Terraform Configuration

Configure how Atmos executes Terraform and OpenTofu commands, including the base path for components, auto-approve behavior, backend file generation, and initialization options.

Disambiguation

The term "Terraform" is used in this documentation to refer to generic concepts such as providers, modules, stacks, the HCL-based domain-specific language and its interpreter. Atmos works with both Terraform and OpenTofu.

Configuration

atmos.yaml

components:
  terraform:
    # Executable to run (terraform, tofu, or absolute path)
    command: terraform

    # Base path to Terraform components
    base_path: components/terraform

    # Automatically add -auto-approve to apply commands
    apply_auto_approve: false

    # Run terraform init before deploy
    deploy_run_init: true

    # Add -reconfigure to init commands
    init_run_reconfigure: true

    # Generate backend.tf.json from stack configuration
    auto_generate_backend_file: true

    # Generate files from the `generate` section before terraform commands
    auto_generate_files: false

    # Init command options
    init:
      pass_vars: false

    # Plan command options
    plan:
      skip_planfile: false

    # Provider plugin caching (enabled by default)
    plugin_cache: true
    plugin_cache_dir: ""  # Uses ~/.cache/atmos/terraform/plugins by default

    # Registry cache proxy (disabled by default)
    cache:
      enabled: false
      location: ""  # Uses ~/.cache/atmos/terraform/registry by default

    # Interactive shell configuration
    shell:
      prompt: "Terraform Shell"

Configuration Reference

command

Specifies the executable to run for Terraform commands. Defaults to terraform.

Environment variable: ATMOS_COMPONENTS_TERRAFORM_COMMAND Command-line flag: --terraform-command

Examples:

• terraform - Use Terraform from PATH
• tofu - Use OpenTofu from PATH
• /usr/local/bin/terraform-1.8 - Use specific version
• /usr/local/bin/tofu-1.7.1 - Use specific OpenTofu version

base_path

Directory containing Terraform component directories. Supports absolute and relative paths.

Environment variable: ATMOS_COMPONENTS_TERRAFORM_BASE_PATH Command-line flag: --terraform-dir

apply_auto_approve

When true, Atmos adds -auto-approve to terraform apply commands, skipping the confirmation prompt.

Environment variable: ATMOS_COMPONENTS_TERRAFORM_APPLY_AUTO_APPROVE Default: false

deploy_run_init

When true, Atmos runs terraform init before executing atmos terraform deploy.

Environment variable: ATMOS_COMPONENTS_TERRAFORM_DEPLOY_RUN_INIT Command-line flag: --deploy-run-init Default: true

init_run_reconfigure

When true, Atmos adds -reconfigure to terraform init commands, updating backend configuration.

Environment variable: ATMOS_COMPONENTS_TERRAFORM_INIT_RUN_RECONFIGURE Command-line flag: --init-run-reconfigure Default: true

auto_generate_backend_file

When true, Atmos generates backend.tf.json from stack configuration before running Terraform commands.

Environment variable: ATMOS_COMPONENTS_TERRAFORM_AUTO_GENERATE_BACKEND_FILE Command-line flag: --auto-generate-backend-file Default: true

auto_generate_files

When true, Atmos generates files from the generate section in stack configuration before running Terraform commands.

Environment variable: ATMOS_COMPONENTS_TERRAFORM_AUTO_GENERATE_FILES Default: false

init.pass_vars

When true, Atmos passes the generated varfile to terraform init using --var-file. This is primarily useful with OpenTofu, which supports passing varfiles to init for dynamic backend configuration.

This also applies to the implicit init that Atmos runs while resolving a component referenced through !terraform.output or atmos.Component — its vars are forwarded as TF_VAR_* environment variables so that modules with init-time variable dependencies (for example, a module version bound to a var) can initialize.

Environment variable: ATMOS_COMPONENTS_TERRAFORM_INIT_PASS_VARS Command-line flag: --init-pass-vars Default: false

plan.skip_planfile

When true, Atmos skips creating a plan file during terraform plan. The plan output is shown but not saved.

Environment variable: ATMOS_COMPONENTS_TERRAFORM_PLAN_SKIP_PLANFILE Command-line flag: --skip-planfile Default: false

plugin_cache

When true, Atmos enables Terraform provider plugin caching by automatically setting TF_PLUGIN_CACHE_DIR. This improves performance by reusing downloaded providers across components, reducing init times and network bandwidth.

This is Terraform's own provider cache and is independent of the registry cache (cache). The plugin cache stores provider plugins that Terraform manages itself; the registry cache is an Atmos-managed proxy that caches both provider and module registry traffic. The two are separate layers and can be used together.

When caching is enabled, Atmos also sets TF_PLUGIN_CACHE_MAY_BREAK_DEPENDENCY_LOCK_FILE=true as required by Terraform.

If TF_PLUGIN_CACHE_DIR is already set in your environment or via the global env: section in atmos.yaml, Atmos does not override it—you manage your own cache.

Environment variable: ATMOS_COMPONENTS_TERRAFORM_PLUGIN_CACHE Default: true

plugin_cache_dir

Custom directory path for the Terraform plugin cache. If empty (default), Atmos uses the XDG cache directory: ~/.cache/atmos/terraform/plugins.

Environment variable: ATMOS_COMPONENTS_TERRAFORM_PLUGIN_CACHE_DIR Default: "" (uses XDG cache directory)

auto_provision_workdir_for_outputs

When true (default), Atmos automatically provisions the JIT working directory for components with provision.workdir.enabled: true before running terraform init during !terraform.output or atmos.Component evaluation. This enables cross-component output references to work on any machine, including fresh CI runners where the workdir has not been created yet.

Set to false to disable auto-provisioning. terraform init will still run, but only if the workdir has already been created by a prior deploy; on a fresh machine with no prior workdir it will fail.

For state-only reads, prefer !terraform.state — it reads the state file directly with no terraform init, no workdir provisioning step, and no terraform binary required.

Environment variable: ATMOS_COMPONENTS_TERRAFORM_AUTO_PROVISION_WORKDIR_FOR_OUTPUTS Default: true

shell.prompt

Custom prompt to display when running atmos terraform shell.

Using OpenTofu

To use OpenTofu instead of Terraform, set the command to tofu:

atmos.yaml

components:
  terraform:
    command: tofu
    base_path: components/terraform

OpenTofu supports additional features like passing variables to init for dynamic backend configuration:

atmos.yaml

components:
  terraform:
    command: tofu
    init:
      pass_vars: true

CLI Configuration (rc)

The rc section declares the Terraform/OpenTofu CLI configuration (.terraformrc / .tofurc). Atmos renders it and exposes it to the subprocess via TF_CLI_CONFIG_FILE and TOFU_CLI_CONFIG_FILE — no hand-managed dotfiles. It is a near-opaque passthrough: keys map directly to CLI-config directives, so new directives work without an Atmos release.

enabled

Enable rendering of the CLI configuration. Defaults to false.

(remaining keys)

Rendered verbatim into Terraform's native CLI config (HCL): provider_installation, host, credentials, plugin_cache_dir, etc.

components:
  terraform:
    rc:
      enabled: true
      provider_installation:
        - network_mirror:
            url: "https://terraform-mirror.example.com/"
        - direct:
            exclude:
              - "registry.terraform.io/hashicorp/*"

If you already manage your own CLI config (via TF_CLI_CONFIG_FILE, TOFU_CLI_CONFIG_FILE, or the legacy TERRAFORM_CONFIG), Atmos detects it and defers to you.

Registry Cache (cache)

The cache section enables the Terraform registry cache — transparent provider and module caching via an ephemeral local network-mirror proxy. It is execution-environment (runner) configuration that merges through the stack hierarchy.

This is not the same as Terraform's plugin_cache: the registry cache is an Atmos-managed proxy that caches both provider and module registry traffic (default root ~/.cache/atmos/terraform/registry), whereas plugin_cache is Terraform's own provider plugin cache (~/.cache/atmos/terraform/plugins). They are independent layers.

enabled

Enable the registry cache. Defaults to false.

Environment variable:ATMOS_COMPONENTS_TERRAFORM_CACHE_ENABLED

location

Cache root. Defaults to the XDG cache directory under terraform/registry.

Environment variable:ATMOS_COMPONENTS_TERRAFORM_CACHE_LOCATION

backend.type

Storage backend. filesystem (default).

metadata_ttl

Time-to-live for registry metadata (Go duration). Defaults to 24h.

stale_while_revalidate

Window during which stale metadata may be served while revalidating (Go duration). Defaults to 168h.

mirror.enabled

Express fleet pre-seeding policy. The cache mirror command runs regardless. Defaults to false.

Target platforms are configured at the project level via platforms (not under cache), since the same list also drives multi-platform lock completion.

components:
  terraform:
    platforms:
      - linux_amd64
      - darwin_arm64
      - windows_amd64
    cache:
      enabled: true
      metadata_ttl: 24h
      stale_while_revalidate: 168h

Manage the cache with atmos terraform cache list|stats|prune|delete|mirror.

Platforms (platforms)

components.terraform.platforms is the list of target platforms a project builds for, as <os>_<arch> (e.g. linux_amd64, darwin_arm64). A single list drives two things:

Eager pre-seeding

The lazy proxy only caches the platform Terraform requests at run time (your host's). Run atmos terraform cache mirror to pre-fetch every platform in platforms into the same cache directory — for mixed CI/developer fleets or air-gapped bundles.

Complete lock files

When a customized provider installation method is active (Terraform's default plugin_cache, or the registry cache), init writes a .terraform.lock.hcl with checksums for only the host platform and warns "Incomplete lock file information for providers". With platforms declared, Atmos runs providers lock after init to complete the lock for every platform, so a committed lock installs cleanly across a fleet.

components:
  terraform:
    platforms:
      - linux_amd64
      - darwin_arm64
      - windows_amd64

For ephemeral or vendored components (provision.workdir or a source:) the canonical .terraform.lock.hcl has no committable home, so Atmos keeps the committed lock per instance as .<stack>-<component>.terraform.lock.hcl — restored into the working directory before init and persisted after. Keep canonical **/.terraform.lock.hcl ignored and un-ignore !**/.*-*.terraform.lock.hcl in .gitignore. Plain in-repo components keep committing the canonical lock as usual.

Generated Files

When auto_generate_backend_file is enabled, Atmos generates a backend.tf.json file in each component directory. Add this to your .gitignore:

# Atmos generated files
backend.tf.json

Related Commands

atmos terraform

Execute Terraform/OpenTofu commands

atmos terraform plan

Generate and show execution plan

atmos terraform apply

Apply infrastructure changes

atmos terraform deploy

Run init, plan, and apply in sequence

atmos terraform shell

Open an interactive shell

atmos terraform generate backends

Generate backend configuration files

atmos terraform generate varfiles

Generate variable files

atmos terraform generate files

Generate auxiliary configuration files

Related

• Component Configuration Overview
• Stack Configuration
• Terraform Components
• Terraform Backend
• Generate Terraform Files