stack block reference

Use the stack block to source component configurations from the HCP Terraform private registry. Each stack block represents a reusable component configuration that you can publish, version, and reuse.

Background

Stacks are made up of individual component blocks that each source from a Terraform module. You define components in the <NAME>.tfcomponent.hcl file, which is the component configuration file for your Stack.

In the HCP Terraform private registry, you can publish and manage entire component configuration files to simplify sharing Stacks across your organization. Unlike component blocks which source individual Terraform modules, the stack block sources an entire component configuration. Refer to Publish Stack component configurations to learn more about publishing Stack configurations to the private registry.

When you define a stack block in a <NAME>.tfcomponent.hcl file, the stack block sources the entire component configuration, including all of the Stack's components and providers. Refer to Use artifacts from the HCP Terraform private registry to learn more about using the stack block to define a new Stack.

Configuration model

The stack block supports the following arguments:

• stack "<LABEL>"   block
  • source   string
  • version   string
  • inputs   map

Complete configuration

All available arguments are defined in the following stack block:

stack "<LABEL>" {
  source  = "<NAMESPACE>/<NAME>"
  version = "<VERSION_CONSTRAINT>"

  inputs = {
    <VARIABLE_NAME> = <VALUE>
  }
}

Specification

A stack block supports the following configuration.

stack "<LABEL>"

The label after the stack keyword is a name for the new Stack you are defining, and the name can be any valid identifier.

The following arguments are supported in a stack block:

source

The source argument specifies the component configuration to source from the HCP Terraform private registry.

stack "<LABEL>" {
  source = "<NAMESPACE>/<NAME>"
  # ...
}

The source address's <NAMESPACE> value is your organization's name, and <NAME> is your component configuration's name.

Summary

• Data type: String
• Default: None
• Required: Yes

version

Use the version argument to specify which version of a component configuration to use from the HCP Terraform private registry.

stack "<LABEL>" {
  source  = "<NAMESPACE>/<NAME>"
  version = "<VERSION_CONSTRAINT>"
  # ...
}

The version argument accepts a version constraint string. Terraform uses the newest installed version of the component configuration that meets the constraint. When an acceptable version isn't installed, Terraform downloads the newest version that meets the constraint. We recommend explicitly constraining the acceptable version numbers to avoid unexpected or unwanted changes.

Run terraform stacks init whenever you modify the version argument to update the local cache with the new version.

Summary

• Data type: String
• Default: None
• Required: Yes

inputs

The inputs argument defines a mapping of input variable names to values for the component configuration. The keys in this map must correspond to the variable names defined in the component configuration's variables.

stack "<LABEL>" {
  source  = "<NAMESPACE>/<NAME>"
  version = "<VERSION_CONSTRAINT>"

  inputs = {
    <VARIABLE_NAME> = <VALUE>
  }
}

You can use three types of values in the inputs map:

• Variable references, such as var.variable_name
• Component outputs, such as component.component_name.output_name
• Literal values, such as primitives and functions

Summary

• Data type: Object
• Default: None
• Required: Yes

Examples

The following example demonstrates how to use a stack block to create a Stack using a component configuration published in the HCP Terraform private registry.

Source a component configuration from the private registry

In the following example, Terraform sources the database component configuration from your organization's private registry and constrains it to version 1.x:

stack "database" {
  source  = "my-org/database-stack"
  version = "~> 1.0"

  inputs = {
    environment    = "production"
    instance_count = 3
    region         = "us-west-2"
  }
}

The stack block sources the entire database-stack component configuration, including all of its components and providers. To learn more, refer to Use a Stack component configuration.