From 587b9fe6e7134dfa83a5c0eac9f63b1fcf7c0a49 Mon Sep 17 00:00:00 2001 From: Brian McClain Date: Sun, 18 May 2025 00:00:24 -0400 Subject: [PATCH 1/6] Add documentation for tf-migrate VCS-driven workspaces --- .../docs/cloud-docs/migrate/tf-migrate/index.mdx | 9 ++++++++- .../migrate/tf-migrate/reference/prepare.mdx | 16 ++++++++++++++++ 2 files changed, 24 insertions(+), 1 deletion(-) diff --git a/website/docs/cloud-docs/migrate/tf-migrate/index.mdx b/website/docs/cloud-docs/migrate/tf-migrate/index.mdx index 128a3d847..bba1f0a3d 100644 --- a/website/docs/cloud-docs/migrate/tf-migrate/index.mdx +++ b/website/docs/cloud-docs/migrate/tf-migrate/index.mdx @@ -101,7 +101,6 @@ To configure your API token, set the `TF_GIT_PAT_TOKEN` environment variable $ export TF_GIT_PAT_TOKEN= ``` - ## Supported backends The `tf-migrate` tool supports migrating state from the following backends to HCP Terraform or Terraform Enterprise: @@ -119,6 +118,14 @@ The `tf-migrate` tool supports migrating state from the following backends to HC `tf-migrate` does not support migrating state from an existing `cloud` integration or `remote` backend. +## Supported workspace workflows + +The `tf-migrate` tool supports creating HCP Terraform workspaces configured to use the CLI or the VCS workflow. + +If your local configuration is a Git repository and has either GitHub or GitLab configured as a remote, `tf-migrate` asks you to confirm that you would like to create a VCS-driven workspace. If you have more than one VCS connection configured in your HCP Terraform organization, `tf-migrate` also asks you to choose which VCS connection to use. + +If your local configuration is not a Git repository, or does not use one of the supported remotes, `tf-migrate` automatically creates a CLI-driven workspace instead. + ## Enable logging You can enable detailed logging by setting the `TF_MIGRATE_ENABLE_LOG` environment variable to `true`. When you enable this setting, `tf-migrate` writes the logs to the following locations, depending on your operating system: diff --git a/website/docs/cloud-docs/migrate/tf-migrate/reference/prepare.mdx b/website/docs/cloud-docs/migrate/tf-migrate/reference/prepare.mdx index d695179f9..bb6bda07e 100644 --- a/website/docs/cloud-docs/migrate/tf-migrate/reference/prepare.mdx +++ b/website/docs/cloud-docs/migrate/tf-migrate/reference/prepare.mdx @@ -61,6 +61,22 @@ $ tf-migrate prepare └────────────────────────────┘ 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 │ From 002e6ffef05fa1d6f7b66f676687811b4c92a3d4 Mon Sep 17 00:00:00 2001 From: Brian McClain Date: Sun, 18 May 2025 00:15:33 -0400 Subject: [PATCH 2/6] Update requirements --- website/docs/cloud-docs/migrate/tf-migrate/index.mdx | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/website/docs/cloud-docs/migrate/tf-migrate/index.mdx b/website/docs/cloud-docs/migrate/tf-migrate/index.mdx index bba1f0a3d..c0636566b 100644 --- a/website/docs/cloud-docs/migrate/tf-migrate/index.mdx +++ b/website/docs/cloud-docs/migrate/tf-migrate/index.mdx @@ -120,11 +120,15 @@ The `tf-migrate` tool supports migrating state from the following backends to HC ## Supported workspace workflows -The `tf-migrate` tool supports creating HCP Terraform workspaces configured to use the CLI or the VCS workflow. +The `tf-migrate` tool supports creating HCP Terraform workspaces configured to use the CLI or the VCS workflow. The `tf-migrate` tool will only prompt to ask if you want to create a VCS-driven workspace if you meet the following requirements: -If your local configuration is a Git repository and has either GitHub or GitLab configured as a remote, `tf-migrate` asks you to confirm that you would like to create a VCS-driven workspace. If you have more than one VCS connection configured in your HCP Terraform organization, `tf-migrate` also asks you to choose which VCS connection to use. +- Your local configuration is a Git repository +- Your local Git repository has either GitHub or GitLab configured as a remote +- Your HCP Terraform organization has at least one VCS OAuth connection configured for GitHub or GitLab `tf-migrate` -If your local configuration is not a Git repository, or does not use one of the supported remotes, `tf-migrate` automatically creates a CLI-driven workspace instead. +If you have more than one VCS connection configured in your HCP Terraform organization, `tf-migrate` also asks you to choose which VCS connection to use. + +If your local configuration does not meet all of the above requirements, `tf-migrate` automatically creates a CLI-driven workspace instead. ## Enable logging From d37e422a17c29595c9fe5fa6710901e333e5abd7 Mon Sep 17 00:00:00 2001 From: Brian McClain Date: Sun, 18 May 2025 00:18:56 -0400 Subject: [PATCH 3/6] Add VCS-driven workspace information to the prepare command useage doc --- .../docs/cloud-docs/migrate/tf-migrate/reference/prepare.mdx | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/website/docs/cloud-docs/migrate/tf-migrate/reference/prepare.mdx b/website/docs/cloud-docs/migrate/tf-migrate/reference/prepare.mdx index bb6bda07e..423c1a39f 100644 --- a/website/docs/cloud-docs/migrate/tf-migrate/reference/prepare.mdx +++ b/website/docs/cloud-docs/migrate/tf-migrate/reference/prepare.mdx @@ -21,6 +21,7 @@ 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-` where `` 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](/terraform/cloud-docs/migrate/tf-migrate#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: @@ -29,7 +30,7 @@ The `tf-migrate prepare` command generates a new Terraform configuration in the - 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` CLI tool adds the generated configuration to the `.gitignore` file so that the configuration is not committed to source control. +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: From d3a5dfbf999852d5e3ece83275d5bdc753b1d95c Mon Sep 17 00:00:00 2001 From: Brian McClain Date: Mon, 19 May 2025 11:08:36 -0400 Subject: [PATCH 4/6] Add version callout for VCS-driven workspaces --- website/docs/cloud-docs/migrate/tf-migrate/index.mdx | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/website/docs/cloud-docs/migrate/tf-migrate/index.mdx b/website/docs/cloud-docs/migrate/tf-migrate/index.mdx index c0636566b..901182726 100644 --- a/website/docs/cloud-docs/migrate/tf-migrate/index.mdx +++ b/website/docs/cloud-docs/migrate/tf-migrate/index.mdx @@ -122,9 +122,10 @@ The `tf-migrate` tool supports migrating state from the following backends to HC The `tf-migrate` tool supports creating HCP Terraform workspaces configured to use the CLI or the VCS workflow. The `tf-migrate` tool will only prompt to ask if you want to create a VCS-driven workspace if you meet the following requirements: -- Your local configuration is a Git repository -- Your local Git repository has either GitHub or GitLab configured as a remote -- Your HCP Terraform organization has at least one VCS OAuth connection configured for GitHub or GitLab `tf-migrate` +- You are using version 1.1.0 or newer of `tf-migrate`. +- Your local configuration is a Git repository. +- Your local Git repository has either GitHub or GitLab configured as a remote. +- Your HCP Terraform organization has at least one VCS OAuth connection configured for GitHub or GitLab `tf-migrate`. If you have more than one VCS connection configured in your HCP Terraform organization, `tf-migrate` also asks you to choose which VCS connection to use. From 9a1ee2e3c90f0c9f6edc692c88f9a7a205dc125e Mon Sep 17 00:00:00 2001 From: Brian McClain Date: Tue, 20 May 2025 11:22:20 -0400 Subject: [PATCH 5/6] Apply suggestions from code review Co-authored-by: rita <8647768+ritsok@users.noreply.github.com> --- website/docs/cloud-docs/migrate/tf-migrate/index.mdx | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/website/docs/cloud-docs/migrate/tf-migrate/index.mdx b/website/docs/cloud-docs/migrate/tf-migrate/index.mdx index 901182726..66c65e99b 100644 --- a/website/docs/cloud-docs/migrate/tf-migrate/index.mdx +++ b/website/docs/cloud-docs/migrate/tf-migrate/index.mdx @@ -120,14 +120,15 @@ The `tf-migrate` tool supports migrating state from the following backends to HC ## Supported workspace workflows -The `tf-migrate` tool supports creating HCP Terraform workspaces configured to use the CLI or the VCS workflow. The `tf-migrate` tool will only prompt to ask if you want to create a VCS-driven workspace if you meet the following requirements: +Versions 1.1.0 and newer of `tf-migrate` can create CLI- or VCS-driven HCP Terraform workspaces. + +The `tf-migrate` tool will only prompt you to create a VCS-driven workspace if you meet the following requirements: -- You are using version 1.1.0 or newer of `tf-migrate`. - Your local configuration is a Git repository. - Your local Git repository has either GitHub or GitLab configured as a remote. - Your HCP Terraform organization has at least one VCS OAuth connection configured for GitHub or GitLab `tf-migrate`. -If you have more than one VCS connection configured in your HCP Terraform organization, `tf-migrate` also asks you to choose which VCS connection to use. +If your HCP Terraform organization has more than one VCS connection configured, `tf-migrate` will ask you to choose which VCS connection to use. If your local configuration does not meet all of the above requirements, `tf-migrate` automatically creates a CLI-driven workspace instead. From 69ba9388ca0bbfd2e25c3e484ea3c473eb5db4c1 Mon Sep 17 00:00:00 2001 From: Brian McClain Date: Tue, 20 May 2025 11:28:54 -0400 Subject: [PATCH 6/6] Update website/docs/cloud-docs/migrate/tf-migrate/index.mdx --- website/docs/cloud-docs/migrate/tf-migrate/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/cloud-docs/migrate/tf-migrate/index.mdx b/website/docs/cloud-docs/migrate/tf-migrate/index.mdx index 66c65e99b..d706b22eb 100644 --- a/website/docs/cloud-docs/migrate/tf-migrate/index.mdx +++ b/website/docs/cloud-docs/migrate/tf-migrate/index.mdx @@ -126,7 +126,7 @@ The `tf-migrate` tool will only prompt you to create a VCS-driven workspace if y - Your local configuration is a Git repository. - Your local Git repository has either GitHub or GitLab configured as a remote. -- Your HCP Terraform organization has at least one VCS OAuth connection configured for GitHub or GitLab `tf-migrate`. +- Your HCP Terraform organization has at least one VCS OAuth connection configured for GitHub or GitLab. If your HCP Terraform organization has more than one VCS connection configured, `tf-migrate` will ask you to choose which VCS connection to use.