hooks-tfmigrate

Demonstrates the tfmigrate hook kind. This hook runs a Terraform state migration through atmos terraform migrate before Terraform plan and apply operations.

Watch this example as a recorded demo in the Terraform state migrations with tfmigrate changelog post, or in the atmos terraform migrate command docs.

What this shows

• kind: tfmigrate with mode: dynamic.
• before.terraform.plan previews the migration with tfmigrate plan.
• before.terraform.apply applies the migration with tfmigrate apply.
• Zero tfmigrate configuration. With no .tfmigrate.hcl, Atmos generates one that reuses the component's Terraform backend for tfmigrate history storage. This makes reruns safe after Atmos already applied the migration. Here the backend is local, so history lands next to the state file. With an S3 or GCS backend, history goes to the same bucket under a namespaced key. Provide your own .tfmigrate.hcl file, or use the hook's config: field, to override.
• Local Terraform state keeps the example self-contained and avoids cloud credentials. Terraform workspaces are disabled so both components share the same local state file.

Requirements

Nothing needs to be pre-installed. The components declare opentofu and tfmigrate in dependencies.tools. The Atmos toolchain downloads both automatically on first run, into the git-ignored .tools/ directory. No cloud credentials are needed either. The example uses local Terraform state.

If you prefer managing the tools yourself, install them on PATH instead, for example with Homebrew:

brew install opentofu minamijoyo/tfmigrate/tfmigrate

Run

Start in this example directory:

cd examples/hooks-tfmigrate

Seed old state with the legacy component. This creates a local state file containing random_pet.legacy.

atmos terraform apply service-legacy -s test -auto-approve

Inspect the migration context that Atmos will pass to tfmigrate:

atmos terraform migrate list service -s test

Preview the refactored component. The hook runs tfmigrate plan first. Because mode: dynamic only previews during before.terraform.plan, the Terraform plan can still show the old address moving until apply time.

atmos terraform plan service -s test

Apply the refactored component. The hook runs tfmigrate apply before Terraform apply. This moves random_pet.legacy to random_pet.service in state. The Terraform apply should then converge without replacing the random pet.

atmos terraform apply service -s test

Run the plan again. History mode records the applied migration, so tfmigrate does not try to move the address a second time.

atmos terraform plan service -s test

Files

• stacks/deploy/test.yaml configures the legacy and refactored components.
• components/terraform/service-legacy/ creates the original state address.
• components/terraform/service/ contains the refactored address.
• components/terraform/service/migrations/ contains the migration HCL. Atmos points the generated tfmigrate config at this directory automatically. The local history file is written under state/tfmigrate/, which is ignored by git.

Notes

Atmos executes tfmigrate from the component working directory, so migration files live beside the component. In production, confirm the migration context with atmos terraform migrate list.