Migrate a workspace to a Stack

You can use tf-migrate to migrate an HCP Terraform workspace to a Stack. Refer to the Stacks documentation for more information on Stacks.

Hands-on: Try the Migrate a workspace to a Stack tutorial.

Overview

Complete the following steps to migrate an HCP Terraform workspace to a Stack with tf-migrate:

1. If your Terraform configuration defines any resources in your root module, you must first convert your root module into a child module. If your root module only creates resources in child modules, you can skip this step. Refer to Modularize configuration for more information on this process.
2. Run the tf-migrate stacks prepare command to generate your Terraform Stack, prepare your state, and generate Terraform configuration to deploy the Stack. Refer to Prepare Stack migration for more information.
3. Optionally, configure your cloud provider credentials. You can authenticate Stacks by using OIDC or by accessing existing authentication credentials. Refer to the Authenticate a Stack documentation for more information.
4. Run the tf-migrate stacks execute command to perform the migration. Refer to Execute Stack migration for more information.
5. Optionally, remove the import = true argument from the deployment block to make changes to the deployed Stack. Refer to Modify migrated Stack for more information.

Requirements

The tf-migrate CLI requires the following to migrate an HCP Terraform workspace to a Stack:

• tf-migrate 2.0+ installed locally.
• Terraform 1.13+ installed locally.
• Terraform configuration deployed to one or more HCP Terraform workspaces.
• Terraform Stacks enabled in your HCP Terraform organization. Refer to create a Stack for more information.

Optionally, if your configuration requires credentials to authenticate with a cloud provider, you must create an organization-wide variable set. Refer to the Authenticate a Stack documentation for more information.

Modularize configuration

Convert your Terraform configuration into child modules by moving any resource configurations from the root module into children. You can use the tf-migrate CLI to create a converted copy of your existing configuration or convert the configuration manually.

Use the CLI to convert configuration

You can use the tf-migrate modules create command to copy your configuration, convert your root module into a child module, then save the converted configuration into a directory named modularized_config. The command does not modify your existing configuration or state.

$ tf-migrate modules create
✓ Found 4 terraform files in the root directory
✓ Extracted HCP Terraform data to identify the workspaces controlled by the configuration.
 
You're about to begin the modularization process. read the following important notes carefully:
 1. A folder named modularized_config will be created to store the modularized configuration generated from your current setup.
 2. All directories containing locally referenced modules will be copied into the modularized_config folder.
 3. The modularized_config folder must not already exist in the current working directory.
 4. All folders for locally referenced modules must be located within the current working directory where Terraform Migrate is being run.
 
Kindly confirm that you have read and understood the warning message above. Do you want to proceed ... ?
 
 
  Only 'yes' or 'no' will be accepted as input.
  Type 'yes' to approve proceed with modularization process
  Type 'no' to abort the modularization process
 
 
Enter a value:  yes
 
✓ Found 1 HCP Terraform workspaces associated with the configuration.
✓ Successfully generated modularized config in modularized_config
✓ Modularization process completed successfully

Before you can migrate a converted configuration to a Stack, you must initialize the updated configuration.

First, change to the new modularized_config directory:

$ cd modularized_config

Next, initialize the configuration:

$ terraform init

After initializing your configuration, prepare the Stack migration in the modularized_config directory.

Refer to the tf-migrate modules create reference documentation for more information.

Manual conversion

You can instead convert the configuration manually rather than use the tf-migrate modules create command. The following example is a complete root module that has been modularized. It defines one provider and one output. All resources this configuration manages are defined in the string module:

terraform {
  required_providers {
    random = {
      source  = "hashicorp/random"
      version = "3.7.2"
    }
  }
  cloud {
    organization = "my-organization"
    workspaces {
      name = "my-workspace"
    }
  }
}

provider "random" {}

module "string" {
  source = "./modules/strings"
  length = 16
}

output "string" {
  value = module.string
}

Prepare Stack migration

Use the tf-migrate stacks prepare command to generate configuration for a Stack, as well as Terraform configuration to deploy the Stack to HCP Terraform. This command does not modify your existing configuration or state.

$ 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 the project under which stack is to be created:  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
 
Please review the generated files in the stacks directory before proceeding to execute:
  1. Add stack authentication - https://developer.hashicorp.com/terraform/language/stacks/deploy/authenticate
  2. Resolve any PLACEHOLDER values for output block types, if any.
  3. Resolve any PLACEHOLDER values for deployment input attributes, if any.

The tf-migrate stacks prepare command creates the following directories:

• The _stacks_generated directory contains the generated Stack configuration. Refer to the Define Stack configuration documentation for more information on this configuration.
• The stacks_migration_infra directory contains Terraform configuration to deploy the generated Stack configuration to HCP Terraform.

Refer to the tf-migrate stacks prepare reference documentation for more information.

Execute Stack migration

Use the tf-migrate stacks execute command to deploy the Stack configuration generated with the tf-migrate stacks prepare command.

$ tf-migrate stacks execute
✓ Stack configuration path found: /tmp/my_config/modularized_config/_stacks_generated
✓ Successfully validated stack configuration found in dir: /tmp/my_config/modularized_config/_stacks_generated
✓ Init command ran successfully
✓ Plan command ran successfully and changes are detected
✓ Apply command ran successfully in 2m17.128786916s
Apply complete! Resources: 3 added, 0 changed, 0 destroyed.
 
 
Migration Summary
┌─────────┬────────────────────────────────────────────────────────────────────────────────────────────────┐
│ Item    │ URL                                                                                            │
├─────────┼────────────────────────────────────────────────────────────────────────────────────────────────┤
│ Project │ https://app.terraform.io/app/<ORG>/projects/prj-zcHA23BCD4EFGHij                              │
│ Stack   │ https://app.terraform.io/app/<ORG>/projects/prj-zcHA23BCD4EFGHij/stacks/st-ab1CDefGHijKlmNo    │
└─────────┴────────────────────────────────────────────────────────────────────────────────────────────────┘

Refer to the tf-migrate stacks execute reference documentation for more information.

Next steps

After you complete the migration, you can modify your Stack configuration in the _stacks_generated directory. This directory contains your Stack components and configuration and you can move or rename this folder.

When tf-migrate generates your Stack configuration, it includes the import = true argument in the deployment block in the deployment.tfdeploy.hcl file. This argument tells HCP Terraform that it should not apply the configuration, and instead allows you to manually upload your Stack state.

If you want to make changes to your migrated Stack, you must remove the import flag or set its value to false.

deployment "my-workspace" {
  inputs = { }
-  import = true
}

You can use the following methods to deploy changes to your Stack:

• Run the terraform stacks CLI commands. For more information, refer to the terraform stacks reference documentation.
• Use the HCP Terraform API. For more information, refer to the Stacks API reference documentation.
• Commit your Stack configuration to source control and connect your stack to a VCS repository. For more information, refer to the Configure a Stack documentation.