# atmos terraform migrate apply

Use `atmos terraform migrate apply` to apply a user-authored `tfmigrate` migration for an Atmos Terraform component.

> ⚠️ Experimental

## Usage

```shell
atmos terraform migrate apply [component] -s <stack> [options]
```

Atmos runs the same component preparation as `plan`: auth, source provisioning, workdir provisioning, generated files, Terraform init, and workspace selection.

## Arguments

- **`component`** — Atmos Terraform component to migrate. Omit when selecting multiple components with `--all`, `--components`, `--query`, or `--affected`.

## Flags

- **`--stack` / `-s`** — Atmos stack where the component is defined.
- **`--identity` / `-i`** — Identity to authenticate before resolving the component and running `tfmigrate apply`. Environment variable: `ATMOS_IDENTITY`.
- **`--migration`** — Path to a single `tfmigrate` migration file, relative to `migration_dir`. Do not include the `migration_dir` prefix. `migration_dir` defaults to `./migrations` when that directory exists in the component, otherwise it defaults to the component root. Omit this flag to let `tfmigrate` run history mode. Single-file reruns are not inherently idempotent.
- **`--tfmigrate-config`** — Override the `tfmigrate` config path. Atmos checks, in order: this flag or `ATMOS_TFMIGRATE_CONFIG`, then `TFMIGRATE_CONFIG`, then a `.tfmigrate.hcl` file in the component. When none of these are set, Atmos generates a config that reuses the component's Terraform backend as history storage.
- **`--backend-config`** — Backend config entry passed to `tfmigrate --backend-config`. Repeat the flag for multiple entries.
- **`--all`** — Apply the migration for all selected component instances.
- **`--components`** — Apply the migration for the listed component names.
- **`--query`** — Apply the migration for component instances matching a YQ expression.
- **`--affected`** — Apply the migration for affected Terraform components. `--include-dependents` is not supported for migrate yet.
- **`--skip-init`** — Skip the normal Terraform init path before `tfmigrate` runs.

## Examples

Apply history-mode migrations:

```shell
atmos terraform migrate apply s3-bucket -s plat-ue2-dev
```

Apply with an explicit identity:

```shell
atmos terraform migrate apply s3-bucket -s plat-ue2-dev --identity aws-prod
```

Apply a single-file migration:

```shell
atmos terraform migrate apply s3-bucket -s plat-ue2-dev --migration 001_remove_template_provider.hcl
```

`tfmigrate` resolves the value relative to the `migration_dir` in its config. Pass just the filename when `migration_dir` already points at your migrations directory.

Override the default `tfmigrate` config path:

```shell
atmos terraform migrate apply s3-bucket -s plat-ue2-dev --tfmigrate-config migrations/.tfmigrate.hcl
```

Components with an S3 or GCS backend get durable history automatically. When none of `--tfmigrate-config` / `ATMOS_TFMIGRATE_CONFIG`, `TFMIGRATE_CONFIG`, or a component `.tfmigrate.hcl` file is set, Atmos generates a config that stores history in the same bucket as the state. Provide your own config only to customize this behavior, for example:

```hcl
tfmigrate {
  migration_dir = "./tfmigrate"

  history {
    storage "s3" {
      bucket   = env.ATMOS_TFMIGRATE_HISTORY_BUCKET
      key      = env.ATMOS_TFMIGRATE_HISTORY_KEY
      region   = env.ATMOS_TFMIGRATE_HISTORY_REGION
      role_arn = env.ATMOS_TFMIGRATE_HISTORY_ROLE_ARN
    }
  }
}
```

Atmos authenticates the component identity before `tfmigrate` runs. The history storage client then inherits the same environment as the Terraform backend.

## Rerun Safety

Use history mode for automation. Single-file `tfmigrate apply path.hcl` can fail on rerun if state addresses already moved or were removed.

## Related

- [`atmos terraform migrate`](/cli/commands/terraform/migrate)
- [`atmos terraform migrate plan`](/cli/commands/terraform/migrate-plan)
- [`atmos terraform migrate list`](/cli/commands/terraform/migrate-list)