Publish Stack component configurations to the private registry

Publish Stack component configurations to your organization's private registry to simplify sharing and versioning configurations with your teams.

Background

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

You can publish a component configuration to the HCP Terraform private registry to share a Stack across your organization. When you publish a component configuration, other teams can create a new Stack using that configuration by sourcing it in a stack block in their own <NAME>.tfcomponent.hcl file. Refer to Use artifacts from the HCP Terraform private registry to learn more about using the stack block.

You can also publish component configurations to your private registry using the HCP Terraform API. To learn more, refer to the Stack component configurations reference

Prerequisites

To publish a Stack component configuration file you must meet the following requirements:

• You must be a member of the owners team or a team with Manage Stack component configurations permissions.
• You must configure a VCS provider connection. Refer to Connect to VCS Providers for more information.

Your VCS provider connection and repository must also meet the following requirements:

• Your HCP Terraform user account must have admin access to your connected VCS repository.
• GitLab repositories must be in the main organization or group, and not in any subgroups.
• Your repository must contain a <NAME>.tfcomponent.hcl file that defines your Stack's components.
• Your repository must have at least one Git release tag using semantic versioning.

Tag versions

The HCP Terraform private registry uses Git tags to identify component configuration versions. After the tag prefix, tags must follow semantic versioning, such as 1.2.3. The registry ignores tags that don't match this format.

When you push a new semantic version tag to your repository, the registry automatically imports it as a new version.

Publish a component configuration

To publish a Stack component configuration, complete the following steps:

1. In HCP Terraform, navigate to your organization.
2. Select Registry from the sidebar, then Private Library.
3. Click Publish and choose Stack component configuration from the menu.
4. Select your VCS provider from the list.
5. Choose the repository that contains your component configuration. You can also search by typing part of the repository name.
6. If your component configuration is not at your repository's root, you can optionally specify a path in the Source Directory field.
7. You can optionally specify Tag Prefix if you are publishing multiple component configurations from the same repository.
8. Click Next.
9. In the Stack component configuration source address field, enter a name for the component configuration. Users reference this name in stack blocks.
10. Click Create.

HCP Terraform imports your component configuration and redirects you back to the main private registry page. Click the name of your component configuration to view its details page.

Publish multiple configurations from one repository

If your repository contains multiple component configurations, use tag prefixes to publish them individually. For example, you can add GitHub tags such as database-v1.0.0 and network-v1.0.0, then specify database- or network- as tag prefixes when you publish each component configuration.

Without a tag prefix, HCP Terraform publishes new versions for all component configurations whenever you create a new tag in GitHub.

Release new versions

To release a new version of a component configuration, push a new release tag to the associated VCS repository. The HCP Terraform private registry automatically imports the configuration and creates a new version for that tag. Refer to Tag versions to learn about tag requirements.

View and manage published configurations

You can view the following information about a component configuration on its details page:

• Versions
• Source repository
• Providers
• Inputs
• Outputs
• Components
• Documentation from a README file in the repository

Refer to Define configuration to learn more about Stack component configurations.

You can use the Manage component configuration menu to perform the following actions:

• View version history
• Delete a specific version of the component configuration
• Delete the entire component configuration