Skip to main content

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

    # 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.

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.

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)

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

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