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
--ci (optional)

Enable CI mode for automated pipelines. When enabled, Atmos writes job summaries, CI output variables, and status checks based on the ci configuration in atmos.yaml.

In CI mode, deploy also downloads stored planfiles and verifies them against fresh plans before applying, ensuring no infrastructure drift has occurred since the plan was reviewed.

CI mode is auto-detected when CI=true or GITHUB_ACTIONS=true environment variables are set.

Environment variables: ATMOS_CI, CI

atmos terraform deploy <component> -s <stack> --ci

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.

CI Integration​

Experimental

When running in CI mode (--ci flag or auto-detected), the deploy command provides a complete CI-native apply workflow:

  1. Before deploy — Downloads stored planfiles from configured storage (S3, GitHub Artifacts, or local)
  2. Verification — Generates a fresh plan and compares it against the stored plan to detect drift
  3. Apply — Applies the verified plan if it matches, or fails with a drift error
  4. After deploy — Writes job summaries, CI output variables, and updates status checks
# In GitHub Actions (auto-detected)
atmos terraform deploy vpc -s dev

# Explicit CI mode
atmos terraform deploy vpc -s dev --ci
info

See CI Configuration for full configuration options and Planfile Storage for storage backend setup.