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

_\[Video: atmos terraform plan]_

## Usage

Execute the `terraform plan` command like this:

```shell
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` to see all the available options
:::

## Examples

### Basic Planning

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

```shell
atmos terraform plan vpc -s dev
```

### Custom Planfile Output

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

```shell
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:

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

### Planning with Variable Overrides

Pass additional variables to the plan:

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

### Targeted Planning

Plan changes only for specific resources:

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

### Destroy Planning

Generate a plan to destroy infrastructure:

```shell
atmos terraform plan vpc -s dev -destroy
```

## 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:
   ```shell
   atmos terraform apply <component> -s <stack> --from-plan
   ```

### Custom Planfile Locations

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

```shell
# 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):

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

You can also configure this globally in `atmos.yaml`:

```yaml
components:
  terraform:
    plan:
      skip_planfile: true
```

## Arguments

- **`component` (required)**

  Atmos component name to plan.

## Flags

- **`--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
  ```shell
  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.
  ```shell
  # Plan only affected components across all stacks
  atmos terraform plan --affected
  ```
- **`--all` (optional)**

  Plan all components in all stacks (use with caution).
  ```shell
  atmos terraform plan --all
  ```
- **`--dry-run` (optional)**

  Show what would be executed without actually running the plan.
  ```shell
  atmos terraform plan vpc -s dev --dry-run
  ```
- **`--skip-init` (optional)**

  Skip running `terraform init` before planning.
  ```shell
  atmos terraform plan vpc -s dev --skip-init
  ```
- **`--process-templates` (optional)**

  Enable/disable Go template processing in Atmos stack manifests.

  Default: `true`
  ```shell
  atmos terraform plan vpc -s dev --process-templates=false
  ```
- **`--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](/cli/configuration/ci) 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`
  ```shell
  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

:::tip 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:**

```shell
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.
  ```shell
  atmos terraform plan vpc -s dev -out=my-plan.tfplan
  ```
- **`-destroy`**

  Create a plan to destroy all resources.
  ```shell
  atmos terraform plan vpc -s dev -destroy
  ```
- **`-target=RESOURCE`**

  Plan only specific resources. Can be specified multiple times.
  ```shell
  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.
  ```shell
  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.
  ```shell
  atmos terraform plan vpc -s dev -refresh-only
  ```

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

```shell
# 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):

```shell
# 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

```shell
# 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](https://mikefarah.gitbook.io/yq) expressions against component configuration:

```shell
# 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
```

### 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`](/cli/commands/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.
- **`--include-dependents`**
  With 
  `--affected`
  , also plan 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), 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`)

```shell
# 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](/cli/configuration/ci) for full configuration options including custom templates, status checks, and output variables.
:::

## Related Commands

- [`atmos terraform apply`](/cli/commands/terraform/apply) - Apply the changes from a plan
- [`atmos terraform deploy`](/cli/commands/terraform/deploy) - Deploy with auto-approval
- [`atmos terraform plan-diff`](/cli/commands/terraform/plan-diff) - Compare two plan files

## Configuration

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

```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:

```shell
export ATMOS_COMPONENTS_TERRAFORM_PLAN_SKIP_PLANFILE=true
```

:::info
See [Terraform Planfiles](/components/terraform/planfiles) for a comprehensive guide on working with planfiles in Atmos.
:::