tf-migrate configuration file reference

This topic describes the parameters for configuring the tf-migrate CLI.

Configuration model

A tf-migrate configuration file supports the following parameters.

Migrate to HCP Terraform or Terraform Enterprise

When you migrate your Terraform Community Edition state and variable values to HCP Terraform or Terraform Enterprise with the tf-migrate prepare command, you can provide an optional configuration file with the following parameters.

• skip-dir: list of strings
• projects: list of objects
  • dir: string
  • workspaces: list of objects
    • name: string
    • env-vars: map
    • terraform-vars: list of strings

Migrate an HCP Terraform workspace to a Stack

When you use the tf-migrate modules create or tf-migrate stacks prepare commands, you can provide an optional configuration file with the following parameters.

• organization_name: string
• stack_project_name: string
• stacks_name: string
• workspace_config: map of objects
  • WORKSPACE: string
    • deployment_name: string
    • tf_vars_file: list of strings
    • env_vars: list of strings

Specification

This section provides details about the fields you can configure in a tf-migrate configuration file.

skip-dir

Specifies a list of paths to directories you want tf-migrate to skip. This parameter is identical to using the -skip-dir command-line flag. By default, tf-migrate processes all child directories containing Terraform configuration files.

• Data type: List of strings
• Default: None

projects

Specifies a list of project configurations that align with local directories. The tf-migrate tool creates one project in HCP Terraform or Terraform Enterprise per configuration. In each project, tf-migrate creates one workspace per local workspace.

• Data type: List of objects
• Default: None

projects.dir

Specifies the relative or absolute path to the Terraform configuration to migrate.

• Data type: String
• Default: None

projects.workspaces

Specifies workspace configurations in the project. Terraform creates a workspace in HCP Terraform or Terraform Enterprise for each workspace configuration. The following table describes the attributes you can configure in each item in the list of workspaces:

• Data type: List of objects
• Default: None

organization_name

Specifies the name of the organization that contains the workspaces to migrate to a Stack.

• Data type: String
• Default: None

stack_project_name

Specifics the name of the project to create when migrating workspaces to a Stack.

• Data type: String
• Default: None

stacks_name

Specifies the name of the Stack to create when migrating workspaces to a Stack.

• Data type: String
• Default: None

workspace_config

Specifies a list of workspaces to migrate to a Stack.

• Data type: Map of objects
• Default: None

workspace_config.<WORKSPACE>.deployment_name

Specifies the name of the deployment in the Stack.

• Data type: String
• Default: None

workspace_config.<WORKSPACE>.tf_vars_file

Specifies a list of Terraform variables files to use for configuring the Stack. Each file must end with either .tfvars or tfvars.json. The path can be a relative or absolute path.

• Data type: List of strings
• Default: None

workspace_config.<WORKSPACE>.env_vars

Specifies a map of environment variables to set during the migration. Each key must start with TF_VAR.

• Data type: List of strings
• Default: None

Example configuration files

Below are example configuration files to migrate workspaces.

Migrate local state to HCP Terraform workspace

The following example creates one project using data from the example/project1 directory. The project has a workspace named staging and a workspace named dev:

skip-dir = ["example/skip/dir1", "example/skip/dir2"]

projects = [
    {
        dir = "example/project1"
        workspaces = [
            {
                name = "staging"
                env-vars = {
                    "TF_VAR_region": "us-east-2"
                }
                terraform-vars = ["staging.tfvars"]
            },
            {
                name = "dev"
                terraform-vars = ["dev.tfvars"]
            }
        ]
    }
]

Migrate HCP Terraform workspace to a Stack

The following configuration creates a project named my-new-project and migrates the staging and dev workspaces to a Stack named my-migrated-stack.

organization_name  = "MyOrganization"
stack_project_name = "my-new-project"
stacks_name        = "my-migrated-stack"

workspace_config = { 
  "staging" = {
    deployment_name = "staging-deployment-"
    tf_vars_file    = ["terraform.tfvars", "terraform-2.tfvars"]
  }

   "dev" = {
    deployment_name = "dev-deployment-2"
    tf_vars_file    = ["terraform-3.tfvars"] 
    env_vars        = ["TF_VAR_bucket_name"]
  }
}

Move resources from the root module to a child module

By default, the tf-migrate modules create command uses the cloud block and map of tags in your configuration to find workspaces in HCP Terraform. If your configuration specifies a workspace by name, or it does not have a cloud block, you can provide a list of workspaces with a configuration file.

The configuration below uses the staging workspace in the MyOrganization organization when you provide it to the tf-migrate modules create command.

organization_name = "MyOrganization"
workspaces = ["staging"]