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

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

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

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