Skip to main content

atmos terraform migrate

Use atmos terraform migrate to run user-authored tfmigrate migrations in an Atmos Terraform component context.

Experimental
atmos terraform migrate
Configure Tfmigrate Hooks

Run migrations automatically from Terraform lifecycle hooks.

atmos terraform migrate --help


 █████  ████████ ███    ███  ██████  ███████ 
██   ██    ██    ████  ████ ██    ██ ██      
███████    ██    ██ ████ ██ ██    ██ ███████ 
██   ██    ██    ██  ██  ██ ██    ██      ██ 
██   ██    ██    ██      ██  ██████  ███████ 
                                             

👽 test darwin/arm64

Run tfmigrate in an Atmos Terraform component context.

  Atmos prepares the component the same way it does for Terraform operations:
  it resolves the stack/component, authenticates, generates backend and
  variable files, initializes the working directory unless skipped, selects
  the Terraform workspace, and then runs tfmigrate.

USAGE

                                                     
    $ atmos terraform migrate [sub-command] [flags]  
                                                     

AVAILABLE COMMANDS

      apply  Apply a migrated Terraform state with tfmigrate
      list   List Terraform component instances with tfmigrate context
      plan   Compute a migrated Terraform state with tfmigrate

FLAGS

  -h, --help  help for migrate


GLOBAL FLAGS

      --ai                        Enable AI-powered analysis of command output

      --append-user-agent string  Customize User-Agent string in Terraform provider requests (sets
                                  TF_APPEND_USER_AGENT)

      --base-path string          Base path for Atmos project

  -C, --chdir string              Change working directory before executing the command (run as if Atmos started in
                                  this directory)

      --clone-target-ref          Clone the target reference with which to compare the current branch

      --components strings        Filter by specific components

      --config strings            Paths to configuration files (comma-separated or repeated flag)

      --config-path strings       Paths to search for Atmos configuration (comma-separated or repeated flag)

      --dry-run                   Perform dry run without making actual changes

      --force-color               Force color output even when not a TTY (useful for screenshots)

      --force-tty                 Force TTY mode with sane defaults when terminal detection fails (useful for
                                  screenshots)

      --heatmap                   Show performance heatmap visualization after command execution (includes P95
                                  latency)

      --heatmap-mode string       Heatmap visualization mode: bar, sparkline, table (press 1-3 to switch in TUI)
                                  (default bar)

  -i, --identity string           Specify the identity to authenticate to before running Terraform commands. Use
                                  without value to interactively select.

      --include-dependents        For each affected component, detect the dependent components and process them in the
                                  dependency order

      --init-pass-vars            Pass the generated varfile to terraform init using --var-file flag (OpenTofu feature)

      --interactive               Enable interactive prompts for missing required flags, optional value flags using
                                  the sentinel pattern, and missing positional arguments (requires TTY, disabled in
                                  CI) (default true)

      --logs-file string          The file to write Atmos logs to. Logs can be written to any file or any standard
                                  file descriptor, including '/dev/stdout', '/dev/stderr' and '/dev/null' (default
                                  /dev/stderr)

      --logs-level string         Logs level. Supported log levels are Trace, Debug, Info, Warning, Off. If the log
                                  level is set to Off, Atmos will not log any messages (default Warning)

      --mask                      Enable automatic masking of sensitive data in output (use --mask=false to disable)
                                  (default true)

      --no-color                  Disable color output

      --pager string              Enable pager for output (--pager or --pager=true to enable, --pager=false to disable, --
                                  pager=less to use specific pager)

      --process-functions         Enable/disable YAML functions processing in Atmos stack manifests (default true)

      --process-templates         Enable/disable Go template processing in Atmos stack manifests (default true)

      --profile strings           Activate configuration profiles (comma-separated or repeated flag)

      --profile-file string       Write profiling data to file instead of starting server

      --profile-type string       Type of profile to collect when using --profile-file. Options: cpu, heap, allocs,
                                  goroutine, block, mutex, threadcreate, trace (default cpu)

      --profiler-enabled          Enable pprof profiling server

      --profiler-host string      Host for pprof profiling server (default localhost)

      --profiler-port int         Port for pprof profiling server (default 6060)

  -q, --query string              Execute atmos terraform command on components filtered by a YQ expression

      --redirect-stderr string    File descriptor to redirect stderr to. Errors can be redirected to any file or any
                                  standard file descriptor (including '/dev/null')

      --ref string                Git reference with which to compare the current branch

      --repo-path string          Filesystem path to the already cloned target repository with which to compare the
                                  current branch

      --sha string                Git commit SHA with which to compare the current branch

      --skill strings             Specify skills for AI analysis context (comma-separated or repeated flag, requires --
                                  ai)

      --skip strings              Skip executing specific YAML functions in the Atmos stack manifests

      --skip-hooks string         Skip lifecycle hooks for this invocation. Use --skip-hooks (no value) to skip all, or --
                                  skip-hooks=name1,name2 to skip specific hooks by name

      --skip-init                 Skip terraform init before running command

      --ssh-key string            Path to PEM-encoded private key to clone private repos using SSH

      --ssh-key-password string   Encryption password for the PEM-encoded private key if the key contains a password-
                                  encrypted PEM block

  -s, --stack string              Stack name

      --upload-status             Upload plan status to Atmos Pro

      --use-version string        Use a specific version of Atmos (e.g., --use-version=1.160.0)

  -v, --verbose                   Enable verbose error output with full context, stack traces, and detailed
                                  information



Use atmos terraform migrate [command] --help for more information about a
command.

Usage​

atmos terraform migrate <subcommand> [component] [options]

Atmos prepares the component before tfmigrate runs. Source provisioning, workdir provisioning, generated backend files, generated varfiles, auth identity setup, and Terraform workspace selection all happen first.

Arguments​

subcommand
Migration action to run. Supported values are plan, apply, and list.
component
Atmos Terraform component to migrate or inspect. Omit when selecting multiple components with flags such as --all, --components, --query, or (for plan and apply) --affected.

Flags​

--stack / -s
Atmos stack where the component is defined.
--identity / -i
Identity to authenticate before resolving the component and running tfmigrate. Environment variable: ATMOS_IDENTITY.
--migration
A single tfmigrate migration file for plan or apply. tfmigrate resolves the value relative to the migration_dir set in its config (default .). Pass just the filename when migration_dir already points at your migrations directory. Omit this flag to let tfmigrate run history mode.
--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, --components, --query, --affected
Select multiple Terraform component instances instead of passing one component argument. --affected applies to plan and apply only. list supports --all, --components, and --query.
--skip-init
Skip the normal Terraform init path before tfmigrate runs.

Authentication​

atmos terraform migrate uses the same identity flow as other Terraform commands. Pass an identity explicitly when the migration needs cloud credentials for backend access, YAML functions, source provisioning, or tfmigrate history storage:

atmos terraform migrate plan s3-bucket -s plat-ue2-dev --identity aws-prod --tfmigrate-config .tfmigrate.hcl

You can also use ATMOS_IDENTITY:

ATMOS_IDENTITY=aws-prod atmos terraform migrate apply s3-bucket -s plat-ue2-dev --tfmigrate-config .tfmigrate.hcl

When no identity is provided, Atmos can use the component or stack default identity. Use --identity without a value to select interactively, or --identity=false to disable authentication for the command.

Subcommands​

Examples​

Preview history-mode migrations:

atmos terraform migrate plan s3-bucket -s plat-ue2-dev

Apply history-mode migrations:

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

List migration context and history settings:

atmos terraform migrate list -s plat-ue2-dev

How Atmos Runs tfmigrate​

For every selected component instance, Atmos:

  • Resolves the stack/component with the standard Terraform command flags.
  • Authenticates the configured Atmos identity before migration.
  • Runs the normal Terraform init path unless --skip-init is set.
  • Selects the configured Terraform workspace.
  • Resolves tfmigrate and Terraform/OpenTofu through the Atmos toolchain or PATH.
  • Sets TFMIGRATE_EXEC_PATH to the resolved Terraform/OpenTofu binary unless already set.
  • Routes the generated varfile into tfmigrate's internal Terraform plans via TF_CLI_ARGS_plan. This lets components with required variables plan cleanly.
  • Generates a default tfmigrate config when you have not provided one. The default reuses the component's Terraform backend as history storage.
  • Pre-creates the parent directory of a storage "local" history path from the tfmigrate config. This prevents the first history save from failing on a missing directory.
  • Exports per-instance history helper variables for the tfmigrate config.

History Mode​

Enable tfmigrate history mode by omitting --migration:

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

History storage works with zero configuration. When the component has no .tfmigrate.hcl, and no --tfmigrate-config or TFMIGRATE_CONFIG, Atmos generates a tfmigrate config that reuses the component's Terraform backend:

  • S3 backend — Atmos stores history in the same bucket, under tfmigrate/<stack>/<component>/<workspace>/history.json. It inherits the region, profile, assume-role ARN, KMS key, and custom endpoint.
  • GCS backend — Atmos stores history in the same bucket, under the same namespaced object name.
  • Local or other backends — Atmos stores history as a local file next to the local-backend state file, or under the component working directory. Atmos creates the directory automatically.

The generated config points migration_dir at the component's migrations/ directory when one exists, the component root otherwise.

To take control, add a .tfmigrate.hcl file to the component, or point at one explicitly. Atmos discovers a component-local file automatically, and skips the generated default entirely:

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

History Variables​

Atmos sets these variables for use from the tfmigrate config via env:

ATMOS_STACK
The selected Atmos stack.
ATMOS_COMPONENT
The selected Terraform component instance.
ATMOS_TERRAFORM_WORKSPACE
The selected Terraform workspace, or default when none is configured.
ATMOS_TFMIGRATE_HISTORY_NAMESPACE
tfmigrate/&lt;stack&gt;/&lt;component&gt;/&lt;workspace&gt;.
ATMOS_TFMIGRATE_HISTORY_KEY
tfmigrate/&lt;stack&gt;/&lt;component&gt;/&lt;workspace&gt;/history.json.
ATMOS_TFMIGRATE_HISTORY_BUCKET
Copied from the component Terraform backend when the backend is S3 or GCS.
ATMOS_TFMIGRATE_HISTORY_REGION, ATMOS_TFMIGRATE_HISTORY_PROFILE, ATMOS_TFMIGRATE_HISTORY_ROLE_ARN
Copied from supported S3 backend settings.

Atmos namespaces the history key by stack, component, and workspace. This avoids collisions when multiple Atmos component instances share the same Terraform backend bucket.

Rerun Safety​

Single-file tfmigrate apply path.hcl is not inherently idempotent. A rerun can fail if a state mv source or state rm address already changed.

For CI, use tfmigrate history mode with durable storage such as S3, GCS, or a local file persisted by the workflow runner.

Related​