atmos terraform
Use these subcommands to interact with Terraform and OpenTofu.
Atmos Terraform/OpenTofu commands fall into two categories:
-
Single-Component: Run Terraform for one component at a time
-
Multi-Component (Filtered/Bulk): Run Terraform across multiple components using stack names, selectors, or change detection
Atmos supports all Terraform and OpenTofu commands and options described in Terraform CLI Overview and OpenTofu Basic CLI Features.
In addition, for the Single-Component commands, the component
argument and stack
flag are required to generate
variables and backend config for the component in the stack.
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.
Single-Component Commands Usageβ
Use single-component commands when you want to execute Terraform operations on one component at a time, offering precise control over individual resources.
Multi-Component Commands (Bulk Operations) Usageβ
Use multi-component commands to run Terraform operations across multiple components simultaneously. You can target components by stack, selector, query, or change detectionβoften making this approach more efficient than using Atmos workflows for certain use cases.
Additions and differences from native Terraform and OpenTofuβ
-
before executing other
terraform
commands, Atmos runsterraform 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 soatmos terraform <command> <component> -s <stack> --skip-init
-
atmos terraform deploy
command executesterraform apply -auto-approve
(sets-auto-approve
flag when runningterraform apply
) -
atmos terraform deploy
command supports--deploy-run-init=true|false
flag to enable/disable runningterraform init
before executing the command -
atmos terraform apply
andatmos terraform deploy
commands support--from-plan
flag. If the flag is specified, the commands will use the planfile previously generated byatmos 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
andatmos 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 nativeterraform apply <planfile>
command. For example, you can execute the commandatmos terraform plan <component> -s <stack> -out=<FILE>
, which will save the generated plan to a file on disk, and then execute the commandatmos 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 generatedplanfile
andvarfile
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 (includingterraform.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.warningThe
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 runsterraform init -reconfigure
, thenterraform workspace select
, and if the workspace was not created before, it then runsterraform workspace new
-
atmos terraform import
command searches forregion
in the variables for the specified component and stack, and if it finds it, setsAWS_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 runningterraform 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 theterraform
commands. For example:atmos terraform plan <component> -s <stack> -- -refresh=false
atmos terraform apply <component> -s <stack> -- -lock=false
Run atmos terraform --help
to see all the available options
Examplesβ
Argumentsβ
component
(required for Single-Component commands)Atmos Terraform/OpenTofu component.
Flagsβ
--stack
(alias-s
) (required for Single-Component commands)Atmos stack.
atmos terraform plan <component> --stack <stack>
atmos terraform apply --all -s <stack>--dry-run
(optional)Dry run. Simulate the command without making any changes.
atmos terraform <command> <component> -s <stack> --dry-run
atmos terraform <command> --all --dry-run
atmos terraform <command> --affected --dry-run--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--components
(optional)Execute the command on the specified components in all stacks or in a specific stack.
atmos terraform plan --components <component-1>
atmos terraform plan --components <component-1>,<component-2>
atmos terraform apply --components <component-1> --components <component-2>
atmos terraform apply --components <component-1>,<component-2> --stack <stack> --logs-level=Debug--all
(optional)Execute the command on all components in all stacks or in a specific stack.
atmos terraform plan --all
atmos terraform apply --all --stack <stack>
atmos terraform apply --all --dry-run
atmos terraform deploy --all --logs-level=Debug--query
(optional)Execute the command on the components filtered by a YQ expression, in all stacks or in a specific stack.
NOTE: All Atmos sections are available in the expression, e.g.
vars
,settings
,env
,metadata
,backend
, etc.atmos terraform plan --query '.vars.tags.team == "data"'
atmos terraform apply --query '.vars.tags.team == "eks"' --stack <stack>
atmos terraform apply --query '.settings.context.account_id == 12345'
atmos terraform deploy --query '.vars.tags.team == "data"' --dry-run --logs-level=Debug--affected
(optional)Execute the command on all the directly affected components, in all stacks or in a specific stack, in dependency order (if component dependencies are configured).
NOTE: When using the
--affected
flag, Atmos supports all the flags from theatmos describe affected
CLI command.atmos terraform plan --affected
atmos terraform apply --affected --stack <stack>
atmos terraform apply --affected --dry-run
atmos terraform apply --affected --clone-target-ref=true
atmos terraform deploy --affected --include-dependents
atmos terraform apply --affected --include-dependents --dry-run --logs-level=Debug--include-dependents
(optional; can only be used in conjunction with the--affected
flag)For each directly affected component, detect the dependent components and process them in dependency order, recursively. Dependents are components that are indirectly affected, meaning that nothing in the current branch modifies their code or configs, but they are configured as dependencies of the components that are modified.
atmos terraform plan --affected --include-dependents --logs-level=Debug
atmos terraform apply --affected --include-dependents --dry-run
atmos terraform apply --affected --include-dependents --stack prod --dry-run--ref
(optional; can only be used in conjunction with the--affected
flag)Git Reference with which to compare the current working branch.
If the reference is a branch, the command will compare the current working branch with the branch.
If the reference is a tag, the command will compare the current working branch with the tag.
If the flags are not provided, the ref will be set automatically to the head to the default branch (
refs/remotes/origin/HEAD
Git ref, usually themain
branch)--sha
(optional; can only be used in conjunction with the--affected
flag)Git commit SHA with which to compare the current working branch
--ssh-key
(optional; can only be used in conjunction with the--affected
flag)Path to PEM-encoded private key to clone private repos using SSH
--ssh-key-password
(optional; can only be used in conjunction with the--affected
flag)Encryption password for the PEM-encoded private key if the key contains a password-encrypted PEM block
--repo-path
(optional; can only be used in conjunction with the--affected
flag)Path to the already cloned target repository with which to compare the current branch. Conflicts with
--ref
,--sha
,--ssh-key
and--ssh-key-password
--clone-target-ref
(optional; can only be used in conjunction with the--affected
flag)Clone the target reference with which to compare the current branch.
atmos terraform plan --affected --clone-target-ref=true
atmos terraform deploy --affected --clone-target-ref=true --dry-run
atmos terraform apply --affected --clone-target-ref=true --dry-run --logs-level=DebugIf the flag is not passed or set to
false
(default), the target reference will be checked out instead. This requires that the target reference is already cloned by Git, and the information about it exists in the.git
directory
All native Terraform/OpenTofu flags are supported.
Multi-Component Commands (Bulk Operations) Examplesβ
Let's assume that we have the following Atmos stack manifests in the prod
and nonprod
stacks,
with dependencies between the components:
`prod` and `nonprod` stacks
Let's run the following Multi-Component commands in dry-run
mode and review the output to understand what each command executes:
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 planfile
Use this command to generate a planfile for an Atmos Terraform/OpenTofu component in a stack.
ποΈ 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.
ποΈ plan-diff
The atmos terraform plan-diff command compares two Terraform plans and shows the differences between them.
ποΈ 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.