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. Use the --everything flag to delete all the local Terraform state files and directories (including terraform.tfstate.d) for all components and stacks. Use the --force flag to bypass the safety confirmation prompt and force the deletion (use with caution).

warning
The --everything flag performs destructive operations that can lead to permanent state loss. 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 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 --everything

# Clean a specific component
atmos terraform clean vpc --everything

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

# Clean without confirmation prompt
atmos terraform clean --everything --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

Argument	Description	Required
`component`	Atmos terraform component	yes

Flags

Flag	Description	Alias	Required
`--stack`	Atmos stack	`-s`	yes
`--dry-run`	Dry run		no
`--redirect-stderr`	File descriptor to redirect `stderr` to. Errors can be redirected to any file or any standard file descriptor (including `/dev/null`)		no
`--append-user-agent`	Append a custom User-Agent to Terraform requests. Can also be set using the ATMOS_COMPONENTS_TERRAFORM_APPEND_USER_AGENT environment variable.		no

note

All native terraform flags are supported

Subcommands

📄️ clean

Use this command to delete the .terraform folder, the folder that TFDATADIR ENV var points to, .terraform.lock.hcl file, varfile

📄️ deploy

Use this command to execute terraform apply -auto-approve on an Atmos component in an Atmos stack.

📄️ generate backend

Use this command to generate a Terraform backend config file for an Atmos terraform component in a stack.

📄️ generate backends

Use this command to generate the Terraform backend config files for all Atmos terraform components in all stacks.

📄️ generate varfile

Use this command to generate a varfile (.tfvar ) for an Atmos terraform component in a stack.

📄️ generate varfiles

Use this command to generate the Terraform varfiles (`.tfvar`) for all Atmos terraform components in all stacks.

📄️ shell

This command starts a new `SHELL` configured with the environment for an Atmos component in a stack to allow execution of all native terraform commands inside the shell without using any atmos-specific arguments and flags. This may by helpful to debug a component without going through Atmos.

📄️ workspace

This command calculates the `terraform` workspace for an Atmos component (from the context variables and stack config). It runs `terraform init -reconfigure` and selects the workspace by executing the `terraform workspace select` command.