Merge pull request #431 from hashicorp/RK/migrate-for-the-future

Author: rkoron007

content/terraform-docs-common/docs/cloud-docs/migrate/index.mdx

@@ -6,13 +6,13 @@ description: >-
 
 # Migrate Terraform state to HCP Terraform or Terraform Enterprise
 
-This topic describes how to migrate existing Terraform state files to HCP Terraform or Terraform Enterprise without first de-provisioning them. Refer to [State](/terraform/language/state) in the Terraform configuration language reference for additional information about Terraform state. 
+This topic describes how to migrate existing Terraform state files to HCP Terraform or Terraform Enterprise without first de-provisioning them. Refer to [State](/terraform/language/state) in the Terraform configuration language reference for additional information about Terraform state.
 
 ## Overview
 
 Perform the following actions to migrate existing resources to one or more workspaces in HCP Terraform or Terraform Enterprise:
 
-1. Stop all Terraform operations associated with the state files. 
+1. Stop all Terraform operations associated with the state files.
 1. Migrate Terraform state files to HCP Terraform or Terraform Enterprise.
 
 You have three options to migrate your state:
@@ -39,9 +39,9 @@ Stop all Terraform operations associated with the state files. This may require
 
 
 1. Add the `cloud` block to your Terraform configuration and specify the following fields:
-   1. `hostname` field: Specify either `app.terraform.io` for HCP Terraform or the hostname of your Terraform Enterprise deployment. 
-   1. `organization` field: Specify your HCP Terraform or Terraform Enterprise organization. 
-   1. `workspaces` block: Add a `tags` or `name` field and specify one or more destination workspaces as a list of strings. 
+   1. `hostname` field: Specify either `app.terraform.io` for HCP Terraform or the hostname of your Terraform Enterprise deployment.
+   1. `organization` field: Specify your HCP Terraform or Terraform Enterprise organization.
+   1. `workspaces` block: Add a `tags` or `name` field and specify one or more destination workspaces as a list of strings.
 
    Refer to [The `cloud` Block](/terraform/cli/cloud/settings#the-cloud-block) in the Terraform CLI documentation for additional information. The following example migrates the state associated with the configuration to the `networking` workspace on HCP Terraform:
 
@@ -69,17 +69,17 @@ Stop all Terraform operations associated with the state files. This may require
     $ md5sum terraform.tfstate
     690a3f8ae079c629494a52c68757d585  terraform.tfstate
     ```
-   
+
 1. If the workspace does not yet exist in your organization, send a `POST` request to the `/organizations/:organization_name/workspaces` endpoint to create it. Otherwise, proceed to the next step. Refer to the following topics for details:
-   - [Create a workspace](/terraform/cloud-docs/api-docs/workspaces#create-a-workspace) in the HCP Terraform API reference documentation. 
+   - [Create a workspace](/terraform/cloud-docs/api-docs/workspaces#create-a-workspace) in the HCP Terraform API reference documentation.
    - [Create a workspace](/terraform/enterprise/api-docs/workspaces#create-a-workspace) in the Terraform Enterprise API reference documentation.
 1. Send a `POST` request to the `/workspaces/:workspace_id/actions/lock` endpoint to lock the workspace. Refer to the following topics for details:
-   - [Lock a workspace](/terraform/cloud-docs/api-docs/workspaces#lock-a-workspace) in the HCP Terraform API reference documentation. 
-   - [Lock a workspace](/terraform/enterprise/api-docs/workspaces#lock-a-workspace) in the Terraform Enterprise API reference documentation. 
+   - [Lock a workspace](/terraform/cloud-docs/api-docs/workspaces#lock-a-workspace) in the HCP Terraform API reference documentation.
+   - [Lock a workspace](/terraform/enterprise/api-docs/workspaces#lock-a-workspace) in the Terraform Enterprise API reference documentation.
 1. To upload your state files to the workspace, send a `POST` request to the `/workspaces/:workspace_id/state-versions` endpoint. Specify the MD5 string in the `data.attributes.md5` field and encoded state file in the `data.attributes.state` field of the request body.  Refer to the following topics for details:
-   - [Create a state version](/terraform/cloud-docs/api-docs/state-versions#create-a-state-version) in the HCP Terraform API reference documentation. 
+   - [Create a state version](/terraform/cloud-docs/api-docs/state-versions#create-a-state-version) in the HCP Terraform API reference documentation.
    - [Create a state version](/terraform/enterprise/api-docs/state-versions#create-a-state-version) in the Terraform Enterprise API reference documentation.
-1. Send a `POST` request to the `/workspaces/:workspace_id/actions/unlock` endpoint to unlock the workspace. 
+1. Send a `POST` request to the `/workspaces/:workspace_id/actions/unlock` endpoint to unlock the workspace.
 
 Refer to the following external article for an example of how to create a script in Python to automate multiple state files:
 [Migrating A Lot of State with Python and the HCP Terraform (previously Terraform Cloud) API](https://medium.com/hashicorp-engineering/migrating-a-lot-of-state-with-python-and-the-terraform-cloud-api-997ec798cd11). The example uses the [Workspaces API](/terraform/cloud-docs/api-docs/workspaces#create-a-workspace) to create the necessary workspaces in HCP Terraform and the [State Versions API](/terraform/cloud-docs/api-docs/state-versions) to migrate the state files to those workspaces.
@@ -90,3 +90,16 @@ Refer to the following external article for an example of how to create a script
 > **Hands-on:** Complete the [Migrate to HCP Terraform in bulk](/terraform/tutorials/cloud/bulk-migrate-hcp) tutorial to get started with tf-migrate.
 
 You can use the `tf-migrate` CLI tool to automatically migrate state to HCP Terraform and Terraform Enterprise. The tool does not ship with HCP Terraform. You must download and install the binary for the CLI tool separately. Refer to the [`tf-migrate` documentation](/terraform/migrate) for more information.
+
+<!-- BEGIN: TFC:only name:stacks-tfe -->
+
+## Migrate a workspace to a Stack
+
+In HCP Terraform, there are two ways of organizing your infrastructure:
+
+- Workspaces are ideal for managing a self-contained infrastructure of one Terraform root module.
+- Stacks are ideal for managing multiple infrastructure modules and repeating that infrastructure at scale.
+
+If you have an existing workspace that you want to convert to a Stack, you can use the Terraform migrate CLI to migrate your workspace state and configuration to a Stack in HCP Terraform. Refer to the [Terraform migrate CLI](/terraform/migrate/stacks) to learn more.
+
+<!-- END: TFC:only name:stacks-tfe -->

content/terraform-docs-common/docs/cloud-docs/stack-workspace.mdx

@@ -28,7 +28,7 @@ Workspaces provide a hard separation between environments because each workspace
 
 If your team uses a branching strategy where each environment maps to a separate Git branch, workspaces can align with your workflow. You can promote changes across environments through pull requests between branches. Workspaces also work well when CI/CD pipelines control promotion across environments, especially when a promotion must be gated by approvals or automated test outcomes.
 
-Previously, those looking to deploy repeatable infrastructure using HCP Terraform would create separate workspaces and then use run triggers or other automation tools to coordinate changes between them. However, workspaces are not truly coupled to each other, hampering your ability to flexibly manage infrastructure as it scales. If you have a tightly orchestrated infrastructure that changes across different environments, we recommend defining a Stack.
+Previously, those looking to deploy repeatable infrastructure using HCP Terraform would create separate workspaces and then use run triggers or other automation tools to coordinate changes between them. However, workspaces are not truly coupled to each other, hampering your ability to flexibly manage infrastructure as it scales. If you have a tightly orchestrated infrastructure that changes across different environments, we recommend defining a Stack. If you want to migrate an existing workspace to a Stack, refer to the [Terraform migrate CLI](/terraform/migrate/stacks).
 
 Workspaces do support validating your code with policies, drift detection, and a range of other features that Stacks do not support. Refer to [Feature support](#feature-support) to learn more.
 
@@ -45,7 +45,7 @@ We recommend using Stacks if your use case meets any of the following conditions
 - You repeat infrastructure across different environments, regions, or accounts that require consistent and synchronized deployments.
 - You have a tightly orchestrated infrastructure that changes across different environments.
 
-Stacks codify the entire behavior of your infrastructure lifecycle within version-controlled configuration files. To learn more about Stacks and review examples, refer to [Stack use cases](/terraform/language/stacks/use-cases).
+Stacks codify the entire behavior of your infrastructure lifecycle within version-controlled configuration files. To learn more about Stacks and review examples, refer to [Stack use cases](/terraform/language/stacks/use-cases). If you want to migrate an existing workspace to a Stack, refer to the [Terraform migrate CLI](/terraform/migrate/stacks).
 
 Stacks were designed to simplify and scale Terraform workflows that become complex or repetitive using workspaces. When you use a Stack, HCP Terraform automatically recognizes the dependency between components, automatically deferring the component's plan and apply steps until it can complete them successfully. Learn more about how Stacks plan [deferred changes](/terraform/cloud-docs/stacks/deploy/runs#deferred-changes).
 

content/terraform-docs-common/docs/cloud-docs/stacks/create.mdx

@@ -31,6 +31,8 @@ You can create a Stack using any of the following methods:
 - The HCP Terraform UI
 - The Terraform CLI
 
+If you want to migrate an existing workspace to a Stack, refer to the [Terraform migrate CLI](/terraform/migrate/stacks).
+
 If you are creating a Stack in an organization for the first time, you must enable Stacks for your organization. Navigate to your organization’s **Settings** page, and in the **General** settings, check the box next to **Stacks**.
 
 ### HCP Terraform workflow

content/terraform/v1.13.x/docs/language/block/stack/tfdeploy/deployment.mdx

@@ -156,7 +156,7 @@ We recommend using the `destroy` argument to remove deployments to ensure your c
 
 ### `import`
 
-The `import` argument is a placeholder for future functionality.
+The `tf-migrate` CLI can migrate the state of an existing HCP Terraform workspace to a Stack deployment. The `tf-migrate` CLI automatically sets the `import` argument to `true` when importing the state of an existing workspace to a specific deployment.
 
 ```hcl
 deployment "<LABEL>" {
@@ -168,6 +168,10 @@ deployment "<LABEL>" {
 }
 ```
 
+Terraform migrate sets the `import` argument to let HCP Terraform know that the rest of the deployments in a Stack can continue plan as normal while the deployment with `import` is migrating state.
+
+To learn more about migrating a workspace to a Stack deployment, refer to [Terraform migrate](/terraform/migrate/stacks).
+
 #### Summary
 
 - Data type: Boolean

content/terraform/v1.14.x (beta)/docs/language/block/stack/tfdeploy/deployment.mdx

@@ -155,7 +155,7 @@ We recommend using the `destroy` argument to remove deployments to ensure your c
 
 ### `import`
 
-The `import` argument is a placeholder for future functionality.
+The `tf-migrate` CLI can migrate the state of an existing HCP Terraform workspace to a Stack deployment. The `tf-migrate` CLI automatically sets the `import` argument to `true` when importing the state of an existing workspace to a specific deployment.
 
 ```hcl
 deployment "<LABEL>" {
@@ -167,6 +167,10 @@ deployment "<LABEL>" {
 }
 ```
 
+Terraform migrate sets the `import` argument to let HCP Terraform know that the rest of the deployments in a Stack can continue plan as normal while the deployment with `import` is migrating state.
+
+To learn more about migrating a workspace to a Stack deployment, refer to [Terraform migrate](/terraform/migrate/stacks).
+
 #### Summary
 
 - Data type: Boolean