Skip to main content

atmos terraform deploy

Use this command to deploy Terraform changes for an Atmos component in a stack with auto-approval. This combines plan and apply operations in a single command.

atmos terraform deploy --help

Usage​

Execute the terraform deploy subcommand like this:

atmos terraform deploy <component> -s <stack>

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

  • atmos terraform deploy command automatically sets -auto-approve flag when running terraform apply

  • atmos terraform deploy command supports --from-plan flag. If the flag is specified, the command will use the planfile previously generated by atmos terraform plan command instead of generating a new planfile, e.g. atmos terraform deploy <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 deploy command supports --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 deploy <component> -s <stack> --planfile <FILE> to apply the previously generated planfile

See all flags.

tip

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

Configuration​

Configure default behavior for terraform deploy in your atmos.yaml:

components:
  terraform:
    # Run 'terraform init' before deploy
    deploy_run_init: true

    # Auto-generate backend configuration
    auto_generate_backend_file: true

These settings can also be controlled via environment variables:

export ATMOS_COMPONENTS_TERRAFORM_DEPLOY_RUN_INIT=true
export ATMOS_COMPONENTS_TERRAFORM_AUTO_GENERATE_BACKEND_FILE=true

Examples​

Simple Example​

Deploy the top-level-component1 using the configuration specified in the tenant1-ue2-dev stack. This command explicitly targets a stack, which defines the environment and region settings for the deployment.

atmos terraform deploy top-level-component1 --stack tenant1-ue2-dev

Planfiles​

Deploy top-level-component1 based on a previously generated execution plan. The -s flag specifies the tenant1-ue2-dev stack, and --from-plan indicates that the deploy should proceed with the plan that was previously created, ensuring that the deployment matches the plan's specifications.

atmos terraform deploy top-level-component1 -s tenant1-ue2-dev --from-plan

Or use -s for a specific execution plan file located at <path_to_planfile> to ensure precision in what is deployed.

atmos terraform deploy top-level-component1 -s tenant1-ue2-dev --planfile <path_to_planfile>

Targeting Specific Stages​

This demonstrates how Atmos can be used to deploy infrastructure components, like a VPC, specifying the stack to ensure the deployment occurs within the correct environment and configuration context.

atmos terraform deploy infra/vpc -s tenant1-ue2-staging
atmos terraform deploy test/test-component -s tenant1-ue2-dev
atmos terraform deploy test/test-component-override-2 -s tenant2-ue2-prod
atmos terraform deploy test/test-component-override-3 -s tenant1-ue2-dev

Arguments​

component (required)

Atmos terraform component.

Flags​

--stack (alias -s) (required)

Atmos stack.

--dry-run (optional)

Dry run.

atmos terraform deploy <component> -s <stack> --dry-run=true
--deploy-run-init (optional)

Enable/disable running terraform init before executing the command.

atmos terraform deploy <component> -s <stack> --deploy-run-init
--from-plan (optional)

If the flag is specified, use the planfile previously generated by Atmos instead of generating a new planfile. The planfile name is in the format supported by Atmos and is saved to the component's folder.

atmos terraform deploy <component> -s <stack> --from-plan
--planfile (optional)

The path to a planfile. The --planfile flag should be used instead of the planfile argument in the native terraform apply <planfile> command.

atmos terraform deploy <component> -s <stack> --planfile <planfile>
--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 deploy <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 deploy <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 deploy <component> -s <stack> --skip=eval --skip=include
atmos terraform deploy <component> -s <stack> --skip=terraform.output,include

Native Terraform Flags​

The atmos terraform deploy command supports all native terraform apply options described in Terraform apply options, with the exception that a planfile argument can't be provided on the command line. To use a previously generated planfile, use the --from-plan or --planfile command-line flags.

See Terraform Planfiles for a comprehensive guide on working with planfiles in Atmos.

Multi-Component Operations​

Execute terraform deploy across multiple components using filtering flags. Since deploy auto-approves, this is particularly powerful for automated deployments. All flags can be combined with --dry-run to preview what would be executed.

warning

Multi-component deploy operations will auto-approve all changes. Use --dry-run first to verify which components will be affected.

Deploy All Components​

# Deploy all components in all stacks
atmos terraform deploy --all

# Deploy all components in a specific stack
atmos terraform deploy --all --stack prod
atmos terraform deploy --stack prod

Deploy Affected Components​

Deploy only components affected by changes in the current branch (requires git). Components are processed in dependency order:

# Deploy affected components in all stacks
atmos terraform deploy --affected

# Deploy affected components in a specific stack
atmos terraform deploy --affected --stack prod

# Include dependent components (components that depend on affected components)
atmos terraform deploy --affected --include-dependents

# Clone the target reference instead of checking it out
atmos terraform deploy --affected --clone-target-ref=true

Deploy Specific Components​

# Deploy specific components in all stacks
atmos terraform deploy --components vpc,eks

# Deploy specific components in a specific stack
atmos terraform deploy --components vpc,eks --stack prod

Deploy Components by Query​

Filter components using YQ expressions against component configuration:

# Deploy components where team tag equals "eks"
atmos terraform deploy --query '.vars.tags.team == "eks"'

# Deploy components in a specific account
atmos terraform deploy --query '.settings.context.account_id == 12345'

# Combine with stack filter
atmos terraform deploy --query '.vars.tags.team == "eks"' --stack prod

Multi-Component Flags​

--all
Deploy all components in all stacks (or specified stack with --stack).
--affected
Deploy components affected by git changes in dependency order. Supports all flags from atmos describe affected.
--components
Deploy specific components by name (comma-separated or repeated flag).
--query
Deploy components matching a YQ expression. All Atmos sections are available: vars, settings, env, metadata, etc.
--include-dependents
With --affected, also deploy components that depend on affected components, recursively.
--ref
Git reference to compare against (branch or tag). Default: refs/remotes/origin/HEAD.
--sha
Git commit SHA to compare against.
--clone-target-ref
Clone the target reference instead of checking it out locally.