Terraform and OpenTofu on Quake AI

Terraform and OpenTofu use HashiCorp Configuration Language (HCL) to define infrastructure as code. You describe the resources you want (instances, networks, volumes, security groups) in .tf files, and the tool creates, updates, or destroys them to match your declared state. Both tools use the same OpenStack provider and produce identical results on Quake AI.

For a comparison of OpenTofu and Terraform, see IaC on Quake AI. This page focuses on how Terraform and OpenTofu work with Quake AI specifically: provider configuration, authentication, state management, and the resource types available.

The OpenStack provider#

Terraform and OpenTofu interact with Quake AI through the OpenStack provider. The provider translates HCL resource definitions into OpenStack API calls.

Declare the provider in your main.tf:

terraform {
  required_providers {
    openstack = {
      source  = "terraform-provider-openstack/openstack"
      version = "~> 2.0"
    }
  }
}

provider "openstack" {}

The empty provider "openstack" {} block tells the provider to read credentials from environment variables, which is the recommended approach.

Authentication#

The provider supports two authentication methods. Both use application credentials generated in the Quake AI console.

Environment variables (recommended)#

Source your application credential file before running any Terraform command:

source ~/openrc.sh
terraform plan

The provider reads OS_AUTH_URL, OS_APPLICATION_CREDENTIAL_ID, and OS_APPLICATION_CREDENTIAL_SECRET from the environment. This keeps credentials out of your .tf files and version control.

Explicit provider configuration#

For CI/CD pipelines or environments where sourcing a file is impractical, pass credentials directly:

provider "openstack" {
  auth_url                      = "https://keystone.rumble.cloud/v3"
  application_credential_id     = var.credential_id
  application_credential_secret = var.credential_secret
}

Use Terraform variables or a secrets manager to inject the values; never hardcode credentials in .tf files.

State management#

Terraform tracks the real-world state of your infrastructure in a state file (terraform.tfstate). This file maps each HCL resource to the corresponding OpenStack resource ID, enabling Terraform to detect drift and plan changes accurately.

Local state (default)#

By default, the state file lives in the working directory. This works for personal projects but breaks down when multiple people or CI pipelines manage the same infrastructure.

Remote state on Quake AI#

Store state in Quake AI object storage for team access and state locking:

terraform {
  backend "s3" {
    bucket   = "terraform-state"
    key      = "production/terraform.tfstate"
    endpoint = "https://object.us-east-1.rumble.cloud"  # replace with your region
    region   = "us-east-1"                         # us-east-1 | us-east-2 | us-west-1

    skip_credentials_validation = true
    skip_metadata_api_check     = true
    skip_region_validation      = true
    force_path_style            = true
  }
}

Generate S3 credentials through the console (see Create S3 credentials) and export them as AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY before running terraform init.

Common resource types#

The OpenStack provider maps Quake AI services to Terraform resource types. These are the resources you use most frequently:

Compute#

Network#

Storage#

Public application entry points#

Automation (legacy Heat)#

The plan/apply workflow#

Each infrastructure change follows the same cycle:

1. terraform init: download the OpenStack provider plugin and configure the backend. Run once per project or when you change providers.
2. terraform plan: compare the declared state in your .tf files against the real state in terraform.tfstate. Terraform prints a diff showing what it creates, modifies, or destroys.
3. terraform apply: execute the planned changes. Terraform prompts for confirmation before making any API calls.
4. terraform destroy: tear down all resources managed by the current configuration. Use this to clean up test environments.

Review the plan output before applying. Terraform distinguishes between in-place updates (modifying a resource's attributes) and replacements (destroying and recreating a resource). Replacements can cause downtime; look for forces replacement in the plan output.

Project structure#

A typical Quake AI Terraform project splits configuration across files by concern:

.
├── main.tf           # Provider configuration
├── variables.tf      # Input variables
├── data.tf           # Data sources (images, networks, flavors)
├── compute.tf        # Instance definitions
├── network.tf        # Networks, subnets, routers, security groups
├── storage.tf        # Volumes and attachments
├── outputs.tf        # Output values (IPs, IDs)
└── terraform.tfvars  # Variable values (not committed to version control)

Terraform loads all .tf files in the working directory automatically; the file names are for human organization, not tool requirements.

Operational best practices#

Pin the provider version. Use version = "~> 2.0" to allow patch updates while preventing breaking changes. Run terraform init -upgrade when you want to pick up a new minor version.

Use variables for everything that changes between environments. Instance counts, flavors, network CIDRs, and image names should be variables. Hardcoded values create drift between staging and production.

Use terraform.tfvars for environment-specific values. Keep one .tfvars file per environment and pass it with terraform plan -var-file=production.tfvars.

Never commit terraform.tfstate or .tfvars files. The state file contains resource IDs and may contain sensitive attributes. The .tfvars file may contain credentials. Add both to .gitignore.

Use anti-affinity server groups. When deploying multiple instances of the same role, place them in a soft-anti-affinity server group. This distributes instances across physical hosts for fault tolerance.

Tag resources consistently. Use the tags attribute on networks, ports, and other resources that support it. Tags make it possible to identify Terraform-managed resources in the console and CLI.

Further reading#

On this platform:

• IaC on Quake AI: comparison of OpenTofu and Terraform
• How to create application credentials: generate the credentials Terraform needs
• Simple VM Terraform example: minimal working configuration
• Full-stack Terraform example: multi-tier infrastructure with a self-managed edge proxy
• Validated IaC templates in the template library
• Terraform error handling: diagnose common Terraform failures

External resources:

• OpenStack Terraform provider documentation: full resource and data source reference
• Terraform documentation: language reference, CLI commands, state management
• OpenTofu documentation: open-source fork with identical syntax and provider support