Skip to main content
Purpose

Use these subcommands to interact with terraform.

atmos terraform --help

Usage

Executes terraform commands.

atmos terraform <command> <component> -s <stack> [options]
atmos terraform <command> <component> --stack <stack> [options]

Atmos supports all terraform commands and options described in Terraform CLI reference.

In addition, the component argument and stack flag are required to generate variables and backend config for the component in the stack.

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

Additions and differences from native terraform:

  • before executing other terraform commands, Atmos runs terraform init

  • you can skip over atmos calling terraform init if you know your project is already in a good working state by using the --skip-init flag like so atmos terraform <command> <component> -s <stack> --skip-init

  • atmos terraform deploy command executes terraform apply -auto-approve (sets -auto-approve flag when running terraform apply)

  • atmos terraform deploy command supports --deploy-run-init=true|false flag to enable/disable running terraform init before executing the command

  • atmos terraform apply and atmos terraform deploy commands support --from-plan flag. If the flag is specified, the commands will use the planfile previously generated by atmos terraform plan command instead of generating a new planfile, e.g. atmos terraform apply <component> -s <stack> --from-plan. Note that in this case, the planfile name is in the format supported by Atmos and is saved to the component's folder

  • atmos terraform apply and atmos terraform deploy commands support --planfile flag to specify the path to a planfile. The --planfile flag should be used instead of the planfile argument in the native terraform apply <planfile> command. For example, you can execute the command atmos terraform plan <component> -s <stack> -out=<FILE>, which will save the generated plan to a file on disk, and then execute the command atmos terraform apply <component> -s <stack> --planfile <FILE> to apply the previously generated planfile

  • atmos terraform clean command deletes the .terraform folder, .terraform.lock.hcl lock file, and the previously generated planfile and varfile for the specified component and stack. Use the --skip-lock-file flag to skip deleting the .terraform.lock.hcl file. It deletes all local Terraform state files and directories (including terraform.tfstate.d used for local state) for a component in a stack. The --force flag bypasses the safety confirmation prompt and forces the deletion. Use with caution.

    warning

    The clean command performs destructive operations that can lead to permanent state loss, if not using remote backends. Always ensure you have remote state configured in your components before proceeding.

  • atmos terraform workspace command first runs terraform init -reconfigure, then terraform workspace select, and if the workspace was not created before, it then runs terraform workspace new

  • atmos terraform import command searches for region in the variables for the specified component and stack, and if it finds it, sets AWS_REGION=<region> ENV var before executing the command

  • atmos terraform generate backend command generates a backend config file for an Atmos component in a stack

  • atmos terraform generate backends command generates backend config files for all Atmos components in all stacks

  • atmos terraform generate varfile command generates a varfile for an Atmos component in a stack

  • atmos terraform generate varfiles command generates varfiles for all Atmos components in all stacks

  • atmos terraform plan-diff command compares two Terraform plans and shows the differences between them. It takes an original plan file (--orig) and optionally a new plan file (--new). If the new plan file is not provided, it will generate one by running terraform plan with the current configuration.

  • atmos terraform shell command configures an environment for an Atmos component in a stack and starts a new shell allowing executing all native terraform commands inside the shell

  • double-dash -- can be used to signify the end of the options for Atmos and the start of the additional native arguments and flags for the terraform commands. For example:

    • atmos terraform plan <component> -s <stack> -- -refresh=false
    • atmos terraform apply <component> -s <stack> -- -lock=false

tip

Run atmos terraform --help to see all the available options

Examples​

atmos terraform plan test/test-component-override-3 -s tenant1-ue2-dev
atmos terraform plan test/test-component-override-3 -s tenant1-ue2-dev --skip-lock-file
atmos terraform plan test/test-component-override-2 -s tenant1-ue2-dev --redirect-stderr /dev/stdout
atmos terraform plan test/test-component-override -s tenant1-ue2-dev --redirect-stderr ./errors.txt

atmos terraform apply test/test-component-override-3 -s tenant1-ue2-dev
atmos terraform apply test/test-component-override-2 -s tenant1-ue2-dev --redirect-stderr /dev/stdout
atmos terraform apply test/test-component-override -s tenant1-ue2-dev --redirect-stderr ./errors.txt

atmos terraform destroy test/test-component-override-3 -s tenant1-ue2-dev
atmos terraform destroy test/test-component-override-2 -s tenant1-ue2-dev --redirect-stderr /dev/stdout
atmos terraform destroy test/test-component-override -s tenant1-ue2-dev --redirect-stderr /dev/null

atmos terraform init test/test-component-override-3 -s tenant1-ue2-dev

# Clean all components (with confirmation)
atmos terraform clean

# Clean a specific component
atmos terraform clean vpc

# Clean a specific component in a stack
atmos terraform clean vpc --stack dev

# Clean without confirmation prompt
atmos terraform clean --force
atmos terraform clean test/test-component-override-3 -s tenant1-ue2-dev

atmos terraform workspace test/test-component-override-3 -s tenant1-ue2-dev
atmos terraform workspace test/test-component-override-3 -s tenant1-ue2-dev --redirect-stderr /dev/null
atmos terraform workspace test/test-component-override-3 -s tenant1-ue2-dev --redirect-stderr /dev/stdout
atmos terraform workspace test/test-component-override-3 -s tenant1-ue2-dev --redirect-stderr ./errors.txt

atmos terraform plan test/test-component -s tenant1-ue2-dev -- -refresh=false -lock=false

atmos terraform plan test/test-component -s tenant1-ue2-dev --append-user-agent "Acme/1.0 (Build 1234; arm64)"

Arguments​

component (required)

Atmos terraform component.

Flags​

--stack (alias -s) (required)

Atmos stack.

--dry-run (optional)

Dry run.

atmos terraform <command> <component> -s <stack> --dry-run=true
--redirect-stderr (optional)

File descriptor to redirect stderr to.

Errors can be redirected to any file or any standard file descriptor (including /dev/null).

--append-user-agent (optional)

Append a custom User-Agent to Terraform requests.

Can also be set using the ATMOS_COMPONENTS_TERRAFORM_APPEND_USER_AGENT environment variable.

--skip-init (optional)

Skip running terraform init before executing terraform commands.

atmos terraform apply <component> -s <stack> --skip-init
--process-templates (optional)

Enable/disable Go template processing in Atmos stack manifests when executing terraform commands.

If the flag is not passed, template processing is enabled by default.

atmos terraform plan <component> -s <stack> --process-templates=false
--process-functions (optional)

Enable/disable YAML functions processing in Atmos stack manifests
when executing terraform commands.

If the flag is not passed, YAML function processing is enabled by default.

atmos terraform plan <component> -s <stack> --process-functions=false
--skip (optional)

Skip processing a specific Atmos YAML function in Atmos stacks manifests when executing terraform commands.

To specify more than one function, use multiple --skip flags, or separate the functions with a comma.

atmos terraform plan <component> -s <stack> --skip=eval --skip=include
atmos terraform apply <component> -s <stack> --skip=terraform.output,include
note

All native terraform flags are supported.

Subcommands​