terraform stacks migrate translate-state reference

Use the terraform stacks migrate translate-state command to convert Terraform state files into Terraform Stack state artifacts.

Experimental

The terraform stacks migrate command group is experimental and disabled by default. Set TF_STACKS_MIGRATE_EXPERIMENTAL=true to enable these commands. Do not use these commands on production resources.

Usage

$ TF_STACKS_MIGRATE_EXPERIMENTAL=true terraform stacks <global-stacks-flags> migrate translate-state <options>

Relative paths are resolved from the working directory after applying -chdir.

Description

Use terraform stacks migrate translate-state after you translate your traditional configuration into a Stack configuration and you need state artifacts that match the translated configuration layout.

The command accepts a migrate manifest to translate all deployments declared in the manifest or explicit paths to translate one Terraform state file. When you use explicit paths, the command reads the following files:

A traditional Terraform state file
The original Terraform root module that produced the original .tfstate file
A translated Stack configuration containing the target components and deployments

This command writes .tfstackstate artifacts that you can use with the translated Stack configuration.

This command works only with local files. It does not create a Stack, upload configuration, or move remote state automatically.

Before you run the command, you must meet the following requirements:

Run terraform init in the original Terraform configuration directory so this command can reuse the .terraform.lock.hcl dependency lock file and installed provider cache.
Your translated Stack configuration must already exist locally.
Run terraform stacks init in the translated Stack configuration directory so the command can use the initialized local module bundle it needs for the translated component sources.
The translated Stack configuration is self-contained under -stack-config. Component sources and any nested local module sources must resolve within that directory tree.
Each generated .tfstackstate output path points to an existing writable directory and uses an unused filename.

On success, human-readable output includes the output path, component count, resource count, and output value count. JSON output includes the same summary plus component addresses, resource type counts, provider addresses, and output names when present.

Options

-migrate-manifest: The path to the migrate manifest to translate all deployments declared in the manifest. Mutually exclusive with -tfstate, -source-config, -stack-config, and -output.
- Optional.
- String.
-tfstate: The path to the traditional .tfstate file to translate.
- Required if you provide an explicit state file path.
- String.
-source-config: The directory containing the original Terraform root module that produced the original .tfstate file.
- Required if you provide an explicit state file path.
- String.
-stack-config: The directory containing the translated Stack configuration. The directory must contain component and deployment configuration files. All component sources and nested local module sources must resolve within this directory tree.
- Required if you provide an explicit state file path.
- String.
-output: The path to write the translated Stack state artifacts. The parent directory must already exist and be writable. The output file must not already exist. The command does not overwrite an existing artifact.
- Required if you provide an explicit state file path.
- String.
-json: Output results in JSON format instead of the default human-readable text format.
- Optional.
- Boolean flag.
- Default: false.

Examples

The following command translates all state files declared in the default migrate manifest:

$ TF_STACKS_MIGRATE_EXPERIMENTAL=true terraform stacks migrate translate-state

The following command translates the state files declared in a specific migrate manifest:

$ TF_STACKS_MIGRATE_EXPERIMENTAL=true terraform stacks migrate translate-state \
  -migrate-manifest=./migration/migrate-manifest.json

The following command translates one Terraform state file into a Terraform Stack state artifact:

$ TF_STACKS_MIGRATE_EXPERIMENTAL=true terraform stacks migrate translate-state \
  -tfstate=./workspace.tfstate \
  -source-config=./terraform \
  -stack-config=./stack \
  -output=./out/workspace.tfstackstate

The following command translates the state file and returns the result summary in JSON format:

$ TF_STACKS_MIGRATE_EXPERIMENTAL=true terraform stacks migrate translate-state \
  -tfstate=./workspace.tfstate \
  -source-config=./terraform \
  -stack-config=./stack \
  -output=./out/workspace.tfstackstate \
  -json

Global flags

Refer to Global flags reference for information about flags you can use with all commands.