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
How it works
- You describe resources in
.tffiles, for example anibee_vpcwith a name and a site. terraform planreads your files and the current state of your resources, and lists what it would create, change or delete.terraform applymakes those changes by calling the IBEE API, and waits for asynchronous work (such as a VM being built) to finish.- Terraform records what it created in a state file, so the next plan knows what already exists.
terraform destroydeletes 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.
Set your credentials
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.
Initialize, plan and 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.
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.
organization_id is deprecated and unused.
What the provider manages
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 importfails for buckets, registries and S3 credentials. With local state,terraform state push -force terraform.tfstate.backuprestores 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 importworks, 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 withibee_cloud_vm_volume_attachmentoribee_gpu_vm_volume_attachment), theibee_vm_backup_runaction,ibee_bucket_retention(useibee_bucket.default_retention) andibee_cdn_origin. Runterraform state rmfor these first. ibee_cloud_vm,ibee_gpu_vm:os_typeis required.billing_intervalisHOURLYorMONTHLY(a one-month commitment) and defaults toHOURLYfor new VMs; the provider buildsbilling_catalogfrom the plan, as the portal does.delete_public_ip_actionhas no default: setreleaseorreservefor a VM with an automatically assigned public IP, or destroy fails with400.ibee_compute_plans,ibee_images:vm_typeis required.- Volume attachments: set
billing_catalog, for example toibee_block_volume.<name>.billing_catalog. - Changes that now replace the resource, because the API has no update for them:
ibee_secret_storename and description,ibee_secret_identitytoken_policy_mode, secret identity scope permissions, andibee_vpc_subnetname and DNS. - Load balancers: set the new
tlsblock forhttps(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_plansandibee_backup_storage_plansdata sources;ibee_bucket_cors,ibee_bucket_lifecycleandibee_bucket_notificationsare 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
Related pages
- Provider documentation on the Terraform Registry
- Terraform examples: a web app, a private network, a static site, and storage with secrets
- Provider source on GitHub
- Authentication: tokens and permissions
- Asynchronous operations: what
operation_timeoutwaits for
