From 8d4bb3efb89caf94dd6dceed5efd0fef1a04f652 Mon Sep 17 00:00:00 2001 From: rkoron007 Date: Mon, 22 Sep 2025 11:02:40 -0700 Subject: [PATCH] Prepare for the beta whenever it does drop --- .../docs/cloud-docs/migrate/index.mdx | 13 +++++++++++++ .../docs/cloud-docs/stack-workspace.mdx | 4 ++-- .../docs/cloud-docs/stacks/create.mdx | 2 ++ .../language/block/stack/tfdeploy/deployment.mdx | 6 +++++- .../language/block/stack/tfdeploy/deployment.mdx | 6 +++++- 5 files changed, 27 insertions(+), 4 deletions(-) diff --git a/content/terraform-docs-common/docs/cloud-docs/migrate/index.mdx b/content/terraform-docs-common/docs/cloud-docs/migrate/index.mdx index e44550577b..51f20611c5 100644 --- a/content/terraform-docs-common/docs/cloud-docs/migrate/index.mdx +++ b/content/terraform-docs-common/docs/cloud-docs/migrate/index.mdx @@ -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. + + + +## 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. + + diff --git a/content/terraform-docs-common/docs/cloud-docs/stack-workspace.mdx b/content/terraform-docs-common/docs/cloud-docs/stack-workspace.mdx index 172a78e20e..c6527751aa 100644 --- a/content/terraform-docs-common/docs/cloud-docs/stack-workspace.mdx +++ b/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). diff --git a/content/terraform-docs-common/docs/cloud-docs/stacks/create.mdx b/content/terraform-docs-common/docs/cloud-docs/stacks/create.mdx index 30b732c3ad..fc83a98e41 100644 --- a/content/terraform-docs-common/docs/cloud-docs/stacks/create.mdx +++ b/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 diff --git a/content/terraform/v1.13.x/docs/language/block/stack/tfdeploy/deployment.mdx b/content/terraform/v1.13.x/docs/language/block/stack/tfdeploy/deployment.mdx index 714114a2ff..4a3566dfdc 100644 --- a/content/terraform/v1.13.x/docs/language/block/stack/tfdeploy/deployment.mdx +++ b/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 "