Authoring IaC templates for Quake AI

You write OpenTofu or Terraform templates against the OpenStack provider the same way you would on any Antelope-era cloud. Quake AI adds a small, fixed catalog of flavors, networks, and volume types, a second AWS provider path for S3-compatible object storage, and Magnum behaviors that differ from generic OpenStack tutorials. This page collects those rules so a new template matches the infrastructure template library and passes CI validation.

If you are new to IaC on the platform, start with Get started with IaC and IaC on Quake AI. If you know OpenStack but not Quake AI branding, read How Quake AI uses OpenStack first.

What is different on Quake AI#

Quake AI runs Antelope (2023.1). The OpenStack provider resource names (openstack_compute_instance_v2, openstack_networking_port_v2, and the rest) are standard. The differences show up in catalog literals (which flavor and network names resolve), auth (application credentials plus separate S3 keys), and platform limits (Magnum trust rules and no managed VPN).

The platform keeps the decision space small on purpose: 26 public flavors in four families, one boot volume type, two shared external networks, and project-scoped roles instead of IAM policies. Templates that hard-code those literals correctly are easier to validate and less likely to fail tofu plan in a new project.

Authentication and providers#

OpenStack provider#

Authenticate with application credentials, not username and password in HCL. Export the variables from the file you generate in Generate app credentials:

export OS_AUTH_URL="https://keystone.rumble.cloud/v3"
export OS_AUTH_TYPE="v3applicationcredential"
export OS_APPLICATION_CREDENTIAL_ID="YOUR_APP_CREDENTIAL_ID"
export OS_APPLICATION_CREDENTIAL_SECRET="YOUR_APP_CREDENTIAL_SECRET"
export OS_REGION_NAME="us-east-1"

Declare an empty provider block and keep secrets out of .tf files:

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

provider "openstack" {}

Regions: us-east-1, us-east-2, us-west-1. Parameterize the region in endpoint examples when your template README shows object storage URLs.

AWS provider for object storage#

Object storage buckets use the AWS provider pointed at Quake AI's S3-compatible endpoint. The OpenStack application credential does not satisfy the AWS provider. Mint EC2-compatible credentials with the OpenStack CLI and export AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY before tofu plan. The S3 storage template README documents the bootstrap; mirror that pattern in any template that creates buckets.

provider "aws" {
  region                      = var.s3_region
  skip_credentials_validation = true
  skip_metadata_api_check     = true
  skip_requesting_account_id  = true

  endpoints {
    s3 = var.s3_endpoint
  }
}

Catalog literals#

These values come from the live platform catalog. Wrong defaults produce empty data sources on tofu plan even when tofu validate passes.

Link flavor choice to Compute flavors and capacity planning. Shared vCPU sizes (s1a.*) suit demos; dedicated families (m2a, c2a, r2a) suit production workloads.

External network policy#

Quake AI exposes two shared external networks. Pick the default in variables.tf based on what the template teaches:

Readers can override either value in terraform.tfvars. Document which class your template belongs to in the README.

Recommended template skeleton#

Most compute templates in the library follow the same Neutron shape: private network, router on the external network, security group rules, port with security groups attached by ID, boot-from-volume instance, optional floating IP.

data "openstack_images_image_v2" "os" {
  name        = var.image_name
  most_recent = true
}

data "openstack_networking_network_v2" "external" {
  name = var.external_network
}

resource "openstack_networking_network_v2" "private" {
  name           = "${var.instance_name}-net"
  admin_state_up = true
}

resource "openstack_networking_subnet_v2" "private" {
  network_id = openstack_networking_network_v2.private.id
  cidr       = var.private_cidr
  ip_version = 4
}

resource "openstack_networking_router_v2" "main" {
  external_network_id = data.openstack_networking_network_v2.external.id
}

resource "openstack_networking_router_interface_v2" "private" {
  router_id = openstack_networking_router_v2.main.id
  subnet_id = openstack_networking_subnet_v2.private.id
}

resource "openstack_networking_secgroup_v2" "app" {
  name = "${var.instance_name}-sg"
}

resource "openstack_networking_port_v2" "app" {
  network_id         = openstack_networking_network_v2.private.id
  security_group_ids = [openstack_networking_secgroup_v2.app.id]

  depends_on = [openstack_networking_router_interface_v2.private]
}

resource "openstack_compute_instance_v2" "app" {
  flavor_name = var.flavor_name
  key_pair    = var.key_name

  block_device {
    uuid                  = data.openstack_images_image_v2.os.id
    source_type           = "image"
    destination_type      = "volume"
    volume_size           = 20
    boot_index            = 0
    delete_on_termination = true
  }

  network {
    port = openstack_networking_port_v2.app.id
  }
}

resource "openstack_networking_floatingip_v2" "app" {
  pool = var.external_network
}

resource "openstack_networking_floatingip_associate_v2" "app" {
  floating_ip = openstack_networking_floatingip_v2.app.address
  port_id     = openstack_networking_port_v2.app.id
}

Conventions embedded in that skeleton:

• Attach security groups to the port with security_group_ids = [....id]. Avoid security_groups = [....name] on the instance; Nova name lookup can match multiple groups after partial applies.
• Prefix security group and network resource names with var.instance_name or a dedicated prefix variable so repeated applies do not collide with orphaned groups.
• Use openstack_networking_floatingip_associate_v2, not the deprecated openstack_compute_floatingip_associate_v2 resource.
• Wait for the router interface before creating ports that need routing (depends_on as shown).

The simple-vm template in iac/templates/simple-vm/ is the canonical reference implementation.

Variables, secrets, and cloud-init#

Standard variables#

Expose a consistent surface so readers can reuse terraform.tfvars patterns across templates:

Document every variable from variables.tf on the template reference page Parameters table.

SSH keypairs#

Require an existing project keypair via var.key_name. Do not create openstack_compute_keypair_v2 in new templates unless the template explicitly owns key lifecycle and the README states that the private key lands in Terraform state. Prefer the import-key flow from Add an SSH key.

Secrets#

Never commit passwords, API keys, or credential defaults in HCL. Accept secrets through terraform.tfvars (gitignored), CI secret stores, or generated values on the instance via cloud-init.

cloud-init and templatefile#

Use templatefile() for user-data. Do not pass computed resource attributes (for example a floating IP address) into templatefile() variables when that creates a dependency cycle; render those values on the instance or split the bootstrap script.

Platform quirks for template authors#

For the full OpenStack mapping and Console naming, see How Quake AI uses OpenStack.

Validation expectations#

Every template in the library passes tofu validate in CI before it ships. That check confirms the HCL parses and matches the provider schema. It does not mean the template was applied in your project or that your quotas allow the default flavors.

Treat validated OpenTofu templates as a correct starting point. Run tofu plan in your project, adjust flavors and counts for your tier, then apply. For the full validation program, see How the platform validates its content.

See also#

• IaC on Quake AI: OpenTofu and Terraform
• Terraform and OpenTofu on Quake AI
• Get started with IaC
• How to customize a template's image and flavor
• How to add a block volume to a template
• How to parameterize a template with tfvars
• Infrastructure templates