terraform stacks migrate reference

Use the terraform stacks migrate commands to migrate traditional Terraform workspaces to Terraform Stacks.

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 <subcommand>

Description

The terraform stacks migrate command group lets you migrate HCP Terraform workspaces to Terraform Stacks. The commands use a migrate manifest to describe the source configuration, the translated stacks configuration, deployment inputs, and state artifact paths.

The workflow supports local migration preparation. It does not create a Stack in HCP Terraform, upload configuration, or move remote state automatically.

Workflow

Migrate commands use the following local workflow:

Run prepare-manifest to generate a migrate manifest from one or more HCP Terraform workspaces and download each workspace's Terraform state file.
Run validate-manifest to confirm the manifest and expected filesystem layout are valid.
Run translate-config to generate the Stack configuration in the directory that the manifest references.
Review the generated code and make the changes required to source-sensitive inputs.
Run translate-state to generate local .tfstackstate artifacts for the translated Stack configuration.
Upload the generated Stack configuration and complete the migration in the HCP Terraform UI.

Refer to Migrate HCP Terraform workspaces to Terraform Stacks for an end-to-end migration workflow.

Subcommands

prepare-manifest - Generate a migrate manifest from HCP Terraform workspaces.
translate-config - Translate a traditional Terraform root module into Terraform Stack configuration.
translate-state - Convert Terraform state files into Terraform Stack state artifacts.
validate-manifest - Validate a migrate manifest and its expected filesystem layout.

Migrate manifest

A migrate manifest is a JSON file that describes the local migration workspace. By default, commands read or write migrate-manifest.json in the working directory after applying the -chdir flag.

The following example shows the manifest structure:

{
  "version": 1,
  "source_configuration": "./source-config",
  "stacks_configuration": "./stack-config",
  "deployments": [
    {
      "name": "prod",
      "workspace_id": "ws-prod",
      "inputs": [
        {
          "key": "region",
          "value": "us-east-1",
          "hcl": false,
          "sensitive": false,
          "category": "terraform"
        }
      ],
      "state": {
        "tfstate": "./tfstates/prod.tfstate",
        "tfstackstate": "./tfstackstates/prod.tfstackstate"
      }
    }
  ]
}

The manifest supports the following fields:

Field	Description
`version`	Manifest format version. The supported version is `1`.
`source_configuration`	Path to the traditional Terraform root module. Relative paths resolve from the manifest location.
`stacks_configuration`	Path to the translated Terraform Stack configuration. Relative paths resolve from the manifest location.
`deployments[].name`	Deployment name. `prepare-manifest` uses the HCP Terraform workspace name.
`deployments[].workspace_id`	HCP Terraform workspace ID. This field can be omitted for deployments that do not map to an HCP Terraform workspace.
`deployments[].inputs`	Deployment inputs derived from workspace variables.
`deployments[].inputs[].key`	Input name. `prepare-manifest` removes the `TF_VAR_` prefix from environment variables that HCP Terraform passes to Terraform as input variables.
`deployments[].inputs[].value`	Input value. Sensitive variables omit `value` because HCP Terraform does not return sensitive values from the API.
`deployments[].inputs[].hcl`	Indicates whether HCP Terraform interprets the value as HCL.
`deployments[].inputs[].sensitive`	Indicates whether the value is sensitive. All deployments must use the same sensitivity setting for matching input keys.
`deployments[].inputs[].category`	HCP Terraform variable category, such as `terraform` or `env`.
`deployments[].state.tfstate`	Path to the traditional Terraform state file for the deployment. Relative paths resolve from the manifest location.
`deployments[].state.tfstackstate`	Path where `translate-state` writes the translated local Terraform Stack state artifact. Relative paths resolve from the manifest location.

Global flags

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