atmos terraform migrate apply

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

Experimental

atmos terraform migrate apply --help

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

👽 test darwin/arm64

Apply a migrated Terraform state with tfmigrate

USAGE

                                                         
    $ atmos terraform migrate apply [component] [flags]  
                                                         

FLAGS

      --affected                           Run migrations for the affected components in dependency order

      --all                                Run migrations for all components in all stacks

      --auto-generate-backend-file string  Override auto_generate_backend_file setting from atmos.yaml (true/false)

      --backend-config strings             Backend configuration passed to tfmigrate; may be specified multiple times

  -h, --help                               help for apply

      --init-run-reconfigure string        Override init_run_reconfigure setting from atmos.yaml (true/false)

      --migration string                   Path to a single tfmigrate migration file. Omit to let tfmigrate run history mode

      --tfmigrate-config string            Override tfmigrate config path. Defaults to tfmigrate discovery


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


COMPATIBILITY FLAGS

  These flags are passed through to the underlying terraform/tofu command.

      -auto-approve      Skip interactive approval of plan before applying
      -backup            Path to backup the existing state file
      -compact-warnings  Show warnings in a more compact form
      -destroy           Destroy all remote objects managed by the configuration
      -input             Ask for input for variables if not directly set (default: true)
      -json              Output apply results in JSON format
      -lock              Lock the state file when locking is supported (default: true)
      -lock-timeout      Duration to retry a state lock (default: 0s)
      -no-color          Disable color output in the command output
      -parallelism       Limit the number of concurrent operations (default: 10)
      -refresh           Update state prior to checking for differences (default: true)
      -refresh-only      Update state only, no resource changes
      -replace           Force replacement of a particular resource instance
      -state             Path to read and save state
      -state-out         Path to write updated state
      -target            Target specific resources for planning/applying
      -var               Set a value for one of the input variables
      -var-file          Load variable values from the given file

Usage

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:

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

Apply with an explicit identity:

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

Apply a single-file migration:

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:

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:

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
• atmos terraform migrate plan
• atmos terraform migrate list