How to create stacks using CLI including the private code/no-code modules

Introduction

HCP Terraform Stacks allows you to orchestrate multiple Terraform modules as a single unit. When using private modules from the HCP Registry, the CLI workflow ensures that your local configuration is validated and synchronized with the HCP Terraform cloud environment.

This article explains the correct syntax to reference private registry modules in Terraform Stacks, along with a validated end-to-end CLI workflow.

Prerequisites 

• HCP Terraform CLI: Version 1.13.x or higher (recommended your .terraform-version matches your local install).

• Authenticated Session: Ensure you have logged in via terraform login.

• Permissions: You must have Manage Stacks permissions in your HCP Terraform Organization.

  

• Private Module: A module published and available in the HCP Terraform private registry.

Procedures

1. Define and Organize All Required Stack Configuration Files

Before defining a component that consumes a private registry module, ensure that all required Stacks configuration files are properly defined and placed in the correct file types. Terraform Stacks enforces strict separation of configuration blocks by file extension.

a. Define Providers (providers.tfcomponent.hcl)

All required providers must be declared explicitly using required_providers, along with any provider configurations referenced by components.

required_providers {
random = {
source = "hashicorp/random"
version = "3.7.1"
}
}


provider "random" "test" {}

b. Define Input Variables (variables.tfcomponent.hcl)

Define input variables that will be passed into the component. This includes string and boolean variables used by the module inputs.

variable "string_length" {
description = "Length of the string"
type = string
}

variable "special" {
description = "Whether to include special characters"
type = bool
}

c. Define the Component Using a Private Registry Module

When referencing a private registry module in a Stack component, the source attribute must follow this format: app.terraform.io/<organization>/<module-name>/<provider>

component "random-test" {
source = "app.terraform.io/<org-name>/<module-name>/<provider>"
version = "1.0.4"

# inputs are options if you already have the values and the variables configured at module level.
inputs = {
length = var.string_length
special = var.special
}


providers = {
random = provider.random.test
}
}

 

d. Define the Deployment (deployment.tfdeploy.hcl)

Deployments must be defined in a *.tfdeploy.hcl file. This file declares how components are grouped and deployed within the stack. At a minimum, a deployment block must exist for the stack to create deployment runs.

deployment "application" {
}

 

2. Initialize the Stacks Configuration

From the root of the Stacks configuration directory, run:  terraform stacks init. 

This command initializes the Stacks configuration in .terraform.lock.hcl and downloads the required providers in .terraform directory.

 

3. Validate the Configuration

Run :  terraform stacks validate

If validation succeeds, Terraform confirms that the configuration is ready for use within HCP Terraform.

Note: If you see a Terraform version mismatch warning, ensure your locally installed Terraform version matches the version specified in .terraform-version.

4. Create a Stack

Create a new stack in HCP Terraform: terraform stacks create -organization-name <org-name> -project-name <proj-name> -stack-name <stacks-name>

│ Alternatively, set the ENV VAR 'TF_STACKS_ORGANIZATION_NAME'.
│ Alternatively, set the ENV VAR 'TF_STACKS_PROJECT_NAME'.
│ Alternatively, set the ENV VAR 'TF_STACKS_STACK_NAME'.

5. Upload the Stack Configuration

Upload the validated configuration to HCP Terraform: terraform stacks configuration upload -organization-name <org-name> -project-name <proj-name> -stack-name <stacks-name>

Uploading the configuration creates a new stack configuration version and triggers a deployment run.

6. Watch Stack Configuration Processing

After uploading a stack configuration, you can monitor how the configuration is processed by HCP Terraform using the configuration watch command: terraform stacks configuration watch -organization-name <org-name> -project-name <project-name> -stack-name <stacks-name>

7. View Deployment Runs

List deployment runs for the default deployment group: terraform stacks deployment-run list -organization-name <org-name> -project-name <project-name> -stack-name <stacks-name> -deployment-group-name application_default

8. Watch a Deployment Run

Run command : terraform stacks deployment-run watch -deployment-run-id sdr-zoBxD8h7eXMGMnZm

 

Additional Information: 

• Terraform Stacks CLI Reference : https://developer.hashicorp.com/terraform/cli/commands/stacks 

• Terraform Stacks Concepts: Components, Deployments : https://developer.hashicorp.com/terraform/language/stacks 

• HCP Terraform Stacks Tutorial : https://developer.hashicorp.com/terraform/tutorials/cloud/stacks-deploy