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