HashiConf 2025 Don't miss the live stream of HashiConf Day 2 happening now View live stream
Terraform
Terraform Home

Stacks overview

As your infrastructure grows, managing Terraform configurations becomes increasingly complex. Stacks are a powerful configuration layer in HCP Terraform that simplifies managing your infrastructure modules and then repeatedly deploying that infrastructure.

Hands-on: Try out the Deploy a Stack with HCP Terraform tutorial to get started with Stacks quickly.

Stacks replace Terraform's traditional root module structure with a new component-based architecture built on top of your Terraform modules. Stacks let you to provision and coordinate your infrastructure lifecycle at scale, offering an organized and reusable approach that expands upon infrastructure as code (IaC).

Background

Stacks are an alternative way to organize your infrastructure and fundamentally differ from HCP Terraform workspaces. Stacks can exist alongside workspaces in the same project, learn more about the differences and use cases of Stacks and workspaces.

Terraform Stacks enable you to split your Terraform configuration into components and then deploy and manage those components across multiple environments. You can manage the lifecycle of each deployment separately, roll out configuration changes across your deployments, and manage your Stack as a unit in HCP Terraform. When writing a Stack, you codify the entire behavior of your infrastructure lifecycle within version-controlled configuration files.

Each deployment in a Stack represents a group of components that work together, such as a development and production environment. The configuration for each Stack is identical across deployments, and you can customize each deployment with input variables. You can then use HCP Terraform to roll out changes to each of your deployments and keep track of the changes across your environments.

If you participated in the Stacks beta, you need to update your configurations to be compatible with the GA release. For details, refer to Update for general availability.

Workflow

Begin creating Stack by making a component configuration file, ending in tfcomponent.hcl, and filling it with component blocks. Each component block includes a Terraform module as its source, and you can configure each component using the inputs argument. All of your Stack components share a lifecycle, which you repeatedly deploy together using HCP Terraform.

Diagram of the architecture of a Stack. A Stack of two components (Kubernetes and Namespace) are rolled out to three deploymentes (US, Europe, and Asia)

After configuring your Stack’s components, you create a separate deployment configuration file to define how you want to repeat its infrastructure. Each deployment in a Stack represents a group of infrastructure that works together. You can define deployment blocks for your development environments, cloud provider accounts, regions, or whatever your infrastructure calls for.

When ready to deploy your Stack’s infrastructure, you can create a Stack in HCP Terraform to deploy. You can further manage your deployment runs by defining deployment group orchestration rules to automatically approve deployment runs that meet certain conditions.

Primary workflow

The overall process for managing your infrastructure using Stacks consists of the following steps.

Design a Stack

Consider your current infrastructure lifecycle and how the pieces interact with each other. Then, determine how to break down your infrastructure into components and think about how you want to deploy the infrastructure your Stack describes. Refer to Design a Stack to learn more.

Write a component configuration

Configure and define your Stack in a <NAME>.tfcomponent.hcl file. To define a Stack, add and configure component blocks, each representing an individual Terraform module. Refer to Define configuration to learn more.

Stacks declare providers in a different workflow than in traditional Terraform configurations, refer to Declare providers to learn more. Stacks also have their own way of authenticating with providers, refer to Authenticate a Stack for details.

Define deployments

With your component configuration file complete, the next step is to define how you want to deploy your Stack. Create a <NAME>.tfdeploy.hcl file defining how HCP Terraform should deploy your Stack’s infrastructure.

In Stacks, deployments let you replicate infrastructure across multiple environments, regions, accounts, or however your infrastructure requires. Each deployment has an isolated state file, ensuring that changes in one deployment do not affect others.

Refer to Define deployment configuration to learn more.

Deployment groups

You can manually assign deployments to deployment groups, or HCP Terraform automatically creates a new deployment group for any deployments you define. Deployment groups let you enforce rules on the deployments within the group. To learn more, refer to Set conditions for deployment runs.

Deploy

After fully configuring your Stack, use HCP Terraform to deploy your Stack’s infrastructure. Refer to Create a Stack to learn more.

Guidance

Stacks are useful when managing complex, multi-environment infrastructures where consistency and reusability are crucial. Refer to Stack use cases for inspiration on situations where Stacks are particularly well suited.

Constraints and limitations

Stacks have the following constraints:

Edit this page on GitHub