Skip to navigation

Terraform

Terraform is a tool that creates, changes and deletes infrastructure from configuration files. You write what you want in .tf files, Terraform shows you a plan of the changes, and nothing happens until you apply it. The IBEE provider, devs-ibee/ibee version 0.9.0 on the Terraform Registry, teaches Terraform to manage IBEE compute, networking, storage, secrets, CDN and Container Registry. It is built on API contract 0.10.0.

When to use Terraform

You want to…Use
Keep infrastructure in version control, review each change, and rebuild the same setup againTerraform (this page)
Run a one-off command or a short scriptThe CLI
Create resources from inside your own programThe SDKs
Top up, read invoices or manage team membersThe portal: the API doesn’t offer these

How it works

  1. You describe resources in .tf files, for example an ibee_vpc with a name and a site.
  2. terraform plan reads your files and the current state of your resources, and lists what it would create, change or delete.
  3. terraform apply makes those changes by calling the IBEE API, and waits for asynchronous work (such as a VM being built) to finish.
  4. Terraform records what it created in a state file, so the next plan knows what already exists. terraform destroy deletes everything in the state.

Before you begin

  • Terraform 1.11 or later (install). Terraform actions, such as ibee_vm_power, need 1.14 or later.
  • An API token for the workspace you want Terraform to manage, with the permissions your resources need. The example below needs Networking → Edit. See Authentication.
  • Your workspace ID. See Find your workspace ID.

Get started

This example creates one VPC (a private network) in the first available networking site, then deletes it.

1

Set your credentials

export IBEE_TOKEN="ibee_prod_key_xxxxxxxxxxxx"
export IBEE_WORKSPACE_ID="907479"

Production is the default. Set IBEE_ENV=dev with a development token to use the development API. Keep the token out of .tf files and source control.

2

Write a configuration

Save this as main.tf in a new, empty directory:

terraform {
required_version = ">= 1.11.0"
required_providers {
ibee = {
source = "devs-ibee/ibee"
version = "~> 0.9.0"
}
}
}
provider "ibee" {}
# Sites where VPCs can be created; keep only the available ones.
data "ibee_network_sites" "all" {}
locals {
site_id = [for s in data.ibee_network_sites.all.sites : s.site_id if s.available][0]
}
resource "ibee_vpc" "example" {
name = "terraform-example"
site_id = local.site_id
}
output "vpc_id" {
value = ibee_vpc.example.id
}
3

Initialize, plan and apply

terraform init
terraform plan
terraform apply

init downloads the provider from the Registry. plan should say Plan: 1 to add, 0 to change, 0 to destroy. Type yes when apply asks.

4

Check the result

terraform output vpc_id

prints the new VPC’s ID. The VPC also appears on the VPC page of the workspace in the portal.

5

Clean up

terraform destroy

Type yes to delete the VPC.

Some resources, such as VMs, volumes and NAT gateways (which give private VMs internet access through a shared public IP), are billed from creation. Review every plan before you apply it.

Provider settings

Every setting can come from the environment, so provider "ibee" {} is enough.

SettingEnvironment variableDefaultNotes
tokenIBEE_TOKEN—Required, here or in the environment
workspace_idIBEE_WORKSPACE_ID—Required, here or in the environment; sent with every request
endpointIBEE_ENDPOINT, then IBEE_BASE_URL, then IBEE_ENVhttps://api.ibee.ai/v1https only (IBEE_ENV=dev uses https://api.ibee.co.in/v1)
request_timeout—90sTime for each HTTP request, as a duration such as 90s
operation_timeout—20mHow long to wait for asynchronous creates and deletes, such as 45m

organization_id is deprecated and unused.

What the provider manages

AreaResources, data sources and actions
Computeibee_cloud_vm, ibee_gpu_vm, snapshots, backup policies and volume attachments; data sources ibee_sites, ibee_compute_plans, ibee_images, ibee_snapshot_storage_plans, ibee_backup_storage_plans; actions ibee_vm_power, ibee_vm_access, ibee_vm_snapshot_restore, ibee_vm_backup_create, ibee_vm_backup_restore, ibee_vm_backup_restore_cancel
Networkingibee_vpc, ibee_vpc_subnet, ibee_vpc_node_attachment, ibee_nat_gateway, ibee_nat_port_forwarding_rule, ibee_reserved_ip, ibee_reserved_ip_attachment, ibee_firewall_group, ibee_firewall_rule, ibee_firewall_attachment, ibee_load_balancer_l4, ibee_load_balancer_l7; data source ibee_network_sites
Storageibee_bucket, ibee_bucket_cors, ibee_bucket_lifecycle, ibee_bucket_notifications, ibee_s3_credential, ibee_block_volume; data source ibee_block_storage_plans
Container Registryibee_container_registry, ibee_container_registry_access_token; data source ibee_container_registries
Secretsibee_secret_store, ibee_secret, ibee_secret_identity, ibee_secret_identity_scope
CDNibee_cdn_distribution, ibee_cdn_domain, ibee_cdn_website; actions ibee_cdn_purge, ibee_cdn_verify_domain

The full list, with every argument, is in the provider documentation.

Paused: Object Storage and Container Registry

The Object Storage and Container Registry APIs are temporarily paused and answer 404 with an empty body. This affects ibee_bucket, ibee_bucket_cors, ibee_bucket_lifecycle, ibee_bucket_notifications, ibee_s3_credential, ibee_container_registry, ibee_container_registry_access_token and the ibee_container_registries data source.

Upgrade to 0.8.0 before you run plan or apply. Provider 0.7.0 and earlier read the paused 404 as “deleted” and drop buckets, registries and S3 credentials from your state. Your data isn’t deleted, but Terraform no longer tracks those resources. 0.8.0 doesn’t restore state that 0.7.0 already dropped.

With 0.8.0, terraform plan fails on these resources with a clear message while the pause lasts, and your state is kept. To plan your other resources, add -refresh=false, so that Terraform doesn’t read these ones.

To upgrade, see Upgrading.

If 0.7.0 already dropped resources from your state

  • During the pause: terraform import fails for buckets, registries and S3 credentials. With local state, terraform state push -force terraform.tfstate.backup restores them and keeps the S3 secret, but only if that backup is the state from just before the drop and nothing else has changed since.
  • After the pause: terraform import works, but an imported S3 credential’s secret stays empty. Keep the secret from your own records, or rotate the credential.

Errors and retries

The provider calls the API and relays its answer. A failed request shows the HTTP status, the server’s code and message, and the request ID. Reads are retried on 429, 502, 503 and 504, up to 3 times, waiting Retry-After or 250 ms doubling each time, at most 30 seconds. Writes are never retried, because after an error the write may already have been applied: check the resource, then run terraform apply again. Asynchronous work is checked every 2 seconds until operation_timeout.

Upgrading

From 0.8 to 0.9: no breaking changes. Change version to "~> 0.9.0" and run terraform init -upgrade. 0.9.0 fixes a plan_id change on ibee_cloud_vm and ibee_gpu_vm: the resize now sends the new plan’s billing_catalog with the VM’s billing_interval term, which the API requires; 0.8.0’s resize was refused with 400.

From 0.7 to 0.8: no breaking changes. Change version to "~> 0.8.0" and run terraform init -upgrade before your next plan or apply. 0.8.0 keeps your state during the Object Storage and Container Registry pause, and adds the actions ibee_vm_backup_create and ibee_vm_backup_restore_cancel.

From 0.6 to 0.7 has breaking changes. Before you change version to "~> 0.7.0" and run terraform init -upgrade:

  • Removed: ibee_billing_eligibility, ibee_block_volume_attachment (attach volumes with ibee_cloud_vm_volume_attachment or ibee_gpu_vm_volume_attachment), the ibee_vm_backup_run action, ibee_bucket_retention (use ibee_bucket.default_retention) and ibee_cdn_origin. Run terraform state rm for these first.
  • ibee_cloud_vm, ibee_gpu_vm: os_type is required. billing_interval is HOURLY or MONTHLY (a one-month commitment) and defaults to HOURLY for new VMs; the provider builds billing_catalog from the plan, as the portal does. delete_public_ip_action has no default: set release or reserve for a VM with an automatically assigned public IP, or destroy fails with 400.
  • ibee_compute_plans, ibee_images: vm_type is required.
  • Volume attachments: set billing_catalog, for example to ibee_block_volume.<name>.billing_catalog.
  • Changes that now replace the resource, because the API has no update for them: ibee_secret_store name and description, ibee_secret_identity token_policy_mode, secret identity scope permissions, and ibee_vpc_subnet name and DNS.
  • Load balancers: set the new tls block for https (for example { mode = "terminate", certificate_source = "managed" }).
  • No provider defaults or checks: settings you leave out aren’t sent, and the API’s values are recorded.
  • New: Container Registry resources; the ibee_block_storage_plans, ibee_snapshot_storage_plans and ibee_backup_storage_plans data sources; ibee_bucket_cors, ibee_bucket_lifecycle and ibee_bucket_notifications are supported again.

From 0.5 to 0.6: no breaking changes. 0.6.0 added the actions ibee_vm_snapshot_restore, ibee_vm_backup_restore, ibee_vm_access and ibee_vm_backup_run (removed again in 0.7), and the resources ibee_secret_identity and ibee_secret_identity_scope.

Troubleshooting

You seeWhat it meansWhat to do
terraform init can’t find devs-ibee/ibeeThe source is mistyped, or the machine can’t reach registry.terraform.ioUse source = "devs-ibee/ibee" and check your network or proxy.
Missing IBEE API token or Missing workspace_idThe environment variable isn’t set in this shellExport IBEE_TOKEN and IBEE_WORKSPACE_ID again, then rerun.
An error that names an action blockYour Terraform is older than 1.14Upgrade Terraform, or remove the action.
HTTP 401 invalid_api_keyIBEE_TOKEN is wrong, cut short, or from the other environmentExport the whole token again; set IBEE_ENV=dev only for an ibee_dev_key_ token.
HTTP 403 insufficient_scopeThe token lacks a permission a resource needsCreate a token with the permission in required_scope.
HTTP 403 workspace_not_allowedThe token is limited to other workspacesUse a token for IBEE_WORKSPACE_ID’s workspace.
HTTP 402 billing_deniedBilling refused a billable createSee Billing refusals.
A timeout while waiting for a resourceThe work took longer than operation_timeout (20 minutes by default)Raise operation_timeout, then run terraform apply again; check the resource in the portal first.
Unsupported argument or Invalid resource type after upgradingConfiguration written for provider 0.6Follow Upgrading.
HTTP 400 when destroying a VMThe VM has an automatically assigned public IP and delete_public_ip_action isn’t setSet delete_public_ip_action = "release" (or "reserve"), apply, then destroy.
HTTP 400 when destroying a VM, with This address is already a Reserved IPThe VM’s IP was converted to a Reserved IP and delete_public_ip_action is setRemove delete_public_ip_action, apply, then destroy. The IP stays in your workspace and keeps billing until you release it from Reserved IPs.
An error that says a public API operation is “temporarily paused”The configuration has an Object Storage or Container Registry resourceSee Paused: Object Storage and Container Registry.
Invalid index on local.site_idNo networking site is available to your organizationCheck the VPC page in the portal, or contact support.