Configure OpenTofu

Atmos natively supports OpenTofu, similar to the way it supports Terraform. It's compatible with every version of opentofu and designed to work with multiple different versions of it concurrently, and can even work alongside with HashiCorp Terraform.

You will learn

• How to configure Atmos to use OpenTofu for Terraform components
• How to alias terraform to tofu in Atmos
• How to configure OpenTofu for only specific components

Please see the complete configuration options for Terraform, as they are the same for OpenTofu. We'll focus only on what's different in this document, in order to utilize OpenTofu. Keep in mind that Atmos does not handle the downloading or installation of OpenTofu; it assumes that any required binaries for the commands are already installed on your system.

Additionally, if using Spacelift together with Atmos, make sure you review the Spacelift Integration to make any necessary changes.

CLI Configuration

All the default configuration settings to support OpenTofu are defined in the Atmos CLI Configuration, but can also be overridden at any level of the Stack configuration.

components:
  terraform:
    # The executable to be called by `atmos` when running Terraform commands
    command: "/usr/bin/tofu"  # or just `tofu`
    # Can also be set using 'ATMOS_COMPONENTS_TERRAFORM_BASE_PATH' ENV var, or '--terraform-dir' command-line argument
    # Supports both absolute and relative paths
    base_path: "components/tofu"
    # Can also be set using 'ATMOS_COMPONENTS_TERRAFORM_APPLY_AUTO_APPROVE' ENV var
    apply_auto_approve: false
    # Can also be set using 'ATMOS_COMPONENTS_TERRAFORM_DEPLOY_RUN_INIT' ENV var, or '--deploy-run-init' command-line argument
    deploy_run_init: true
    # Can also be set using 'ATMOS_COMPONENTS_TERRAFORM_INIT_RUN_RECONFIGURE' ENV var, or '--init-run-reconfigure' command-line argument
    init_run_reconfigure: true
    # Can also be set using 'ATMOS_COMPONENTS_TERRAFORM_AUTO_GENERATE_BACKEND_FILE' ENV var, or '--auto-generate-backend-file' command-line argument
    auto_generate_backend_file: false
    # Can also be set using 'ATMOS_COMPONENTS_TERRAFORM_APPEND_USER_AGENT' ENV var, or '--append-user-agent' command-line argument
    append_user_agent: "Acme/1.0 (Build 1234; arm64)"
    init:
      # Can also be set using 'ATMOS_COMPONENTS_TERRAFORM_INIT_PASS_VARS' ENV var, or '--init-pass-vars' command-line argument
      pass_vars: true

components.terraform.command

The executable to be called by Atmos when running OpenTofu commands

components.terraform.base_path

The root directory where the OpenTofu components and configurations are located. This path serves as the starting point for resolving any relative paths within the OpenTofu setup.

components.terraform.apply_auto_approve

if set to true, Atmos automatically adds the -auto-approve option to instruct Terraform to apply the plan without asking for confirmation when executing terraform apply command

components.terraform.deploy_run_init

if set to true, Atmos runs terraform init before executing atmos terraform deploy command

components.terraform.init_run_reconfigure

if set to true, Atmos automatically adds the -reconfigure option to update the backend configuration when executing terraform init command

components.terraform.auto_generate_backend_file

if set to true, Atmos automatically generates the Terraform backend file from the component configuration when executing terraform plan and terraform apply commands

components.terraform.init.pass_vars

if set to true, Atmos automatically passes the generated varfile to the tofu init command using the --var-file flag. OpenTofu supports passing a varfile to init to dynamically configure backends

To make OpenTofu the default command when running "terraform", modify atmos.yaml to configure the following global settings:

components:
  terraform:
    # Use the `tofu` command when calling "terraform" in Atmos.
    command: "/usr/bin/tofu"  # or just `tofu`

    # Optionally, specify a different path for OpenTofu components
    base_path: "components/tofu"

Disambiguation

Atmos consistently utilizes the terraform keyword across all configurations, rather than tofu or opentofu. 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.

Additionally, if you prefer to run atmos tofu instead of atmos terraform, you can configure an alias. Just add the following configuration somewhere in the atmos.yaml CLI config file:

aliases:
  tofu: terraform

important

Creating aliases for tofu only changes the CLI invocation of atmos terraform and does not directly influence the actual command that atmos executes when running Terraform. Atmos strictly adheres to the specific command set in the Stack configurations.

Stack Configuration for Components

Settings for Terraform or OpenTofu can also be specified in stack configurations, where they are compatible with inheritance. This feature allows projects to tailor behavior according to individual component needs.

While defaults for everything are defined in the atmos.yaml, the same settings, can be overridden by Stack configurations at any level:

• terraform
• components.terraform
• components.terraform._component_

For instance, you can modify the command executed for a specific component by overriding the command parameter. This flexibility is particularly valuable for gradually transitioning to OpenTofu or managing components that are compatible only with HashiCorp Terraform.

components:
  terraform:
    vpc:
      command: "/usr/local/bin/tofu-1.7"

Example: Provision a Terraform Component with OpenTofu

note

In the following examples, we'll assume that tofu is an Atmos alias for the terraform command.

aliases:
  tofu: terraform

Once you've configured Atmos to utilize tofu — either by adjusting the default terraform.command in the atmos.yaml or by specifying the command for an individual component — provisioning any component follows the same procedure as you would typically use for Terraform.

For example, to provision a Terraform component using OpenTofu, run the following commands:

atmos tofu plan eks --stack=ue2-dev
atmos tofu apply eks --stack=ue2-dev

where:

• eks is the Terraform component to provision (from the components/terraform folder)
• --stack=ue2-dev is the stack to provision the component into

Short versions of all command-line arguments can be used:

atmos tofu plan eks -s ue2-dev
atmos tofu apply eks -s ue2-dev

OpenTofu 1.8+ Module Source Interpolation

OpenTofu 1.8.0 introduced support for variable interpolation in module source attributes, enabling dynamic module paths based on configuration. This feature is OpenTofu-specific and is not supported in HashiCorp Terraform.

Automatic Support

Atmos automatically detects when you're using OpenTofu (by checking if your command contains "tofu" or by executing the version command) and handles OpenTofu-specific syntax gracefully. No additional configuration is required.

Example: Dynamic Module Sources

components/terraform/my-component/main.tf

variable "context" {
  type = object({
    build = object({
      module_path    = string
      module_version = string
    })
  })
  description = "Context for dynamic module loading"
}

module "dynamic_module" {
  source = "${var.context.build.module_path}"

  # Module inputs
  name = "example"
}

stacks/catalog/my-component.yaml

components:
  terraform:
    my-component:
      vars:
        context:
          build:
            module_path: "./modules/example"
            module_version: "v1.0.0"

How It Works

When you configure command: "tofu" in your atmos.yaml, Atmos:

1. Auto-detects OpenTofu using a two-tier strategy:

   • Fast path: Checks if the executable basename contains "tofu"
   • Slow path: Executes <command> version and checks for "OpenTofu"
   • Caches results for performance

2. Skips incompatible validation for known OpenTofu-specific features:

   • Module source variable interpolation
   • Other OpenTofu 1.8+ syntax extensions

3. Still catches real errors - Only skips validation for known OpenTofu patterns, ensuring actual syntax errors are still reported

Supported Command Patterns

Atmos recognizes OpenTofu through any of these command configurations:

• command: "tofu" - Simple executable name
• command: "/usr/bin/tofu" - Absolute path
• command: "/opt/homebrew/bin/tofu" - Homebrew installation
• command: "/Users/user/.asdf/shims/tofu" - asdf-managed
• command: "/path/to/custom/tofu" - Custom installation

Requirements for Module Source Interpolation

To use variable interpolation in module sources with OpenTofu, you must:

1. Configure the OpenTofu command:

   atmos.yaml

   components:
     terraform:
       command: "tofu"  # or any path containing "tofu"

2. Enable passing variables to init (required for module source interpolation):

   atmos.yaml

   components:
     terraform:
       init:
         pass_vars: true

3. Use OpenTofu 1.8.0 or later

Migration from Terraform

If migrating from HashiCorp Terraform to OpenTofu and want to use module source interpolation:

Before (Terraform - not supported):

# This will fail in Terraform
module "example" {
  source = "${var.module_path}"  # Error: Variables not allowed
}

After (OpenTofu 1.8+ - works automatically):

# This works in OpenTofu 1.8+ with Atmos auto-detection
module "example" {
  source = "${var.module_path}"  # Automatically supported
}

No configuration changes needed in Atmos - the auto-detection handles it automatically when command: "tofu" is configured.

Troubleshooting

If you encounter validation errors with OpenTofu-specific syntax:

1. Verify OpenTofu detection:

   tofu version
   # Should output: OpenTofu v1.8.x

2. Check Atmos configuration:

   components:
     terraform:
       command: "tofu"  # Must contain "tofu" or be a path to tofu
       init:
         pass_vars: true  # Required for module source interpolation

3. Enable debug logging to see detection details:

   export ATMOS_LOGS_LEVEL=Trace
   atmos terraform plan my-component -s my-stack

For more details on this feature, see the OpenTofu 1.8.0 release notes.