Define configuration

In the component configuration file, you declare what infrastructure components are part of the Stack.

Your component configuration file defines multiple components that share a lifecycle you can repeatedly deploy. This helps ensure consistency across environments and reduces the complexity of provisioning at scale.

Background

You declare the infrastructure that makes up your Stack in the component configuration file. Component configuration files replace Terraform’s traditional root module and serve as the blueprint for what your Stack deploys.

Component configuration files use the <NAME>.tfcomponent.hcl file type, and define everything that shares your Stack’s lifecycle. After writing your component configuration, you can write a deployment configuration to dictate how HCP Terraform deploys your Stack’s infrastructure.

As with Terraform configuration files, HCP Terraform processes all of the blocks in your component configuration and deployment configuration files in your Stack's root directory in dependency order. You can organize your component configuration into multiple files, as in traditional Terraform configurations.

Requirements

Use Terraform v1.13.x or later to access the Stacks CLI plugin, and run terraform stacks CLI commands.

During the beta release, Stacks had a separate Terraform Stacks CLI, which no longer supports current functionality.

Create a version file

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.13.0:

1.13.0

Define your component configuration

We recommend designing your Stack before you begin writing your configuration files.

All of your Stack’s configuration files must use the .tfcomponent.hcl file type. You can set up your component configuration into multiple files as in traditional Terraform configurations. For example, you can have variables.tfcomponent.hcl, providers.tfcomponent.hcl, and we recommend creating one root-level file for your component blocks, such as components.tfcomponent.hcl.

The component block defines the pieces that make up your Stack. Add a component block for each top-level module you want to include in the Stack. Specify the source module, inputs, and providers for each component.

component "cluster" {
    source = "./eks"
    inputs = {
        aws_region          = var.aws_region
        cluster_name_prefix = var.prefix
        instance_type       = "t2.medium"
    }
    providers = {
        aws       = provider.aws.this
        random    = provider.random.this
        tls       = provider.tls.this
        cloudinit = provider.cloudinit.this
    }
}

After establishing your top-level modules, you can use child modules without adding additional component blocks.

The component block supports the for_each meta-argument if you need to replicate components across multiple instances. For example, the following configuration uses for_each to provision modules in multiple AWS regions for a given environment.

component "s3" {
    for_each = var.regions

    source = "./s3"

    inputs = {
        region = each.value
    }

    providers = {
        aws    = provider.aws.configurations[each.value]
        random = provider.random.this
    }
}

You can define the following blocks in component configuration files to configure your Stack's components:

• 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.

Provider authentication works differently for a Stack, for more details on declaring providers in Stacks, refer to Declare providers.

After writing your component configuration, you can validate your configuration locally using the Terraform CLI.

Validate your configuration

Once you have finished your component configuration, you can use terraform stacks CLI commands to validate your configuration and generate the necessary provider lock files.

$ terraform stacks init
$ terraform stacks validate

You can also re-format your configuration files using the terraform fmt command to ensure consistent styling:

$ terraform stacks fmt

Next steps

If you have not yet defined the providers for your Stack, proceed to Declare providers. You can also learn how to Authenticate your Stack to ensure your providers are properly set up.

After completing your component configuration, the next step is to define your deployment configuration to specify how you want to deploy your Stack's infrastructure.