# How to deploy VMs with Terraform (simple example)

Source: https://docs.quake.ai/docs/automation/how-to/terraform-simple
Markdown: https://docs.quake.ai/docs/automation/how-to/terraform-simple.md

---

# How to deploy VMs with Terraform (simple example)


Looking for a ready-to-use template? See the [Simple VM template](/resources/iac-templates/simple-vm) for a parameterized, validated version you can deploy directly.


<PrerequisiteBlock methods={["terraform"]}>

- Familiarity with [Terraform on Quake AI](/docs/automation/concepts/terraform)

</PrerequisiteBlock>

This configuration deploys a scalable set of virtual machines on Quake AI with associated storage, networking, and security.

## Project quota requirements

The defaults in the downloadable zip are sized for the Developer-tier project quota. Apply consumes:

- **1 instance** at `s1a.small` (2 GB RAM).
- **1 floating IP** allocation (the instance attaches directly to `PublicEphemeral`, so no separate FIP is created).
- **2 block volumes** per instance (one OS volume, one data volume).

Confirm the project has the RAM headroom before applying:

```bash
openstack limits show --absolute -f value -c name -c value
```

For production sizing (more VMs or `m2a.xlarge` flavors at 16 GB each), raise `app_vm_count` and `flavor_app` together and request a matching quota raise from the Quake AI operations team. Three `m2a.xlarge` instances total 48 GB RAM, which exceeds the default-tier 32 GB quota.

## Download the code

> [Download the files here.](/files/terraform-simple-vms.zip)

## Codebase structure

The infrastructure is defined across these Terraform files, each responsible for specific components:

- `main.tf` - Core provider configuration and initialization
- `variables.tf` - Variable definitions for customizing the infrastructure
- `outputs.tf` - Output values for verification after apply
- `vms_app.tf` - VM instance configurations
- `volumes_app.tf` - Storage volume definitions
- `securitygroup_app.tf` - Security group rules and configurations
- `keypair.tf` - SSH key pair configuration
- `ports_app.tf` - Network port configurations
- `servergroup_app.tf` - Server group definitions for VM placement
- `data.tf` - Data source definitions

## Component overview

### Provider configuration (main.tf)
The infrastructure uses the OpenStack provider (version 2.0.0). Authentication can be configured either through environment variables or by directly specifying credentials in the provider block.

### Variables and customization (variables.tf)
The infrastructure is configurable through variables including:

- `system_name` - Base name for resource naming
- `app_vm_count` - Number of VMs to deploy (default: 1)
- `flavor_app` - VM instance size (default: s1a.small)
- `image_app` - OS image (default: Ubuntu-22.04)
- `volume_app_os` - OS volume size in GB (default: 10)
- `volume_app` - Additional volume size in GB (default: 10)
- `app_subnet` - Subnet configuration (default: 192.168.1)
- `cloud_network` - Network name (default: PublicEphemeral)
- `keypair` - SSH public key. **No default**: `tofu plan` prompts for a value, and apply refuses to run without one.



For production workloads, create a private network and subnet instead of placing VMs on `PublicEphemeral`. `PublicEphemeral` is a pre-built default public network useful for quick tests: a VM attached directly to it receives a public interface without extra routing setup. Reserve `PublicEphemeral` for short-lived experiments, not for workloads you intend to keep running.



### Virtual machines and storage

- Each VM is created with two volumes:
  - An OS volume for the system
  - An additional volume for data storage
- VMs are configured with network ports and security group rules
- Server groups ensure proper VM placement and distribution

### Networking and security

- Security groups define inbound and outbound traffic rules
- Network ports connect VMs to the specified network
- The infrastructure uses a pre-existing network (PublicEphemeral)

### Access management

- SSH access is configured through keypairs
- Security groups control network access to the VMs

## How it works

1. When applied, Terraform first initializes the OpenStack provider and validates the configuration.
2. It then creates the necessary security groups and rules.
3. Storage volumes are provisioned for each VM.
4. Network ports are created and configured.
5. VMs are launched with the specified image and connected to their volumes and network ports.
6. The server group ensures proper VM distribution across the infrastructure.

## Infrastructure diagram

```ascii
+------------------------+
|     Public Network     |
+------------------------+
           |
+------------------------+
|    Security Groups     |
+------------------------+
           |
     +----------+
     |   VMs    |
     |  (1-N)   |
     +----------+
         |   |
   +-----+   +-----+
   |               |
+--------+    +---------+
| OS Vol |    |Data Vol |
+--------+    +---------+
```

## Usage notes

1. Ensure your OpenStack credentials are configured (see [Generate app credentials](/docs/tools/generate-app-credentials)).
2. Set the `keypair` variable with your public SSH key. The variable has no default, so `tofu plan` will prompt you (or set it via `TF_VAR_keypair`, a `terraform.tfvars` file, or `-var keypair=...`).
3. Adjust the VM count and specifications in `variables.tf` as needed; raise `app_vm_count` and `flavor_app` together for production sizing.
4. Use standard OpenTofu commands to manage the infrastructure:

    - `tofu init`
    - `tofu plan`
    - `tofu apply`
    - `tofu destroy`

## Verify

After `tofu apply` completes, retrieve the new instance addresses and SSH commands from the OpenTofu outputs declared in `outputs.tf`:

```bash
tofu output
tofu output -json ssh_commands
```

You can also confirm the instance is running through the OpenStack CLI:

```bash
openstack server list
openstack server show <instance-name> -c addresses -c status
```

To destroy every resource and release the floating IP:

```bash
tofu destroy
```

## Detailed file descriptions

{/*  vale Quake.HeadingH2Plus = NO  */}
### main.tf
This file serves as the foundation of the infrastructure configuration:

```hcl
terraform {
  required_providers {
    openstack = {
      source = "terraform-provider-openstack/openstack"
      version = "2.0.0"
    }
  }
}

provider "openstack" {
  # Configuration via environment variables or direct credentials
}
```

Key aspects:

- **Provider Block**: Specifies OpenStack as the infrastructure provider with version 2.0.0
- **Authentication**: Supports two methods:

    1. Environment variables (recommended) using OpenStack RC file
    2. Direct credential configuration in the provider block
  
- **Version Pinning**: Explicitly pins the OpenStack provider version to ensure consistency
- **Provider Source**: Uses the official terraform-provider-openstack/openstack source

Best practices implemented:

- Version constraint to prevent unexpected provider updates
- Commented credential placeholders for configuration
- Flexibility in authentication methods

### variables.tf

This file defines all configurable parameters for the infrastructure. Variables are organized into logical groups:

```hcl
# System Identification
variable "system_name" {
  type    = string
  default = "simplevms"
}

# VM Configuration (defaults sized for the Developer-tier project quota)
variable "app_vm_count" {
  type    = string
  default = "1"
}
variable "flavor_app" {
  type    = string
  default = "s1a.small"
}
# ... more variables ...

# Required: SSH public key (no default; apply refuses without a value)
variable "keypair" {
  description = "Public SSH key (ssh-rsa or ssh-ed25519 ...)"
  type        = string
}
```

Variable categories:

1. **System Identification**

    - `system_name`: Base name for resource identification (default: "simplevms")

2. **VM Configuration**

    - `app_vm_count`: Number of VMs to deploy (default: 1; raise with `flavor_app` for production)
    - `flavor_app`: VM size/flavor (default: s1a.small)
    - `image_app`: OS image selection (default: Ubuntu-22.04)

3. **Storage Configuration**

    - `volume_app_os`: Size of OS volume in GB (default: 10)
    - `volume_app`: Size of additional data volume in GB (default: 10)

4. **Network Configuration**

    - `app_subnet`: Subnet CIDR base (default: 192.168.1)
    - `cloud_network`: Network name (default: PublicEphemeral)

5. **Access Configuration**

    - `keypair`: SSH public key for VM access. No default: OpenTofu prompts at plan time and refuses to apply without a value, so a missing key fails fast instead of failing late after creating security groups, ports, and other dependent resources.

Best practices implemented:

- All variables have explicit types defined
- Sensible defaults sized for the default-tier project quota
- Clear grouping and documentation of variables
- Required variables (like `keypair`) ship with no default so missing values surface at plan time

### vms_app.tf

This file defines the core VM instances and their configurations using the OpenStack Compute service:

```hcl
resource "openstack_compute_instance_v2" "server_app" {
  count           = var.app_vm_count
  name            = "${var.system_name}-app-${format("%02d", count.index + 1)}"
  flavor_name     = var.flavor_app
  key_pair        = openstack_compute_keypair_v2.key.name
  # ... configuration continues ...
}
```

Key components:

1. **Instance Configuration**

    - Dynamic instance count based on `app_vm_count`
    - Standardized naming with zero-padded indices (for example, app-01, app-02)
    - VM size defined by `flavor_app` variable
    - SSH key integration for secure access

2. **Network Integration**

    - Security group association for network rules
    - Port assignment from pre-configured network ports

       ```hcl
       network {
         port = openstack_networking_port_v2.app_ports.*.id[count.index]
       }
       ```

3. **Storage Configuration**

    - Boot volume configuration using specified image
    - Volume size defined by `volume_app_os`
    - Automatic volume cleanup on instance termination

       ```hcl
       block_device {
       source_type           = "image"
       destination_type      = "volume"
       delete_on_termination = true
       }
       ```

4. **Availability Management**

    - Server group integration for anti-affinity
    - Ensures VMs are distributed across different compute nodes

     ```hcl
     scheduler_hints {
       group = openstack_compute_servergroup_v2.app_server_group_anti_affinity.id
     }
     ```

Best practices implemented:

- Zero-padded instance numbering for consistent sorting
- Boot from volume configuration for persistence
- Anti-affinity rules for high availability
- Integration with security groups and network ports

### volumes_app.tf

This file manages the additional data volumes for the VMs and their attachments:

```hcl
resource "openstack_blockstorage_volume_v3" "volume_app" {
  count = length(openstack_compute_instance_v2.server_app)
  name  = "${var.system_name}-volumes-app-${format("%02d", count.index + 1)}"
  size  = var.volume_app
}

resource "openstack_compute_volume_attach_v2" "volume_attach_app" {
  count       = length(openstack_compute_instance_v2.server_app)
  instance_id = openstack_compute_instance_v2.server_app.*.id[count.index]
  volume_id   = openstack_blockstorage_volume_v3.volume_app.*.id[count.index]
}
```

Key components:

1. **Volume Creation**

    - Creates additional volumes for data storage
    - Volume count matches the number of VMs
    - Consistent naming scheme with the rest of the infrastructure
    - Size defined by `volume_app` variable

2. **Volume Attachment**

    - Automatically attaches volumes to corresponding VMs
    - Uses instance and volume IDs for proper mapping
    - Maintains one-to-one relationship between VMs and volumes

Best practices implemented:

- Dynamic volume count based on VM instances
- Consistent naming convention with zero-padded indices
- Automatic volume attachment handling
- Clear separation between volume creation and attachment



This is separate from the boot volumes defined in `vms_app.tf`, providing dedicated data storage for each VM.



### securitygroup_app.tf
This file defines the network security rules for the VM instances:

```hcl
resource "openstack_networking_secgroup_v2" "secgroup_app" {
  name = "${var.system_name}-secgrp_app"
}

resource "openstack_networking_secgroup_rule_v2" "secgroup_rule_app_ssh_from_all" {
  direction         = "ingress"
  ethertype         = "IPv4"
  protocol          = "tcp"
  port_range_min    = 22
  port_range_max    = 22
  remote_ip_prefix  = "0.0.0.0/0"
  security_group_id = openstack_networking_secgroup_v2.secgroup_app.id
}
# ... additional rules ...
```

Key components:

1. **Security Group Definition**

    - Creates a named security group for the application
    - Uses consistent naming convention with system name prefix

2. **Ingress Rules**

    - SSH Access (Port 22)
       - Allows remote SSH connections from any IP
    - HTTP Access (Port 80)
       - Enables web traffic on standard HTTP port
    - HTTPS Access (Port 443)
       - Supports secure web traffic
    - ICMP (Ping)
       - Allows basic network connectivity testing

3. **Rule Configuration**

    - All rules are ingress (incoming traffic)
    - IPv4 protocol support
    - Specific port ranges for each service
    - Global access (`0.0.0.0/0`) for all services

Best practices implemented:

- Clear separation of rules by service
- Standard ports for common services
- Basic network connectivity testing enabled
- Consistent rule structure and naming
- Explicit direction and protocol definitions



While this configuration allows access from any IP (`0.0.0.0/0`), in production environments, you might want to restrict access to specific IP ranges for better security.



### keypair.tf

This file manages the SSH key pair used for secure access to the VMs:

```hcl
resource "openstack_compute_keypair_v2" "key" {
  name       = "${var.system_name}-keypair"
  public_key = var.keypair
}
```

Key components:

1. **Keypair Resource**

    - Creates a named keypair in OpenStack
    - Uses consistent naming with system name prefix
    - Imports the public key specified in variables

2. **Integration Points**

    - Referenced by VM instances for SSH access
    - Uses the public key defined in `variables.tf`
    - Enables secure remote access to instances

Best practices implemented:

- Consistent resource naming
- Separation of key material from configuration
- Integration with VM provisioning
- Uses OpenStack's key management system



The actual SSH public key value should be provided through the `keypair` variable in `variables.tf` or through Terraform variables at runtime.



### ports_app.tf
This file manages the network ports for the VM instances:

```hcl
resource "openstack_networking_port_v2" "app_ports" {
  count              = var.app_vm_count
  name               = "${var.system_name}-app_ports-${format("%02d", count.index + 1)}"
  network_id         = data.openstack_networking_network_v2.cloud_network.id
  security_group_ids = [openstack_networking_secgroup_v2.secgroup_app.id]
}
```

Key components:

1. **Port Creation**

    - Creates network ports for each VM instance
    - Dynamic port count based on `app_vm_count`
    - Consistent naming scheme with zero-padded indices

2. **Network Integration**

    - Associates ports with the specified cloud network
    - References network ID from data source
    - Links security groups to ports

3. **Security Integration**

    - Applies security group rules at the port level
    - Direct integration with the application security group

Best practices implemented:

- Dynamic port creation matching VM count
- Consistent resource naming convention
- Security group integration at network level
- Clean separation of networking concerns



These ports are referenced in the VM configuration to provide network connectivity to each instance.



### servergroup_app.tf
This file defines the server group policy for VM placement:

```hcl
resource "openstack_compute_servergroup_v2" "app_server_group_anti_affinity" {
  name     = "${var.system_name}-app_server_group_anti_affinity"
  policies = ["soft-anti-affinity"]
}
```

Key components:

1. **Server Group Definition**
    - Creates a named server group for VM placement
    - Uses consistent naming with system name prefix
    - Implements soft anti-affinity policy

2. **Anti-Affinity Policy**

    - Uses "soft-anti-affinity" for flexible VM distribution
    - Encourages VMs to run on different compute nodes
    - Allows fallback if strict distribution isn't possible

3. **Integration Points**

    - Referenced by VM instances in their scheduler hints
    - Helps OpenStack make intelligent placement decisions
    - Supports high availability goals

Best practices implemented:

- High availability through VM distribution
- Flexible placement with soft anti-affinity
- Consistent resource naming
- Integration with VM scheduling

Note: Soft anti-affinity is preferred over strict anti-affinity as it allows the infrastructure to still function even if perfect distribution isn't possible.

### data.tf

This file defines the data sources used to reference existing OpenStack resources:

```hcl
data "openstack_networking_network_v2" "cloud_network" {
  name = var.cloud_network
}

data "openstack_images_image_v2" "image_app" {
  name = var.image_app
}
```

Key components:

1. **Network Data Source**

    - References existing network by name
    - Uses network name from `cloud_network` variable
    - Provides network ID for port creation

2. **Image Data Source**

    - References VM image by name
    - Uses image name from `image_app` variable
    - Provides image ID for VM creation

3. **Integration Points**

    - Network data used in port configuration
    - Image data used in VM boot volume configuration
    - Enables reuse of existing OpenStack resources

Best practices implemented:

- Separation of data sources from resource creation
- Reuse of existing infrastructure components
- Dynamic resource referencing
{/*  vale Quake.HeadingH2Plus = YES  */}
- Clean integration with variables