Compare Stacks and workspaces

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.

Learn if a workspace or a Stack works best for your use case by comparing what each is best at and the features they support.

When to use workspaces

A workspace contains one Terraform root module, one set of inputs, and one state file. We recommend using workspaces if your use case meets any of the following conditions:

• You can manage your infrastructure using a single Terraform configuration.
• You require a strict separation between environments.
• You can plan and apply your infrastructure with one operation.
• You are setting up a mandatory CI/CD-driven pipeline to control promotion across environments or contexts.
• Your team uses a branch-per-environment workflow.

Workspaces provide a hard separation between environments because each workspace maintains its own isolated state file. Workspaces are suitable for strict separation requirements, such as compliance boundaries, production safeguards, or minimal blast radius scenarios.

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.

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 to learn more.

When to use Stacks

Stacks use a component-based architecture to repeatedly deploy infrastructure, simplifying managing your infrastructure lifecycle at scale. You define the modules that make up your Stack as components in a component configuration, then define how to repeatedly deploy that infrastructure in a deployment configuration.

We recommend using Stacks if your use case meets any of the following conditions:

• Your infrastructure is too large to manage as a single Terraform configuration.
• Your infrastructure cannot be planned in a single operation.
• Your infrastructure shares a common lifecycle.
• Your infrastructure does not share a lifecycle, but does have interconnected services that pass information back and forth.
• 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.

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.

If you have multiple Stacks that do not share a provisioning lifecycle, you can link those Stacks together to export data from one Stack for another to consume. Like workspace run triggers, if the output value of a Stack changes after a run, HCP Terraform automatically triggers runs for any Stacks that depend on those outputs. To learn more, refer to Pass data from one Stack to another.

You can also define rules to automatically approve Stack deployment runs using deployment group orchestration rules. To learn more about the features that Stack do and do not support, refer to Feature support.

Feature support

The following table shows which featured capabilities are available in workspaces and Stacks: