terraform-stacks

Terraform Stacks

Terraform Stacks simplify infrastructure provisioning and management at scale by providing a configuration layer above traditional Terraform modules. Stacks enable declarative orchestration of multiple components across environments, regions, and cloud accounts.

Core Concepts

Stack: A complete unit of infrastructure composed of components and deployments that can be managed together.

Component: An abstraction around a Terraform module that defines infrastructure pieces. Each component specifies a source module, inputs, and providers.

Deployment: An instance of all components in a stack with specific input values. Use deployments for different environments (dev/staging/prod), regions, or cloud accounts.

Stack Language: A separate HCL-based language (not regular Terraform HCL) with distinct blocks and file extensions.

File Structure

Terraform Stacks use specific file extensions:

• Component configuration: .tfcomponent.hcl
• Deployment configuration: .tfdeploy.hcl
• Provider lock file: .terraform.lock.hcl (generated by CLI)

All configuration files must be at the root level of the Stack repository. HCP Terraform processes all files in dependency order.

Recommended File Organization

my-stack/
├── .terraform-version               # The required Terraform version for this Stack
├── variables.tfcomponent.hcl        # Variable declarations
├── providers.tfcomponent.hcl        # Provider configurations
├── components.tfcomponent.hcl       # Component definitions
├── outputs.tfcomponent.hcl          # Stack outputs
├── deployments.tfdeploy.hcl         # Deployment definitions
├── .terraform.lock.hcl              # Provider lock file (generated)
└── modules/                         # Local modules (optional - only if using local modules)
    ├── s3/
    └── compute/

Note: The modules/ directory is only required when using local module sources. Components can reference modules from:

• Local file paths: ./modules/vpc
• Public registry: terraform-aws-modules/vpc/aws
• Private registry: app.terraform.io/<org-name>/vpc/aws
• Git: git::https://github.com/org/repo.git//path?ref=v1.0.0

HCP Terraform processes all .tfcomponent.hcl and .tfdeploy.hcl files in dependency order.

Required Terraform version (.terraform-version)

Use Terraform v1.13.x or later to access the Stacks CLI plugin and to run terraform stacks CLI commands. Begin by adding a .terraform-version file to your Stack's root directory to specify the Terraform version required for your Stack. For example, the following file specifies Terraform v1.14.5:

Component Configuration (.tfcomponent.hcl)

Variable Block

Declare input variables for the Stack configuration. Variables must define a type field and do not support the validation argument.

Important: Use ephemeral = true for credentials and tokens (identity tokens, API keys, passwords) to prevent them from persisting in state files. Use stable for longer-lived values like license keys that need to persist across runs.

Required Providers Block

Provider Block

Provider blocks differ from traditional Terraform:

1. Support for_each meta-argument
2. Define aliases in the block header (not as an argument)
3. Accept configuration through a config block

Single Provider Configuration:

Multiple Provider Configurations with for_each:

Authentication Best Practice: Use workload identity (OIDC) as the preferred authentication method for Stacks. This approach:

• Avoids long-lived static credentials
• Provides temporary, scoped credentials per deployment run
• Integrates with cloud provider IAM (AWS IAM Roles, Azure Managed Identities, GCP Service Accounts)
• Eliminates need for platform-managed environment variables

Configure workload identity using identity_token blocks and assume_role_with_web_identity in provider configuration. For detailed setup instructions for AWS, Azure, and GCP, see: https://developer.hashicorp.com/terraform/cloud-docs/dynamic-provider-credentials

Component Block

Each Stack requires at least one component block. Add a component for each module to include in the Stack. Components reference modules from local paths, registries, or Git.

See references/component-blocks.md for examples of dependencies, for_each, public registry modules, Git sources, and more.

Key Points:

• Reference outputs: component.<name>.<output> or component.<name>[key].<output> for for_each
• Dependencies inferred automatically from component references
• Aggregate with for expressions: [for x in component.s3 : x.bucket_name]
• For components with for_each, reference specific instances: component.<name>[each.value].<output>
• Provider references are normal values: provider.<type>.<alias> or provider.<type>.<alias>[each.value]

Output Block

Outputs require a type argument and do not support preconditions:

Locals Block

Locals blocks work the same in both .tfcomponent.hcl and .tfdeploy.hcl files:

Removed Block

Use to safely remove components from a Stack. HCP Terraform requires the component's providers to remove it.

Deployment Configuration (.tfdeploy.hcl)

Identity Token Block

Generate JWT tokens for OIDC authentication with cloud providers:

Reference tokens in deployments using identity_token.<name>.jwt

Store Block

Access HCP Terraform variable sets within Stack deployments:

Use to centralize credentials and share variables across Stacks. See references/deployment-blocks.md for details.

Deployment Block

Define deployment instances (minimum 1, maximum 20 per Stack):

To destroy a deployment: Set destroy = true, upload configuration, approve destroy run, then remove the deployment block. See references/deployment-blocks.md for details.

Deployment Group Block

Group deployments together for shared settings (HCP Terraform Premium tier feature). Free/standard tiers use default groups named {deployment-name}_default.

Multiple deployments can reference the same group. See references/deployment-blocks.md for details.

Deployment Auto-Approve Block

Define rules to automatically approve deployment plans (HCP Terraform Premium tier feature):

Available context variables: context.plan.applyable, context.plan.changes.add/change/remove/total, context.success

Note: orchestrate blocks are deprecated. Use deployment_group and deployment_auto_approve instead.

See references/deployment-blocks.md for all context variables and patterns.

Publish Output and Upstream Input Blocks

Link Stacks together by publishing outputs from one Stack and consuming them in another:

See references/linked-stacks.md for complete documentation and examples.

Terraform Stacks CLI

Note: Terraform Stacks is Generally Available (GA) as of Terraform CLI v1.13+. Stacks now count toward Resources Under Management (RUM) for HCP Terraform billing.

Initialize and Validate

Deployment Workflow

Important: No plan or apply commands. Upload configuration triggers deployment runs automatically.

Configuration Management

Other Commands

Monitoring Deployments with HCP Terraform API

For programmatic monitoring in automation, CI/CD, or non-interactive environments (like AI agents), use the HCP Terraform API instead of CLI watch commands. The API provides endpoints for:

• Configuration status and validation
• Deployment group summaries
• Deployment run status
• Deployment step details (plan/apply)
• Error diagnostics with file locations and code snippets
• Stack outputs via artifacts endpoint

Key points:

• CLI watch commands stream indefinitely and don't work in automation
• Use artifacts endpoint to retrieve Stack outputs: GET /api/v2/stack-deployment-steps/{step-id}/artifacts?name=apply-description
• Diagnostics endpoint requires stack_deployment_step_id query parameter
• Artifacts endpoint returns HTTP 307 redirect (use curl -L)

For complete API workflow, authentication, polling best practices, and example scripts, see references/api-monitoring.md.

Common Patterns

Component Dependencies: Dependencies are automatically inferred when one component references another's output (e.g., subnet_ids = component.vpc.private_subnet_ids).

Multi-Region Deployment: Use for_each on providers and components to deploy across multiple regions. Each region gets its own provider configuration and component instances.

Deferred Changes: Stacks support deferred changes to handle dependencies where values are only known after apply. This enables complex multi-component deployments where some resources depend on runtime values from other components (cluster endpoints, generated passwords, etc.).

For complete examples including multi-region deployments, component dependencies, deferred changes patterns, and linked Stacks, see references/examples.md.

Best Practices

1. Component Granularity: Create components for logical infrastructure units that share a lifecycle
2. Module Compatibility:
   • Modules used with Stacks cannot include provider blocks (configure providers in Stack configuration)
   • Test public registry modules before using in production Stacks - some modules may have compatibility issues
   • Consider using raw resources for critical infrastructure if module compatibility is uncertain
   • Example: Some terraform-aws-modules versions have been found to have compatibility issues with Stacks (e.g., ALB and ECS modules)
3. State Isolation: Each deployment has its own isolated state
4. Input Variables: Use variables for values that differ across deployments; use locals for shared values
5. Provider Lock Files: Always generate and commit .terraform.lock.hcl to version control
6. Naming Conventions: Use descriptive names for components and deployments
7. Deployment Groups: You can organize deployments into deployment groups. Deployment groups enable auto-approval rules, logical organization, and provide a foundation for scaling. Deployment groups are an HCP Terraform Premium tier feature
8. Testing: Test Stack configurations in dev/staging deployments before production

Troubleshooting

Circular Dependencies: Refactor to break circular references or use intermediate components.

Deployment Destruction: Cannot destroy from UI. Set destroy = true in deployment block, upload configuration, and HCP Terraform creates a destroy run.

Empty Diagnostics: Add required stack_deployment_step_id query parameter to diagnostics API requests.

Module Compatibility: Test public registry modules before production use. Some modules may have compatibility issues with Stacks.

References

For detailed documentation, see:

• references/component-blocks.md - Complete component block reference with all arguments and syntax
• references/deployment-blocks.md - Complete deployment block reference with all configuration options
• references/linked-stacks.md - Publish outputs and upstream inputs for linking Stacks together
• references/examples.md - Complete working examples for multi-region and component dependencies
• references/api-monitoring.md - Full API workflow for programmatic monitoring and automation
• references/troubleshooting.md - Detailed troubleshooting guide for common issues and solutions