tf-migrate stacks prepare reference

The tf-migrate stacks prepare generates new Terraform configuration to migrate one or more HCP Terraform workspaces to a Stack.

Note

The feature to migrate a workspace to a Stack is currently in beta. Do not use beta functionality in production environments. To provide feedback while you test this feature, submit a response to our beta feedback form.

Usage

$ tf-migrate stacks prepare [options]

Description

The tf-migrate stacks prepare command prompts you for the following information:

A name for the Stack.
A name for the new project to deploy the Stack to. This project must not already exist.

The tf-migrate prepare command copies your configuration and local modules to create a new Terraform Stack configuration in the _stacks_generated directory. It also generates Terraform configuration to perform the migration in the stacks_migration_infra directory.

This command does not change your existing configuration, state, or deployed resources.

The tf-migrate stacks prepare command creates one Stack deployment block for each HCP Terraform workspace the configuration manages. If your configuration's cloud block targets a single workspace with the workspaces.name argument, tf-migrate creates one Stack deployment. If your configuration's cloud block targets multiple workspaces with the workspaces.tags argument, tf-migrate creates a Stack deployment for each workspace that matches those tags.

The following is an example is a terraform block that defines two tags, one named environment and another named application.

terraform {
  cloud {
    organization = "<ORG_NAME>"
    workspaces {
      tags = {
        "environment" = "development"
        "application" = "web"
      }
    }
  }
}

If this example matches two workspaces, tf-migrate creates two deployment blocks in the _stacks_generated/deployment.tfdeploy.hcl file and names them to match the workspace name.

deployment "web-dev-east" {
  inputs = {
    ##...
  }
  import = true
}



deployment "web-dev-west" {
  inputs = {
    ##...
  }
  import = true
}

Example

The tf-migrate stacks prepare command generates the configuration to migrate this HCP Terraform workspace to a Stack. The following example creates a Stack named my-new-stack in the my-project project.

$ tf-migrate stacks prepare
✓ Environment readiness checks completed
✓ Extracted terraform configuration data from current directory
Enter the name of the stack to be created:  my-stack
Enter the name of a new project under which the stack will be created (project must not already exist):  my-stack-proj
✓ Fetched latest state file for workspace: my-workspace
✓ Parsed state file for workspace: my-workspace
✓ Extracted variables  from terraform configuration
✓ Extracted providers from terraform configuration
✓ Extracted outputs blocks from terraform configuration
✓ Created components from module blocks from terraform configuration
✓ Created deployments for workspaces provided
✓ Stack configuration files generated successfully
✓ Completed sanity check: terraform stacks init
✓ Completed sanity check: terraform stacks fmt
✓ Completed sanity check: terraform stacks validate
 
─────────────────────────────────────────────────────────────────────────────
🎉 The `tf-migrate stacks prepare` command completed successfully.
─────────────────────────────────────────────────────────────────────────────
 
Next steps:
  1. Review the generated files before proceeding:
       a. _stacks_generated — contains Terraform Stacks configuration files.
       b. stacks_migration_infra — contains Terraform configuration files for creating stacks and migrating workspaces.
 
  2. Update all PLACEHOLDER values:
   - In output blocks (outputs.tfcomponent.hcl in _stacks_generated)
   - In deployment blocks (deployment.tfdeploy.hcl in _stacks_generated)
 
  3. Configure authentication if your stacks manage cloud resources
   (AWS, GCP, Azure, etc.):
   → https://developer.hashicorp.com/terraform/language/stacks/deploy/authenticate
 
  4. Apply the configuration once all updates are complete:
     run: `tf-migrate stacks execute` to start the migration.

Available options

You can include the following flags when you run the tf-migrate prepare command:

Option	Description	Default	Required
`-config-file`	Specifies the path to an optional configuration file. Refer to `tf-migrate` configuration file reference for more information.	None	No
`-skip-workspaces`	Specifies a comma-separated list of workspaces to exclude from the migration.	None	No