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

## Usage

Execute the `terraform deploy` subcommand like this:

```shell
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](#flags).

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

## Configuration

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

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

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

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

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

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

```shell
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.
  ```shell
  atmos terraform deploy <component> -s <stack> --dry-run=true
  ```
- **`--deploy-run-init` (optional)**

  Enable/disable running `terraform init` before executing the command.
  ```shell
  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.
  ```shell
  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.
  ```shell
  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.
  ```shell
  atmos terraform deploy <component> -s <stack> --process-templates=false
  ```
- **`--process-functions` (optional)**

  Enable/disable YAML functions processing in Atmos stack manifestswhen executing terraform commands.

  If the flag is not passed, YAML function processing is enabled by default.
  ```shell
  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.
  ```shell
  atmos terraform deploy <component> -s <stack> --skip=eval --skip=include
  atmos terraform deploy <component> -s <stack> --skip=terraform.output,include
  ```
- **`--max-concurrency` (optional)**

  Maximum number of components to deploy concurrently when running with `--all`, `--affected`, `--components`, or `--query`. Default is `1` (sequential).

  **Environment variable:** `ATMOS_TERRAFORM_DEPLOY_MAX_CONCURRENCY`
  ```shell
  atmos terraform deploy --all -s prod --max-concurrency 4
  ```
- **`--failure-mode` (optional)**

  Controls how the concurrent scheduler handles a failed component when using `--all`, `--affected`, `--components`, or `--query` with `--max-concurrency > 1`.

  Supported values:
  - `fail-fast` _(default)_ — stop scheduling new components as soon as one fails
  - `keep-going` — continue deploying independent graph branches even after a failure
  **Environment variable:** `ATMOS_TERRAFORM_DEPLOY_FAILURE_MODE`
  ```shell
  atmos terraform deploy --all -s prod --max-concurrency 4 --failure-mode keep-going
  ```
- **`--log-order` (optional)**

  Controls how concurrent per-component logs are ordered when `--max-concurrency` is greater than `1`.

  Supported values:
  - `stream` _(default)_ — print log lines as they arrive, interleaved across components
  - `grouped` — buffer each component's output and print it as a contiguous block after the component finishes
  **Environment variable:** `ATMOS_TERRAFORM_DEPLOY_LOG_ORDER`
  ```shell
  atmos terraform deploy --all -s prod --max-concurrency 4 --log-order grouped
  ```
- **`--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`.

  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`
  ```shell
  atmos terraform deploy <component> -s <stack> --ci
  ```
- **`--verify-plan` (optional)**

  Force planfile drift verification (fail on drift) before applying, overriding the
  [`planfiles.verify`](/components/terraform/planfiles#drift-verification) config and the CI default.

  Verification is **automatic** under `--ci` when planfile storage is configured (default behavior is `fail`); this flag is only needed to force it on outside CI or override `verify: warn`/`off`.

  This flag **requires planfile storage** to be configured under
  [`components.terraform.planfiles`](/ci/planfile-storage) in `atmos.yaml` — without it there is
  no stored plan to verify against, and the deploy errors instead of silently applying an
  unverified fresh plan.

  Pass `--verify-plan=false` to **disable** verification, overriding both the `planfiles.verify` config and the CI default. The stored planfile is not downloaded and no drift check runs; `deploy` performs a normal plan-and-apply.

  **Environment variables:** `ATMOS_TERRAFORM_VERIFY_PLAN` (set to `false` to disable)
  ```shell
  atmos terraform deploy <component> -s <stack> --ci --verify-plan
  atmos terraform deploy <component> -s <stack> --ci --verify-plan=false
  ```

## Automatic Plan Verification in CI

When planfile storage is configured and `deploy` runs in CI mode, Atmos automatically downloads the
planfile that `atmos terraform plan --ci` uploaded, generates a fresh plan, compares them, and applies
the fresh plan after verification — failing on drift by default. Control this with
[`components.terraform.planfiles.verify`](/components/terraform/planfiles#drift-verification)
(`fail` | `warn` | `off`) or the `--verify-plan` flag (`--verify-plan` forces `fail`, `--verify-plan=false` forces `off`; CLI overrides config).

If **no stored plan is found** (the `plan` job never uploaded one),
[`components.terraform.planfiles.required`](/components/terraform/planfiles#missing-stored-plan) decides
what happens. It defaults to tracking `verify` strictness, so a fail-by-default CI deploy fails loudly
rather than silently applying an unverified fresh plan — a green `deploy` therefore proves verification
ran. Set `required: false` to allow a fresh apply when the stored plan is absent.

With the `github/artifacts` store, the automatic download talks to the GitHub Artifacts runtime API, so
the workflow must surface the runner's `ACTIONS_RUNTIME_TOKEN` / `ACTIONS_RESULTS_URL` with the
[`github-runtime`](https://github.com/cloudposse/atmos/tree/main/actions/github-runtime) action before
`deploy` — the same requirement as the upload on `plan` (see
[Planfile Storage](/ci/planfile-storage#using-github-artifacts-in-github-actions)):

```yaml
steps:
  - uses: cloudposse/atmos/actions/github-runtime@v1   # surfaces ACTIONS_RUNTIME_TOKEN/RESULTS_URL
    with:
      mode: env
  - run: atmos terraform deploy mycomponent -s prod --ci   # auto-downloads, verifies, then applies
```

## Native Terraform Flags

The `atmos terraform deploy` command supports all native `terraform apply` options described
in [Terraform apply options](https://developer.hashicorp.com/terraform/cli/commands/apply#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](/components/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

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

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

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

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

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

```shell
# Deploy components tagged production or tier-1 (matches any)
atmos terraform deploy --tags production,tier-1

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

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

### 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`](/cli/commands/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.
- **`--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`
   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-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 **fresh** plan (built with the apply-time state and credentials) once the diff confirms it matches the reviewed plan, or fails with a drift error. This reconciles rather than replays the stored binary, avoiding a saved plan going stale when state moves and the base credentials differing between plan time (PR) and apply time (merge). To replay the stored planfile directly instead, use `--from-plan` / `--planfile`.
4. **After deploy** — Writes job summaries, CI output variables, and updates status checks

```shell
# 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](/cli/configuration/ci) for full configuration options and [Planfile Storage](/cli/commands/terraform/planfile) for storage backend setup.
:::

## Related Commands

- [terraform plan](/cli/commands/terraform/plan) - Generate an execution plan
- [terraform apply](/cli/commands/terraform/apply) - Apply changes with confirmation
- [terraform destroy](/cli/commands/terraform/destroy) - Destroy infrastructure
- [terraform planfile](/cli/commands/terraform/planfile) - Manage stored planfiles
- [Native CI](/ci) - CI/CD integration overview