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

:::note 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

**File:** `atmos.yaml`

```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`](/cli/commands/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`](/stacks/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](https://opentofu.org/docs/cli/commands/init/#general-options) for dynamic backend configuration.

  This also applies to the implicit `init` that Atmos runs while resolving a component referenced through [`!terraform.output`](/functions/yaml/terraform.output) or [`atmos.Component`](/functions/template/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.

  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`](/cli/commands/terraform/shell).

## Using OpenTofu

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

**File:** `atmos.yaml`

```yaml
components:
  terraform:
    command: tofu
    base_path: components/terraform
```

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

**File:** `atmos.yaml`

```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`:

```gitignore
# Atmos generated files
backend.tf.json
```

## Related Commands

## Related

- [Component Configuration Overview](/cli/configuration/components)
- [Stack Configuration](/cli/configuration/stacks)
- [Terraform Components](/components/terraform)
- [Terraform Backend](/stacks/backend)
- [Generate Terraform Files](/stacks/generate)