atmos terraform plan

Use this command to generate a Terraform execution plan for an Atmos component in a stack, showing what changes would be made to your infrastructure.

atmos terraform plan

00:00.0 / 00:00.0

atmos terraform plan --help

Usage

Execute the terraform plan command like this:

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

This command generates an execution plan that shows:

• Resources that will be created, modified, or destroyed
• Changes to resource attributes
• Data source reads that will be performed

By default, Atmos saves the plan to a file using a standardized naming convention: <context>-<component>.planfile. This planfile can later be used with atmos terraform apply --from-plan to ensure that only the reviewed changes are applied.

tip

Run atmos terraform plan --help=all to see shared selector and dependency flags.

Examples

Basic Planning

Generate a plan for the vpc component in the dev stack:

atmos terraform plan vpc -s dev

Custom Planfile Output

Save the plan to a specific file using the -out flag (native Terraform flag):

atmos terraform plan vpc -s dev -out=my-custom.planfile

Skip Planfile Generation

When using Terraform Cloud (which doesn't support the -out flag), skip planfile generation:

atmos terraform plan vpc -s dev --skip-planfile

Planning with Variable Overrides

Pass additional variables to the plan:

atmos terraform plan vpc -s dev -var="instance_type=t3.large"

Targeted Planning

Plan changes only for specific resources:

atmos terraform plan vpc -s dev -target=aws_subnet.private

Destroy Planning

Generate a plan to destroy infrastructure:

atmos terraform plan vpc -s dev -destroy

Graph-backed Multi-component Planning

Run plans for multiple components through the Terraform dependency graph:

# Plan every Terraform component in dependency order
atmos terraform plan --all -s dev

# Plan a named subset, preserving dependency edges between selected components
atmos terraform plan --components vpc,eks/cluster,eks/apps -s dev

# Plan components selected by query
atmos terraform plan --query '.settings.tier == "network"' -s dev

The graph is built from dependencies.components first, with settings.depends_on as a fallback. Components that are independent at the same point in the graph can run concurrently when --max-concurrency is greater than 1.

atmos terraform plan --all -s dev --max-concurrency 4

Concurrent plan output is isolated per component. Use --log-order grouped to print each component's logs together after it finishes, or keep the default stream mode to see logs as they arrive. To reduce noise from unchanged components, use --hide=no-changes.

atmos terraform plan --all -s dev \
  --max-concurrency 4 \
  --failure-mode keep-going \
  --log-order grouped \
  --hide=no-changes \
  --execution-summary-file /tmp/atmos-plan-summary.json

GitHub Actions CI Output

When CI mode is enabled with --ci, ci.enabled: true, or GitHub Actions auto-detection, graph-backed multi-component plan runs write a single aggregate CI result after the scheduler finishes. This applies to --all, --components, and --query plan runs. Single-component plan, apply, and deploy keep their existing per-command CI output.

In GitHub Actions, the aggregate result writes once to $GITHUB_STEP_SUMMARY and $GITHUB_OUTPUT. The job summary includes component counts, total resource counts, failed/changed/no-change/skipped groups, a per-component table, and details for failed or changed components. Output variables include has_changes, has_errors, exit_code, resource totals, component totals, summary, command, stack, and component.

Aggregate exit codes follow Terraform plan semantics across the whole graph:

Exit Code	Meaning
1	At least one component failed
2	No failures, but at least one component has changes
0	No failures and no changes

Planfile Management

Default Behavior

When you run atmos terraform plan, Atmos automatically:

1. Generates a planfile with the naming pattern:

   • Without folder prefix: <context>-<component>.planfile
   • With folder prefix: <context>-<folder_prefix>-<component>.planfile

2. Saves the planfile in the component's working directory

3. The planfile can be used later with:

   atmos terraform apply <component> -s <stack> --from-plan

Custom Planfile Locations

You can specify a custom planfile location using the standard Terraform -out flag:

# Absolute path
atmos terraform plan vpc -s dev -out=/tmp/my-plan.tfplan

# Relative path (relative to component directory)
atmos terraform plan vpc -s dev -out=plans/vpc.tfplan

Skipping Planfile Generation

To run a plan without generating a planfile (useful for quick checks or when using Terraform Cloud):

atmos terraform plan vpc -s dev --skip-planfile

You can also configure this globally in atmos.yaml:

components:
  terraform:
    plan:
      skip_planfile: true

Arguments

component (required)

Atmos component name to plan.

Flags

--use-mocks (optional)

Use the producer's literal component mocks for !terraform.state and !terraform.output lookups. Accepts these values:

• Absent, empty, or a false boolean (false, 0, f): mocks are off.
• Bare --use-mocks, a true boolean (true, 1, t), or ATMOS_USE_MOCKS=true: mocks are on, using components.terraform.mocks.mode (fallback by default). In fallback mode the real state or output wins and the mock is used only when the component is not provisioned or the output is missing.
• --use-mocks=fallback or --use-mocks=always: mocks are on, overriding the configured mode for this run. The always value resolves !terraform.state and !terraform.output lookups from mocks only, without initializing the referenced components, authenticating, or reading their backends. The plan itself still initializes this component and uses its own backend and provider credentials.

Matching is case-insensitive, and any other value is an error. Attach the mode with =: a bare --use-mocks takes no value, so --use-mocks always leaves always as a positional argument and Atmos reports an error with a hint.

Default: off. Requires YAML function processing to remain enabled. Accepted only by atmos terraform plan and atmos describe component; every other atmos terraform subcommand (for example apply, deploy, and destroy) rejects it, and also fails if ATMOS_USE_MOCKS is set in the environment, so unset the variable before running them. With --all or --affected, the flag is passed through to each component.

--stack / -s (required)

Atmos stack name where the component is defined.

--skip-planfile (optional)

Skip writing the plan to a file. When set, Atmos will not pass the -out flag to Terraform.

This is useful when:

• Using Terraform Cloud (which doesn't support -out)
• Running quick plan checks without saving the output
• Running in CI/CD environments where planfiles aren't needed

atmos terraform plan vpc -s dev --skip-planfile

--affected (optional)

Plan only affected components based on changes in the repository. This is a global operation that identifies and plans all components affected by recent changes across all stacks.

# Plan only affected components across all stacks
atmos terraform plan --affected

--all (optional)

Plan all components in all stacks (use with caution).

atmos terraform plan --all

--dry-run (optional)

Show what would be executed without actually running the plan.

atmos terraform plan vpc -s dev --dry-run

--skip-init (optional)

Skip running terraform init before planning.

atmos terraform plan vpc -s dev --skip-init

--init-mode (optional)

Override init.mode for this invocation: auto (default, skip init when nothing relevant changed), always, or never (disables the ordinary implicit init, but unlike --skip-init does not suppress the forced reconfigure init that atmos terraform workspace select/new needs).

atmos terraform plan vpc -s dev --init-mode=always

--init-reconfigure (optional)

Override init.reconfigure for this invocation: auto (default), always, or never.

atmos terraform plan vpc -s dev --init-reconfigure=always

--init-upgrade (optional)

Override init.upgrade for this invocation: auto (default), always, or never.

atmos terraform plan vpc -s dev --init-upgrade=always

--process-templates (optional)

Enable/disable Go template processing in Atmos stack manifests.

Default: true

atmos terraform plan vpc -s dev --process-templates=false

--ui (optional)

Enable streaming UI mode for real-time resource status display. Shows a Docker-build-style progress view with spinners, progress bar, and resource states.

The UI automatically disables when output is piped, in CI environments, or when running unsupported commands.

--ui errors when combined with --max-concurrency greater than 1, since concurrently-scheduled components can't share one terminal for their full-screen UI sessions. Use --max-concurrency 1 (the default) with --ui, or drop --ui to run concurrently.

atmos terraform plan vpc -s dev --ui

Use --ui=false to explicitly disable when enabled by config.

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

CI mode is auto-detected when CI=true or GITHUB_ACTIONS=true environment variables are set. Use this flag to explicitly enable CI mode in environments where auto-detection is not available.

Environment variables: ATMOS_CI, CI

atmos terraform plan vpc -s dev --ci

Native Terraform Flags

The atmos terraform plan command supports all native terraform plan flags. To pass native Terraform flags, you have two options:

1. Direct flags - Pass Terraform flags directly if they don't conflict with Atmos flags
2. Double-dash separator - Use -- to explicitly separate Atmos flags from Terraform flags

Using the Double-Dash Separator

The -- separator is a common Unix convention that indicates "end of options". Everything after -- is passed directly to Terraform without interpretation by Atmos. This is useful when:

• You want to ensure a flag is passed to Terraform, not Atmos
• You're using flags that might conflict with Atmos flags
• You want to be explicit about which tool receives which flags

Example:

atmos terraform plan vpc -s dev -- -refresh=false -out=my-custom.tfplan

Some commonly used native flags include:

-out=FILE

Write the plan to a file at the specified path. This is the standard Terraform flag for specifying a custom planfile location.

atmos terraform plan vpc -s dev -out=my-plan.tfplan

-destroy

Create a plan to destroy all resources.

atmos terraform plan vpc -s dev -destroy

-target=RESOURCE

Plan only specific resources. Can be specified multiple times.

atmos terraform plan vpc -s dev -target=aws_subnet.private -target=aws_route_table.private

-var 'NAME=VALUE'

Set a variable value. Can be specified multiple times.

atmos terraform plan vpc -s dev -var="instance_count=3" -var="environment=staging"

-refresh-only

Create a plan to update the state to match remote systems.

atmos terraform plan vpc -s dev -refresh-only

Default Locking and Concurrency Flags

Instead of retyping flags like -lock-timeout on every invocation, declare a default in components.terraform.flags — globally in atmos.yaml, per stack, or per component. plan supports all five flags (lock_timeout, lock, parallelism, refresh, compact_warnings); a native flag typed directly on the command line (as shown above) always wins over a declared default.

Multi-Component Operations

Execute terraform plan across multiple components using filtering flags. All flags can be combined with --dry-run to preview what would be executed.

Plan All Components

# Plan all components in all stacks
atmos terraform plan --all

# Plan all components in a specific stack
atmos terraform plan --all --stack prod
atmos terraform plan --stack prod

Plan Affected Components

Plan only components affected by changes in the current branch (requires git):

# Plan affected components in all stacks
atmos terraform plan --affected

# Plan affected components in a specific stack
atmos terraform plan --affected --stack prod

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

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

Plan Specific Components

# Plan specific components in all stacks
atmos terraform plan --components vpc,eks

# Plan specific components in a specific stack
atmos terraform plan --components vpc,eks --stack prod

Plan Components by Query

Filter components using YQ expressions against component configuration:

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

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

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

Plan Components by Tags and Labels

Filter components by metadata.tags/metadata.labels. These flags compose with --all/--affected/--components/--query to narrow the selected set further, rather than being mutually exclusive with them:

# Plan components tagged production or tier-1 (matches any)
atmos terraform plan --tags production,tier-1

# Plan components labeled cost-center=platform (matches all given labels)
atmos terraform plan --labels cost-center=platform

# Narrow an --affected run to only production-tagged components
atmos terraform plan --affected --tags production

Include Dependencies and Dependents

Selector flags choose the seed set; --include-dependencies and --include-dependents expand it through the dependency graph. Expanded components are planned even when they do not match the selectors — they are prerequisites (or dependents) of what was selected. Prerequisites can live in other stacks, so --include-dependencies with -s dev legitimately plans prerequisite components outside the dev stack:

# Plan dev-labeled components plus everything they depend on
atmos terraform plan --labels=env=dev --include-dependencies

# Bound the expansion to direct dependencies only
atmos terraform plan --labels=env=dev --include-dependencies=1

# Plan a stack plus everything that depends on it, up to two levels out
atmos terraform plan -s dev --include-dependents=2

Pass the depth with = (for example, --include-dependencies=2); a space-separated value is not bound to the flag. The bare flag expands without a depth limit, and true/false values are accepted for backward compatibility.

Multi-Component Flags

--all

Plan all components in all stacks (or specified stack with --stack).

--affected

Plan components affected by git changes in dependency order. Supports all flags from atmos describe affected.

--components

Plan specific components by name (comma-separated or repeated flag).

--query

Plan components matching a YQ expression. All Atmos sections are available: vars, settings, env, metadata, etc.

--tags

Filter by tags (comma-separated, matches any): --tags=production,tier-1. Composes with --all/--affected/--components/--query to narrow the selected set further; cannot be combined with a single component argument.

--labels

Filter by labels (comma-separated key=value or key:value pairs, matches all): --labels=cost-center=platform,compliance=sox. Composes with --all/--affected/--components/--query/--tags; cannot be combined with a single component argument.

--include-dependencies

Also plan everything the selected components depend on (their prerequisites), in dependency order — even when the prerequisites live in other stacks or do not match the selectors. Accepts an optional depth: the bare flag expands the full dependency chain, while --include-dependencies=1 bounds it to direct dependencies. Requires a multi-component selection.
Environment variable: ATMOS_INCLUDE_DEPENDENCIES

--include-dependents

Also plan everything that depends on the selected components, in dependency order. Works with any multi-component selection (--all, --components, --query, --stack, --tags, --labels, --affected). Accepts an optional depth: the bare flag expands the full dependent chain, while --include-dependents=2 bounds it to two levels.
Environment variable: ATMOS_INCLUDE_DEPENDENTS

--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), Atmos produces rich CI artifacts:

• Job summaries with resource badges, collapsible diffs, and warnings written to $GITHUB_STEP_SUMMARY
• Output variables (has_changes, has_errors, exit_code, etc.) written to $GITHUB_OUTPUT
• Status checks showing plan progress and results (requires ci.checks.enabled: true)
• PR plan-summary comments when ci.comments.enabled: true, the run is for a pull request, and the workflow grants pull-requests: write; comments reuse the job-summary template and are updated by default on later runs for the same command, component, and stack

# In GitHub Actions (auto-detected)
atmos terraform plan vpc -s dev

# Explicit CI mode
atmos terraform plan vpc -s dev --ci

info

See CI Configuration for full configuration options including custom templates, status checks, and output variables. See CI Pull Request Comments to opt into plan-summary comments.

Related Commands

• atmos terraform apply - Apply the changes from a plan
• atmos terraform deploy - Deploy with auto-approval
• atmos terraform plan-diff - Compare two plan files

Configuration

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

components:
  terraform:
    plan:
      # Skip generating planfiles by default (useful for Terraform Cloud)
      skip_planfile: false

This can also be set using the environment variable:

export ATMOS_COMPONENTS_TERRAFORM_PLAN_SKIP_PLANFILE=true

info

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