Skip to content

Commit 374dff1

Browse files
BrianMMcClainBrianMMcClain
authored
Merge pull request #379 from hashicorp/tf-migrate-1-3
tf-migrate 2.0 [IPE-1240]
1 parent bfbb879 commit 374dff1

File tree

14 files changed

+1152
-0
lines changed

14 files changed

+1152
-0
lines changed

‎content/terraform-migrate/v2.0.x/data/migrate-nav-data.json‎

Lines changed: 98 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,98 @@
1+
[
2+
{
3+
"heading": "Migrate to HCP Terraform"
4+
},
5+
{
6+
"title": "Overview",
7+
"path": ""
8+
},
9+
{
10+
"title": "Install",
11+
"path": "install"
12+
},
13+
{
14+
"title": "Authenticate",
15+
"path": "authenticate"
16+
},
17+
{
18+
"title": "Migrate to Stacks",
19+
"path": "stacks",
20+
"badge": {
21+
"text": "BETA",
22+
"type": "outlined",
23+
"color": "neutral"
24+
}
25+
},
26+
{
27+
"title": "Reference",
28+
"routes": [
29+
{
30+
"title": "CLI",
31+
"routes": [
32+
{
33+
"title": "tf-migrate prepare",
34+
"path": "reference/cli/prepare"
35+
},
36+
{
37+
"title": "tf-migrate execute",
38+
"path": "reference/cli/execute"
39+
},
40+
{
41+
"title": "modules",
42+
"badge": {
43+
"text": "BETA",
44+
"type": "outlined",
45+
"color": "neutral"
46+
},
47+
"routes": [
48+
{
49+
"title": "tf-migrate modules create",
50+
"path": "reference/cli/modules/create"
51+
}
52+
]
53+
},
54+
{
55+
"title": "stacks",
56+
"badge": {
57+
"text": "BETA",
58+
"type": "outlined",
59+
"color": "neutral"
60+
},
61+
"routes": [
62+
{
63+
"title": "tf-migrate stacks prepare",
64+
"path": "reference/cli/stacks/prepare"
65+
},
66+
{
67+
"title": "tf-migrate stacks execute",
68+
"path": "reference/cli/stacks/execute"
69+
},
70+
{
71+
"title": "tf-migrate stacks cleanup",
72+
"path": "reference/cli/stacks/cleanup"
73+
}
74+
]
75+
}
76+
]
77+
},
78+
{
79+
"title": "Configuration file reference",
80+
"path": "reference/configuration"
81+
}
82+
]
83+
},
84+
{
85+
"title": "Release notes",
86+
"routes": [
87+
{
88+
"title": "v2.0",
89+
"badge": {
90+
"text": "BETA",
91+
"type": "outlined",
92+
"color": "neutral"
93+
},
94+
"path": "releases/v2_0"
95+
}
96+
]
97+
}
98+
]

‎content/terraform-migrate/v2.0.x/docs/migrate/authenticate.mdx‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
---
2+
page_title: Authenticate `tf-migrate`
3+
description: >-
4+
Learn how to authenticate tf-migrate to migrate existing state to HCP Terraform or Terraform Enterprise.
5+
---
6+
7+
# Authenticate `tf-migrate`
8+
9+
To use `tf-migrate`, you must authenticate with HCP Terraform or the Terraform Enterprise instance that you are migrating your state to.
10+
11+
## Connect to HCP Terraform or Enterprise Terraform
12+
13+
The `tf-migrate` tool uses your locally configured Terraform CLI API token. If you have not authenticated your local Terraform installation with HCP Terraform, use the `terraform login` command to create an authentication token.
14+
15+
```
16+
$ terraform login
17+
18+
Terraform will request an API token for app.terraform.io using your browser.
19+
20+
If login is successful, Terraform will store the token in plain text in
21+
the following file for use by subsequent commands:
22+
/Users/redacted/.terraform.d/credentials.tfrc.json
23+
24+
Do you want to proceed?
25+
Only 'yes' will be accepted to confirm.
26+
27+
Enter a value: yes
28+
```
29+
30+
Terraform opens a browser to the HCP Terraform sign in screen, where you can then enter a token name in the web UI, or leave the default name. Click **Create API token** to generate the authentication token.
31+
32+
HCP Terraform only displays your token once. Copy this token, then when the Terraform CLI prompts you, paste the user token exactly once into your terminal. Press **Enter** to complete the authentication process.
33+
34+
## Authenticate your VCS provider
35+
36+
`tf-migrate` can optionally create a pull request that updates the state storage location specified in your Terraform configuration. To do this, `tf-migrate` uses your VCS provider's API, and requires an API token with permissions to modify your Git repository.
37+
38+
To configure your API token, set the `TF_GIT_PAT_TOKEN` environment variable
39+
40+
```
41+
$ export TF_GIT_PAT_TOKEN=<TOKEN>
42+
```
43+
44+
### GitHub connection requirements
45+
46+
If your Terraform files are stored in GitHub, you must configure an API token that meets the following requirements:
47+
48+
- The token must be a classic token. Refer to the [GitHub documentation](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) for additional information.
49+
- The token must have the `repo` OAuth scope.
50+
51+
### GitLab connection requirements
52+
53+
If your Terraform files are stored in GitLab Cloud, you must configure an API token that meets the following requirements:
54+
55+
- The token must be a personal access token. Refer to the [GitLab documentation](https://docs.gitlab.com/user/profile/personal_access_tokens) for additional information.
56+
- The token must have `read_repository` and `write_repository` scopes.
57+
58+
### Bitbucket connection requirements
59+
60+
If your Terraform files are stored in Bitbucket Cloud, you must configure an API token that meets the following requirements:
61+
62+
- The token must be a repository access token. Refer to the [Bitbucket documentation](https://support.atlassian.com/bitbucket-cloud/docs/create-a-repository-access-token/) for additional information.
63+
- The token must have `repository:write` and `pullrequest:write` scopes.

‎content/terraform-migrate/v2.0.x/docs/migrate/index.mdx‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
---
2+
page_title: Migrate to HCP Terraform
3+
description: >-
4+
The tf-migrate CLI migrates existing Terraform state to HCP Terraform or Terraform Enterprise.
5+
---
6+
7+
# Migrate to HCP Terraform
8+
9+
The `tf-migrate` CLI automatically migrates your Terraform Community Edition state and variable values to HCP Terraform or Terraform Enterprise. It also updates your local configuration with the new state storage location and optionally creates a pull request to update your code repository.
10+
11+
**Hands-on**: Complete the [Migrate to HCP Terraform in bulk](/terraform/tutorials/cloud/bulk-migrate-hcp) tutorial to get started with `tf-migrate`.
12+
13+
## Overview
14+
15+
Complete the following steps to install and configure `tf-migrate`:
16+
17+
1. [Download and install `tf-migrate`](/terraform/migrate/install).
18+
1. Configure `tf-migrate` to [authenticate](/terraform/migrate/authenticate#connect-to-hcp-terraform-or-enterprise-terraform) to HCP Terraform or Terraform Enterprise.
19+
1. Optionally [authenticate your VCS provider](/terraform/migrate/authenticate#authenticate-your-vcs-provider) with your version control provider API key to create a pull request with your configuration changes.
20+
1. Optionally enable [logging](#enable-logging) so that you can troubleshoot potential issues that may occur during the migration process.
21+
22+
## Supported backends
23+
24+
The `tf-migrate` tool supports migrating state from the following backends to HCP Terraform or Terraform Enterprise:
25+
26+
- [local](/terraform/language/backend/local)
27+
- [azurerm](/terraform/language/backend/azurerm)
28+
- [consul](/terraform/language/backend/consul)
29+
- [cos](/terraform/language/backend/cos)
30+
- [gcs](/terraform/language/backend/gcs)
31+
- [http](/terraform/language/backend/http)
32+
- [Kubernetes](/terraform/language/backend/kubernetes)
33+
- [oss](/terraform/language/backend/oss)
34+
- [pg](/terraform/language/backend/pg)
35+
- [s3](/terraform/language/backend/s3)
36+
37+
The `tf-migrate` CLI does not support migrating state from an existing `cloud` integration or `remote` backend.
38+
39+
## Supported workspace workflows
40+
41+
The `tf-migrate` tool can create CLI- or VCS-driven HCP Terraform workspaces. It will only prompt you to create a VCS-driven workspace if you meet the following requirements:
42+
43+
- Your local configuration is a Git repository.
44+
- Your local Git repository has GitHub, GitLab, or Bitbucket configured as a remote.
45+
- Your HCP Terraform organization has at least one VCS OAuth connection configured for GitHub, GitLab, or Bitbucket.
46+
47+
If your HCP Terraform organization has more than one VCS connection configured, `tf-migrate` will ask you to choose which VCS connection to use.
48+
49+
If your local configuration does not meet all of the above requirements, `tf-migrate` automatically creates a CLI-driven workspace instead.
50+
51+
## Migrate from workspaces to Stacks
52+
53+
@include "stacks.mdx"
54+
55+
The `tf-migrate` CLI can migrate Terraform configuration and state from an HCP Terraform workspace to a Stack. Refer to [Migrate a workspace to a Stack](/terraform/migrate/stacks) for more information.
56+
57+
## Enable logging
58+
59+
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:
60+
61+
| Platform | Location |
62+
| -------- | -------- |
63+
| macOS and Linux | `/Users/<username>/.tf-migrate/logs/<commandName>/<date>.log` |
64+
| Windows | `C:\Users\<username>\.tf-migrate\logs\<commandName>\<date>.log` |
65+
66+
You can set the `TF_MIGRATE_LOG_LEVEL` environment variable to one of the following values to change the verbosity of the logs in order of decreasing verbosity:
67+
68+
- `TRACE`
69+
- `DEBUG`
70+
- `INFO`
71+
- `WARN`
72+
- `ERROR`
73+
74+
## Additional configuration
75+
76+
You can create an optional configuration file to modify the `tf-migrate` CLI behavior and specify the path to the configuration file when you run `tf-migrate prepare`. Any command-line flags you provide with these commands override the configuration file. Refer to the [configuration reference](/terraform/migrate/reference/configuration) for additional information.

‎content/terraform-migrate/v2.0.x/docs/migrate/install.mdx‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
---
2+
page_title: Install tf-migrate
3+
description: >-
4+
Learn how to install the Terraform migrate tf-migrate CLI tool.
5+
---
6+
7+
# Install `tf-migrate`
8+
9+
HashiCorp distributes Terraform as an executable CLI that you can install on supported operating systems, including Microsoft Windows, macOS, and several Linux distributions.
10+
11+
<Tabs>
12+
13+
<Tab heading="Manual installation">
14+
15+
To install `tf-migrate`, find the [appropriate binary](https://releases.hashicorp.com/tf-migrate/) for your operating system and download it as a zip archive.
16+
17+
After you download `tf-migrate`, unzip the archive.
18+
19+
Finally, make sure that the `tf-migrate` binary is available in a directory that is in your system's `PATH`.
20+
21+
Every build of `tf-migrate` includes a `SHA256SUMS` and a `SHA256SUMS.sig` file to validate your downloaded binary. Refer to the [verify HashiCorp binary downloads tutorial](https://developer.hashicorp.com/well-architected-framework/operational-excellence/verify-hashicorp-binary) for more information.
22+
23+
</Tab>
24+
25+
<Tab heading="Homebrew on macOS">
26+
27+
[Homebrew](https://brew.sh/) is a free and open-source package management system for macOS. You can install the official [`tf-migrate`](https://github.com/hashicorp/homebrew-tap) formula from the terminal.
28+
29+
First, install the HashiCorp tap, a repository of all our Homebrew packages.
30+
31+
```
32+
$ brew tap hashicorp/tap
33+
```
34+
35+
Now, install `tf-migrate` with the `hashicorp/tap/tf-migrate` formula.
36+
37+
```
38+
$ brew install hashicorp/tap/tf-migrate
39+
```
40+
41+
</Tab>
42+
43+
</Tabs>
44+
45+
## Verify installation
46+
47+
Verify that the installation worked by opening a new terminal and using the `-help` flag of `tf-migrate`:
48+
49+
```shell-session
50+
$ tf-migrate -help
51+
Welcome to the HCP Terraform Migrator for Community Edition.
52+
53+
Usage: tf-migrate [global options] <subcommand> [args]
54+
55+
The available commands for execution are listed below.
56+
The primary workflow commands are given first,
57+
followed by global options.
58+
59+
Commands:
60+
##...
61+
```

‎content/terraform-migrate/v2.0.x/docs/migrate/reference/cli/execute.mdx‎

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
---
2+
page_title: tf-migrate execute reference
3+
description: >-
4+
The `tf-migrate execute` command runs a prepared migration plan to move local state to HCP Terraform or Terraform Enterprise.
5+
---
6+
7+
# `tf-migrate execute` reference
8+
9+
The `tf-migrate execute` command directs Terraform to run the `init`, `plan`, and `apply` commands on the configuration generated with the `tf-migrate prepare` command and migrate your local state to HCP Terraform or Terraform Enterprise.
10+
11+
## Usage
12+
13+
```
14+
$ tf-migrate execute
15+
```
16+
17+
## Description
18+
19+
The `tf-migrate execute` command creates the project and workspace in HCP Terraform or Terraform Enterprise, migrates the existing state, and updates your configuration to replace the `backend` block with the `cloud` block. If you responded to the prompt in the prepare workflow to create a pull request, `tf-migrate` creates the pull request after it completes the migration.
20+
21+
When Terraform migrate completes the migration, it displays the number of workspaces migrated, a link to each HCP Terraform workspace, and a link to the GitHub pull request if you configured it to create one.
22+
23+
## Example
24+
25+
The `tf-migrate execute` command automatically performs the migration and code updates.
26+
27+
```bash
28+
$ tf-migrate execute
29+
✓ Init command ran successfully
30+
✓ Plan command ran successfully and changes are detected
31+
✓ Apply command ran successfully
32+
Apply complete! Resources: 7 added, 0 changed, 0 destroyed.
33+
34+
35+
Migration Summary
36+
┌───────────────────────────────┬───────┐
37+
│ Metric │ Count │
38+
├───────────────────────────────┼───────┤
39+
│ Number of Projects Migrated │ 2 │
40+
│ Number of Directories Skipped │ 0 │
41+
│ Number of New Workspaces │ 2 │
42+
│ Number of Variables Migrated │ 8 │
43+
└───────────────────────────────┴───────┘
44+
┌───────────────────────────────────────────────────────────────────────────────────────────────────┐
45+
│ Workspace URLs │
46+
├───────────────────────────────────────────────────────────────────────────────────────────────────┤
47+
│ https://app.terraform.io/<ORG>/workspaces/web_default │
48+
│ https://app.terraform.io/<ORG>/workspaces/api_default │
49+
└───────────────────────────────────────────────────────────────────────────────────────────────────┘
50+
┌────────────────────────────────────────────────────────────────────────┐
51+
│ Pull Request Link │
52+
├────────────────────────────────────────────────────────────────────────┤
53+
│ https://github.com/<ORG>/learn-terraform-migrate/pull/1 │
54+
└────────────────────────────────────────────────────────────────────────┘
55+
```
56+
57+
## Available options
58+
59+
You can include the following flags when you run the `tf-migrate execute` command:
60+
61+
| Option | Description | Default | Required |
62+
| ------ | ----------- | ------- | -------- |
63+
| `-dry-run` | If set, Terraform migrate only shows the output from the `terraform plan` step, and does not perform the migration. | None | No |
64+
65+
## Clean up temporary migration branches
66+
67+
If you chose to create a new branch when you ran the `tf-migrate prepare` command and you created a VCS-driven workspace, tf-migrate automatically configures you HCP Terraform workspaces to use the new branch rather than your default branch. To update your workspace use your default branch, complete the following steps:
68+
69+
1. Merge the `hcp-migrate-<BRANCH>` branch into your default branch.
70+
1. Open your workspace **Settings** page.
71+
1. Click **Version Control**.
72+
1. Update the **VCS branch** field with the name of your default branch.
73+
1. Click **Update VCS settings**.
74+
75+
After you complete these steps, we recommend that you start a new run in your workspace to verify these changes.
76+
77+
1. Navigate back to your workspace overview page.
78+
1. Click **New run**.
79+
1. Under **Run Type**, choose **Plan only**.
80+
1. Click **Start**.
81+
1. Verify that Terraform does not plan to make any changes to your infrastructure.
82+
83+
After you verify these changes, you can safely delete the `hcp-migrate-<BRANCH>` branch.

0 commit comments

Comments
 (0)