Skip to main content

Terraform Stack Configuration

This reference documents the complete stack configuration schema for Terraform components in Atmos. Use this to configure variables, metadata, settings, and environment variables for your Terraform root modules.

Schema​

The schema of an Atmos Terraform Component in an Atmos Stack is as follows:

components:
  terraform:
    # the slug of the component
    example:

      # configuration specific to atmos
      metadata:
        # Components can be of type "real" (default) or "abstract"
        type: real
        # This is the directory path of the component.
        # In this example, we're referencing a component in the `components/terraform/stable/example` folder.
        component: stable/example

        # We can leverage multiple inheritance to sequentially deep merge multiple configurations
        inherits:
          - example-defaults

      # Settings are where we store configuration related to integrations.
      # It's a freeform map; anything can be placed here.
      settings:
        spacelift: {}

      # Define the terraform variables, which will get deep-merged and exported to a `.tfvars` file by atmos.
      vars:
        enabled: true
        name: superduper
        nodes: 10

      # Environment variables to set when running Terraform
      env:
        TF_LOG: DEBUG

Attributes​

vars (optional)

The vars section is a free-form map of Terraform variables. These are deep-merged and exported to a .tfvars file by Atmos. Use component validation to enforce policies.

Example:

vars:
  enabled: true
  name: my-vpc
  cidr_block: "10.0.0.0/16"
metadata (optional)

The metadata section extends functionality of the component. See Common Component Attributes for details on type, enabled, locked, and component.

Terraform-specific metadata:

  • metadata.inherits - List of component configurations to inherit from
  • metadata.component - Path to the Terraform root module (relative to components.terraform.base_path)

Example:

metadata:
  type: real
  component: vpc/v2
  inherits:
    - vpc-defaults
settings (optional)

The settings block is a free-form map used to pass configuration information to integrations like Spacelift, Atlantis, or GitHub Actions.

Example:

settings:
  spacelift:
    workspace_enabled: true
    stack_destructor_enabled: false
  atlantis:
    enabled: true
env (optional)

Environment variables to set when running Terraform commands. Useful for configuring Terraform behavior or passing credentials.

Example:

env:
  TF_LOG: DEBUG
  AWS_PROFILE: production

Context Variables​

These are Cloud Posse's terraform-null-label conventions for organizing infrastructure:

vars.namespace (optional)

The namespace of all stacks. Typically, there will be one namespace for the organization.

Example:

vars:
  namespace: acme
vars.tenant (optional)

In a multi-tenant configuration, the tenant represents a single tenant. By convention, we typically recommend that every tenant have its own Organizational Unit (OU).

Example:

vars:
  tenant: platform
vars.stage (optional)

The stage is where workloads run. See our glossary for disambiguation.

Example:

vars:
  stage: prod
vars.environment (optional)

The environment is used for location where things run. See our glossary for disambiguation.

Example:

vars:
  environment: ue1  # us-east-1

Complete Example​

# stacks/prod/us-east-1/vpc.yaml
import:
  - catalog/vpc/defaults

components:
  terraform:
    vpc:
      metadata:
        type: real
        component: vpc
        inherits:
          - vpc-defaults
      settings:
        spacelift:
          workspace_enabled: true
      vars:
        namespace: acme
        tenant: platform
        environment: ue1
        stage: prod
        name: primary
        cidr_block: "10.0.0.0/16"
        availability_zones:
          - us-east-1a
          - us-east-1b
          - us-east-1c
      env:
        TF_LOG: INFO