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

    # Deprecated: use init.reconfigure instead
    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:
      # Skip init when nothing that affects it has changed (auto | always | never)
      mode: auto
      # Add -reconfigure only when the backend changed (auto | always | never)
      reconfigure: auto
      # Add -upgrade only when Terraform/OpenTofu says it's required (auto | always | never)
      upgrade: auto
      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

    # Streaming UI mode for real-time progress
    ui:
      enabled: false

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

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

    # Default values for terraform CLI execution flags
    flags:
      lock_timeout: ""   # e.g. "5m" — retry a held state lock instead of failing fast
      lock: null         # unset — terraform's own default (true) applies
      parallelism: null  # unset — terraform's own default (10) applies
      refresh: null      # unset — terraform's own default (true) applies
      compact_warnings: false

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 (deprecated)

Deprecated in favor of init.reconfigure (see Configuration Reference below). When init.reconfigure is not explicitly set (at any precedence level), Atmos maps this legacy boolean: false behaves as init.reconfigure: never, and the default true behaves as init.reconfigure: auto — not always. This is the one behavior change existing projects relying on the old default will see: Atmos no longer adds -reconfigure to every init by default. Set init.reconfigure: always explicitly to keep the previous unconditional behavior.

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

init.mode, init.reconfigure, init.upgrade

Control whether and how Atmos runs terraform init automatically before other commands, before deploy (when deploy_run_init is enabled), and before resolving !terraform.output or atmos.Component. All three accept auto, always, or never, and all three default to auto for unpinned projects and projects pinned to a config edition on or after September 12, 2026; pinning an earlier edition restores always for init.mode and never for init.upgrade (Atmos's pre-this-setting behavior for each) with no config changes.

init.mode — auto skips terraform init when nothing that affects it (root .tf/.tofu files, .terraform.lock.hcl, the CLI configuration, the resolved binary, relevant environment variables, and — when init.pass_vars is true — the varfile) has changed since the last successful init, and the working directory still looks initialized. always restores the previous unconditional behavior. never disables the ordinary implicit init — but unlike --skip-init, it does not suppress the always-forced reconfigure init that atmos terraform workspace select/new needs; --skip-init suppresses init unconditionally, including for workspace.
init.reconfigure — auto adds -reconfigure only when the backend configuration changed since the last init, on the first init, after a JIT working directory is re-provisioned, or for atmos terraform workspace. always adds it to every init. never never adds it.
init.upgrade — auto (default) adds -upgrade only when Terraform or OpenTofu reports that an upgrade is required (for example, a provider version constraint was raised beyond the locked version). never never adds it — set this to opt out of automatic upgrades. always adds it to every init.

If a skipped init turns out to have been wrong — a nested module changed, or .terraform was altered by hand — Terraform/OpenTofu fails with a diagnostic (e.g. "Backend initialization required", "Required plugins are not installed") before touching state. Atmos recognizes these diagnostics, runs the init it should have run (adding -reconfigure/-upgrade when the diagnostic calls for it and the setting isn't never), and retries the command once. No retry happens when init was explicitly disabled (--skip-init, init.mode: never, deploy_run_init: false). Atmos never runs -migrate-state as part of this recovery. See Automatic Initialization for the full behavior.

An explicit atmos terraform init invocation always runs, regardless of these settings, and refreshes the cached fingerprint. Deleting .terraform (including with atmos terraform clean) forces a fresh init on the next command.

Environment variables: ATMOS_COMPONENTS_TERRAFORM_INIT_MODE, ATMOS_COMPONENTS_TERRAFORM_INIT_RECONFIGURE, ATMOS_COMPONENTS_TERRAFORM_INIT_UPGRADE Command-line flags: --init-mode, --init-reconfigure, --init-upgrade Default: auto for all three

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

planfiles

Configures planfile storage and drift verification for CI pipelines. Storage is opt-in: when this section is absent, planfile upload, download, and verification are skipped (and an explicit --verify-plan request errors, since there is no stored plan to verify against).

components:
  terraform:
    planfiles:
      stores:
        github:
          type: github/artifacts
      priority: [github]
      verify: fail

planfiles.stores

Named store definitions. Each store has a type (github/artifacts, aws/s3, or local/dir) and backend-specific options.

planfiles.default

Name of the store to use when no priority list is set.

planfiles.priority

Ordered list of store names to try in turn for upload and download.

planfiles.verify

Drift-verification behavior on deploy: fail (default under CI), warn, or off. Precedence is CLI flag (--verify-plan / --verify-plan=false) > config > CI default.

Environment variable (per-run override): ATMOS_TERRAFORM_VERIFY_PLAN

planfiles.required

Whether a stored planfile must exist for deploy to proceed. Unset, it tracks verify strictness (required when verification resolves to fail).

See Planfile Storage for backend configuration and Terraform Planfiles for verification semantics.

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)

ui.enabled

When true, Atmos displays a streaming terminal UI during terraform plan, apply, deploy, init, and destroy commands. The UI shows real-time resource status with progress indicators, similar to Docker build output.

refresh doesn't support the streaming UI (Terraform's refresh doesn't emit the structured -json output it depends on); passing --ui with refresh prints a warning and falls back to standard output.

The streaming UI automatically disables when:

Output is piped or redirected (no TTY)
Running in CI environments (CI=true)
Using commands that don't support JSON streaming (refresh)

--ui is rejected with an error (not a silent fallback) when combined with --max-concurrency greater than 1: concurrently-scheduled components would each try to take over the same terminal with their own full-screen UI session. Use --max-concurrency 1 (the default) with --ui, or drop --ui to run components concurrently.

Environment variable: ATMOS_TERRAFORM_UI Command-line flag: --ui Default: false

Example output during apply:

⠋ apply plat-ue2-dev/vpc
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 40% (2/5) 12.3s

  ✓ Created  aws_vpc.main (2.1s)
  ✓ Created  aws_subnet.public[0] (1.3s)
  ⠋ Creating aws_security_group.default (5.2s)
  ○ Pending  aws_instance.web[0]

On completion, output condenses to a summary:

✓ Apply plat-ue2-dev/vpc completed (15.2s)

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.

Flags (`flags`)

components.terraform.flags sets fleet-wide default values for Terraform CLI execution flags — most importantly -lock-timeout, which controls how long Terraform retries a held state lock before failing. Terraform's own default is 0s (fail immediately), which causes avoidable failures when concurrent pipelines (e.g. a CI matrix, or multiple engineers) touch the same component's state around the same time. Declaring a lock_timeout here means every plan/apply/destroy/refresh/import picks it up automatically, without retyping -lock-timeout=<duration> on every invocation.

components:
  terraform:
    flags:
      lock_timeout: "5m"
      parallelism: 10
      refresh: true
      compact_warnings: true

The same flags: block can also be set at the stack level (a root-level terraform: block, sibling to components:, applying to every terraform component in that stack or import) and per component (inside a specific component's definition), overriding the fleet-wide default field-by-field:

# stack manifest
terraform:
  flags:
    lock_timeout: "5m"    # applies to every terraform component in this stack

components:
  terraform:
    vpc:
      flags:
        lock_timeout: "10m"  # overrides the stack-wide default just for this component

Precedence (lowest to highest): Terraform's own built-in default < atmos.yaml components.terraform.flags < an ATMOS_COMPONENTS_TERRAFORM_FLAGS_* environment variable (overrides the atmos.yaml value) < stack-level terraform.flags < a component's own flags: block < an explicit CLI-typed flag (e.g., atmos terraform plan vpc -s plat-ue2-dev -- -lock-timeout=30s), which always wins.

Not every flag applies to every subcommand — Atmos only injects a flag where Terraform actually supports it:

flags.lock_timeout

Default value for -lock-timeout (e.g. "30s", "5m"). Applies to plan, apply, destroy, refresh, and import.

Environment variable: ATMOS_COMPONENTS_TERRAFORM_FLAGS_LOCK_TIMEOUT Default: unset (Terraform's own 0s applies)

flags.lock

Default value for -lock. Applies to plan, apply, destroy, refresh, and import.

Environment variable: ATMOS_COMPONENTS_TERRAFORM_FLAGS_LOCK Default: unset (Terraform's own true applies)

flags.parallelism

Default value for -parallelism. Applies to plan, apply, destroy, and refresh. Not supported by terraform import.

Environment variable: ATMOS_COMPONENTS_TERRAFORM_FLAGS_PARALLELISM Default: unset (Terraform's own 10 applies)

flags.refresh

Default value for -refresh. Applies to plan, apply (only when not consuming a pre-built plan — Terraform rejects -refresh on apply <planfile>), and destroy. Not supported by terraform refresh itself or terraform import.

Environment variable: ATMOS_COMPONENTS_TERRAFORM_FLAGS_REFRESH Default: unset (Terraform's own true applies)

flags.compact_warnings

Default value for -compact-warnings. Applies to plan, apply, destroy, and refresh. Not supported by terraform import.

Environment variable: ATMOS_COMPONENTS_TERRAFORM_FLAGS_COMPACT_WARNINGS Default: false

For a one-off override without changing configuration, pass the raw Terraform flag directly on the command line — it always wins over every layer above:

atmos terraform plan vpc -s plat-ue2-dev -- -lock-timeout=30s

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

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

Configuration​

Configuration Reference​

Using OpenTofu​

CLI Configuration (rc)​

Registry Cache (cache)​

Platforms (platforms)​

Flags (flags)​

Generated Files​

Related Commands​

Related​

Configuration

Configuration Reference

Using OpenTofu

CLI Configuration (`rc`)

Registry Cache (`cache`)

Platforms (`platforms`)

Flags (`flags`)

Generated Files

Related Commands

Related