tf-migrate prepare reference

The tf-migrate prepare command recursively scans the current directory for Terraform state files, then generates new Terraform configuration to migrate the state to HCP Terraform or Terraform Enterprise.

Usage

$ tf-migrate prepare [options]

Description

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

The HCP Terraform or Terraform Enterprise organization to migrate your state to.
If you would like to create a new branch named hcp-migrate-<BRANCH> where <BRANCH> is the name of the branch you currently have checked out.
If you would like it to automatically create a pull request with the updated code change when the migration is complete.
If you would like to create a CLI or VCS-driven workspace. Refer to supported workspace workflows for the requirements your configuration must meet to support a VCS-driven workspace.

The tf-migrate prepare command generates a new Terraform configuration in the _hcp-migrate-configs directory to perform the migration. This configuration creates the following resources:

One workspace per state file. The tf-migrate tool names the workspace following the <DIRECTORY NAME>-<LOCAL WORKSPACE NAME> pattern. The tf-migrate tool also creates workspace variables from the Terraform configuration's variables.
One project to store all workspaces. The tf-migrate tool uses the directory path to the state file as the project name. For example, if your configuration is stored at ./frontend/networking/terraform.tfstate, tf-migrate names the project "frontend_networking". Because of this, your directory path must be between 3-40 characters and only include letters, numbers, inner spaces, hyphens, and underscores.
A new local git branch if you responded to the prompt to create a new branch with yes.
A new pull request in the remote git repository if you responded to the prompt to create a pull request with yes.

The tf-migrate tool adds the generated configuration to the .gitignore file so that the configuration is not committed to source control.

The tf-migrate tool creates the following structure in HCP Terraform or Terraform Enterprise depending on your local configuration:

Source	Result
Single configuration, single state	Single HCP workspace
Single configuration, multiple states for each Community Edition workspace	One HCP workspace per state
Multiple configurations, one state per configuration	One HCP workspace per configuration
Multiple configurations, multiple states per configuration	One HCP workspace per combination of configuration and state

Example

The tf-migrate prepare command generates the configuration to migrate this state to a single HCP Terraform workspace.

$ tf-migrate prepare
✓ Current working directory: /tmp/learn-terraform-migrate
✓ Environment readiness checks completed
✓ Found 3 HCP Terraform organizations
┌────────────────────────────┐
│ Available Orgs             │
├────────────────────────────┤
│ my-org-1                   │
│ my-org-2                   │
│ my-org-3                   │
└────────────────────────────┘
Enter the name of the HCP Terraform organization to migrate to:  my-org-1
✓ You have selected organization my-org-1 for migration
 
Current repository was found on github.com. Do you want to create VCS-driven workspaces ... ?
 
Enter a value: yes
 
✓ Found 4 VCS providers 
┌────────────────────────────┬──────────────────┬─────────────────┐
│ Available VCS Providers    │ Service Provider │ OAuth Client ID │
├────────────────────────────┤──────────────────┤─────────────────┤
│ github-dev                 │ GitHub           │ oc-ABC123DEF456 │
│ github-internal            │ GitHub           │ oc-GHI789JKL012 │
└───────────────────────────────────────────────┴─────────────────┘
 
Enter the OAuth client ID of the VCS provider from the above list to create the VCS-driven workspace: oc-ABC123DEF456
 
✓ You have selected VCS provider GitHub for migration
✓ Found 2 directories with Terraform files
┌────────────────────────────────┐
│   Terraform File Directories   │
├────────────────────────────────┤
│ web                            │
│ api                            │
└────────────────────────────────┘
Create a local branch named hcp-migrate-main from the current branch main: ... ?
 
 
  Only 'yes or no' will be accepted as input.
  Type 'yes' to approve the step
  Type 'no' to to skip
 
 
Enter a value:  yes
 
✓ Successfully created branch hcp-migrate-main
Do you want to open a pull request from hcp-migrate-main ... ?
 
 
  Only 'yes or no' will be accepted as input.
  Type 'yes' to approve the step
  Type 'no' to to skip
 
 
Enter a value:  yes
 
✓ Migration config generation completed
✓ Successfully updated .gitignore

Available options

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

Option	Description	Default	Required
`-config`	Specifies the path to an optional configuration file. Refer to `tf-migrate` configuration file reference for more information.	None	No
`-hostname`	The hostname of your Terraform Enterprise server. If you do not provide a hostname, `tf-migrate` defaults to HCP Terraform.	`app.terraform.io`	No
`-skip-dir`	Specifies a comma-separated list of relative paths to exclude from the migration.	None	No
`--parallelism`	Specifies the number of threads `tf-migrate` uses to scan the local directory and prepare the migration. Set this value to `1` to disable parallelism.	The number of logical CPUs in the system.	No