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

You are viewing documentation for pre-release version v1.14.x (beta). View latest version.

Stack configuration files

Stacks use two types of configuration files to separate defining the components of your infrastructure from deployment details. Use a component configuration to define your infrastructure once, and a deployment configuration to deploy that infrastructure multiple times with different configurations.

File types

A Stack configuration is made up of of two different file types:

  • Component files, ending in .tfcomponent.hcl, declare the infrastructure components that this Stack creates and the input values of those components.
  • Deployment files, ending in .tfdeploy.hcl, declare how many times to deploy a stack and the input values for each deployment.

Component configuration files

Component files, ending in .tfcomponent.hcl, define the infrastructure components that make up your Stack. Component configuration files focus on what infrastructure you want to create, without specifying where or how many times to deploy it.

The component configuration replaces Terraform's traditional root module structure and declares which modules to include, how to configure providers, and what variables your Stack accepts. Each Stack requires at least one component block, and you must add a component block for every module you want to include in your Stack. Learn more about writing a component configuration.

You can define the following blocks in component configuration files:

  • The component block sources individual modules that make up your Stack. Each component receives input variables and accepts providers that you declare at the Stack level.
  • The required_providers block declares which providers your component configuration requires so that Terraform can install and use them.
  • The provider block configures providers and passes that configuration to components.
  • The removed block defines components you want to remove from your Stack while ensuring proper cleanup of resources.
  • The variable block defines input variables that your deployments can set with different values.
  • The output block defines values to expose in the HCP Terraform UI and to make available to deployments.
  • The locals block defines local values that you can reference within your component configuration.

You can separate your component configuration into several files for easier navigability. For example, the following file structure separates a Stack's components from the other other blocks that help configure those components:

Deployment configuration files

Deployment configuration files (.tfdeploy.hcl) define how HCP Terraform deploys your Stack's infrastructure. Deployment configuration files focus on where and how to deploy your infrastructure, using the components you defined in your component configuration.

Your Stack must have at least one deployment block. The deployment configuration file specifies how many deployments to create, what values to pass to each deployment, and how to orchestrate the deployment run process.

You can define the following blocks in deployment configuration files:

  • The deployment block defines how many times you want to deploy your Stack's infrastructure and with what input values.
  • The deployment_group block groups deployments together to configure shared settings and auto-approval rules.
  • The deployment_auto_approve block defines rules that automatically approve deployment plans based on specific conditions.
  • The identity_token block defines JSON Web Tokens (JWT) that Terraform generates for OIDC authentication with cloud providers.
  • The store block provides access to external secret stores and variable sets from your deployment configuration.
  • The publish_output block exports values from your Stack that other Stacks in the same project can consume.
  • The upstream_input block consumes outputs from another Stack in the same project and uses them as inputs in your current Stack.
  • The locals block defines local values that you can reference within your deployment configuration.

File organization

HCP Terraform processes all the configuration files in your Stack's root directory, regardless of their names. You can organize your configuration across multiple files based on your preferences, similar to traditional Terraform configurations.

Both component configuration and deployment configurations must reside at the root level of your Stack repository. HCP Terraform automatically discovers and processes all .tfcomponent.hcl and .tfdeploy.hcl files in dependency order.

Next steps

Edit this page on GitHub