diff --git a/content/terraform-docs-common/data/cloud-docs-nav-data.json b/content/terraform-docs-common/data/cloud-docs-nav-data.json index 2251ba1d76..f9df6e29f5 100644 --- a/content/terraform-docs-common/data/cloud-docs-nav-data.json +++ b/content/terraform-docs-common/data/cloud-docs-nav-data.json @@ -24,7 +24,7 @@ { "title": "Get started", "href": "https://learn.hashicorp.com/collections/terraform/cloud-get-started?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS" - }, + }, { "title": "Migrate to HCP Terraform", "path": "migrate" @@ -128,30 +128,34 @@ { "title": "Private registry", "routes": [ - { "title": "Overview", "path": "registry" }, + { "title": "Overview", "path": "registry" }, { - "title": "Adding public providers and modules", + "title": "Add public providers and modules", "path": "registry/add" }, { - "title": "Publishing private providers", + "title": "Publish private providers", "path": "registry/publish-providers" }, { - "title": "Publishing private modules", + "title": "Publish private modules", "path": "registry/publish-modules" }, - { "title": "Manage module versions", "path": "registry/manage-module-versions" }, + { + "title": "Publish a Stack", + "path": "registry/publish-stack-configuration" + }, + { "title": "Manage module versions", "path": "registry/manage-module-versions" }, { "title": "Test-integrated modules", "path": "registry/test" }, - { "title": "Using providers and modules", "path": "registry/using" }, + { "title": "Use artifacts from the registry", "path": "registry/using", "alias": "providers, modules, components" }, { "title": "Configuration designer", "path": "registry/design" } - ] + ] }, { "title": "Scope access with projects", diff --git a/content/terraform-docs-common/docs/cloud-docs/registry/publish-stack-configuration.mdx b/content/terraform-docs-common/docs/cloud-docs/registry/publish-stack-configuration.mdx new file mode 100644 index 0000000000..8242cc20ce --- /dev/null +++ b/content/terraform-docs-common/docs/cloud-docs/registry/publish-stack-configuration.mdx @@ -0,0 +1,84 @@ +--- +page_title: Publish Stack component configurations to the HCP Terraform private registry +description: Use the HCP Terraform private registry to publish and share Stack component configurations across your organization. +tfc_only: true +--- + +# 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 `.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 `.tfcomponent.hcl` file. Refer to [Use artifacts from the HCP Terraform private registry](/terraform/cloud-docs/registry/using#use-a-stack-component-configuration) 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](/terraform/cloud-docs/api-docs/private-registry/stack-component-configurations#create-a-stack-component-configuration) + +## Prerequisites + +To publish a Stack component configuration file you must meet the following requirements: + +- You must be a member of the [owners team](/terraform/cloud-docs/users-teams-organizations/permissions/organization#organization-owners) or a team with [**Manage Stack component configurations** permissions](/terraform/cloud-docs/users-teams-organizations/permissions/organization#manage-private-registry). +- You must configure a VCS provider connection. Refer to [Connect to VCS Providers](/terraform/cloud-docs/vcs) 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 `.tfcomponent.hcl` file that defines your Stack's components. +- Your repository must have at least one [Git release tag using semantic versioning](#tag-versions). + +### Tag versions + +The HCP Terraform private registry uses Git tags to identify component configuration versions. After the [tag prefix](#publish-multiple-configurations-from-one-repository), 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. +1. Select **Registry** from the sidebar, then **Private Library**. +1. Click **Publish** and choose **Stack component configuration** from the menu. +1. Select your VCS provider from the list. +1. Choose the repository that contains your component configuration. You can also search by typing part of the repository name. +1. If your component configuration is not at your repository's root, you can optionally specify a path in the **Source Directory** field. +1. You can optionally specify **Tag Prefix** if you are publishing [multiple component configurations from the same repository](#publish-multiple-configurations-from-one-repository). +1. Click **Next**. +1. In the **Stack component configuration source address** field, enter a name for the component configuration. Users reference this name in [stack blocks](/terraform/language/block/stack/tfcomponent/stack#source). +1. 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](#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](/terraform/language/stacks/component/config) 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 diff --git a/content/terraform-docs-common/docs/cloud-docs/registry/using.mdx b/content/terraform-docs-common/docs/cloud-docs/registry/using.mdx index 0daeff3f3f..8df0f2c1f3 100644 --- a/content/terraform-docs-common/docs/cloud-docs/registry/using.mdx +++ b/content/terraform-docs-common/docs/cloud-docs/registry/using.mdx @@ -1,38 +1,41 @@ --- -page_title: Use providers and modules from the HCP Terraform private registry -description: Learn how to use providers and modules from the HCP Terraform private registry in your Terraform configuration. +page_title: Use artifacts from the HCP Terraform private registry +description: Learn how to use artifacts from the HCP Terraform private registry in your Terraform configuration. --- -# Use providers and modules from the HCP Terraform private registry +# Use artifacts from the HCP Terraform private registry -All users in an organization can view the HCP Terraform private registry and use the available providers and modules. A private registry has some key requirements and differences from the [public Terraform Registry](/terraform/registry): +All users in an organization can view the HCP Terraform private registry and use the available providers, Stack component configurations, and modules. A private registry has some key requirements and differences from the [public Terraform Registry](/terraform/registry): -- **Location:** Search for providers, modules, and usage examples in the HCP Terraform private registry UI. +- **Location:** Search for providers, modules, Stacks, and usage examples in the HCP Terraform private registry UI. + +- **Stacks support:** The private registry supports publishing and using Stack component configurations. + - **Provider and Module block `source` argument:** Private providers and modules use a different format. -- **Terraform version:** HCP Terraform workspaces using version 0.11 and higher can automatically access your private modules during Terraform runs, and workspaces using version 0.13 and higher can also automatically access private providers. -- **Authentication:** If you run Terraform on the command line, you must [authenticate](#authentication) to HCP Terraform or your instance to use providers and modules in your organization’s private registry. +- **Terraform version:** HCP Terraform workspaces and Stacks using version 0.11 and higher can automatically access private modules during Terraform runs. Workspaces and Stacks using version 0.13 and higher can also automatically access private providers. +- **Authentication:** If you run Terraform on the command line, you must [authenticate](#authentication) to HCP Terraform or your instance to use artifacts in your organization’s private registry. HCP Terraform supports using modules in written configuration or through the [no-code provisioning workflow](/terraform/cloud-docs/workspaces/no-code-provisioning/provisioning). -## Finding providers and modules +## Find artifacts -To find available providers and modules, click the **Registry** button. The **Registry** page appears. +To find available providers, Stack component configurations, and modules, select **Registry** from the side navigation in your organization. -Click **Providers** and **Modules** to toggle back and forth between lists of available providers and modules in the private registry. You can also use the search field to filter for titles that contain a specific keyword. The search does not include READMEs or resource details. +Click **Providers**, **Stack component configurations**, or **Modules** to toggle between lists of available artifacts in the private registry. You can also use the search field to filter for titles that contain a specific keyword. The search does not include `README`s or resource details. ### Shared providers and modules in Terraform Enterprise On Terraform Enterprise, your [registry sharing](/terraform/enterprise/admin/application/registry-sharing) configuration may grant you access to another organization's providers and modules. Providers and modules that are shared with your current organization have a **Shared** badge in the private registry (below). Providers and modules in your current organization that are shared with other organizations have a badge that says **Sharing**. -### Viewing provider and module details and versions +### View artifact details and versions -Click a provider or module to view its details page. Use the **Versions** menu in the upper right to switch between the available versions, and use the **Readme**, **Inputs**, **Outputs**, **Dependencies**, and **Resources** tabs to view more information about the selected version. +Click an artifact to view its details page. Use the **Versions** menu in the upper right to switch between the available versions, and use the **Readme**, **Inputs**, **Outputs**, **Dependencies**, and **Resources** or **Components** tabs to view more information about the selected version. -### Viewing nested modules and examples +### View nested modules and examples Use the **Submodules** menu to navigate to the detail pages for any nested modules. Use the **Examples** menu to navigate to the detail pages for any available example modules. -## Provisioning infrastructure from no-code ready modules +## Provision infrastructure from no-code ready modules You can use modules marked **No-Code Ready** to create a new workspace and automatically provision the module's resources without writing any Terraform configuration. Refer to [Provisioning No-Code Infrastructure](/terraform/cloud-docs/workspaces/no-code-provisioning/provisioning) for details. @@ -206,10 +209,8 @@ component "my-component" { # ... } - ``` - To source a module from a remote address, use a URL that points to a `tar.gz` file: ```hcl @@ -247,9 +248,27 @@ component "demo" { To learn more about components syntax, refer to the [`component` block reference](/terraform/language/block/stack/tfcomponent/component). +## Use a Stack component configuration + +You can [publish component configurations](/terraform/cloud-docs/registry/publish-stack-configuration) to your private registry to let other users in your organization create a new Stack using that configuration. + +To use a component configuration published in the private registry, do the following: + +1. In HCP Terraform, navigate to your organization. +1. Select **Registry** from the sidebar, then **Private Library**. +1. Click the name of the component configuration you want to use. +1. Copy the `stack` code block snippet from **Usage instructions**. The `stack` block includes the source address, version constraint, and any required input variables. +1. Create a `.tfcomponent.hcl` file and paste the `stack` block snippet. +1. Add a `.terraform-version` file and specify a Terraform version for your Stack. You must specify Terraform v1.14.1 or above. +1. Run `terraform stacks init` to create a provider lock file and install your providers. +1. Create a [deployment file](/terraform/language/stacks/deploy/config), `.tfdeploy.hcl`, and specify values for each required input variable. You can refer to the **Inputs** tab on the component configuration's details page to learn more about the required variables. +1. [Create your Stack](/terraform/cloud-docs/stacks/create) in HCP Terraform. + +Defining a `stack` block in a `.tfcomponent.hcl` file sources a Stack's entire component configuration, including all of the Stack's components and providers. To learn more about the `stack` block, refer to the [`stack` block reference](/terraform/language/block/stack/tfcomponent/stack). + -## Provider and Module Availability +## Provider and module availability A workspace or Stack can only use private providers and modules from its own organization's registry. When using providers or modules from multiple organizations in the same configuration, we recommend: @@ -272,7 +291,7 @@ _Permissions Example_ A user belongs to three organizations (1, 2, and 3), and organizations 1 and 2 share access with each other. In this case, the user's token gives them access to the private registries for all of the organizations they belong to: 1, 2, and 3. However, a team token from a team in organization 1 only gives the user access to the private registry in organizations 1 and 2. -#### Configure Authentication +#### Configure authentication To configure authentication to HCP Terraform or your Terraform Enterprise instance, you can: diff --git a/content/terraform-docs-common/docs/cloud-docs/users-teams-organizations/permissions/organization.mdx b/content/terraform-docs-common/docs/cloud-docs/users-teams-organizations/permissions/organization.mdx index ecc088b327..909f144078 100644 --- a/content/terraform-docs-common/docs/cloud-docs/users-teams-organizations/permissions/organization.mdx +++ b/content/terraform-docs-common/docs/cloud-docs/users-teams-organizations/permissions/organization.mdx @@ -249,8 +249,9 @@ The following permissions control access to the organization's [private registry | Permission name | Description | |-----------------|-------------| -| [Manage modules](#manage-private-modules) | Publish and delete modules in private registry | -| [Manage providers](#manage-private-providers) | Publish and delete providers in private registry | +| [Manage modules](#manage-private-modules) | Publish and delete modules in the private registry | +| [Manage providers](#manage-private-providers) | Publish and delete providers in the private registry | +| [Manage Stack component configurations](#manage-stack-component-configurations) | Publish and delete Stack component configurations in the private registry | ### Manage private modules @@ -260,6 +261,14 @@ Allow members to publish and delete modules in the organization's private regist Allow members to publish and delete providers in the organization's private registry. + + +### Manage Stack component configurations + +Allow members to [publish and delete Stack component configurations](/terraform/cloud-docs/registry/publish-stack-configuration) in the organization's private registry. + + + ## Public registry permissions diff --git a/content/terraform/v1.14.x/data/language-nav-data.json b/content/terraform/v1.14.x/data/language-nav-data.json index 4d5633fc2d..94d9e1764d 100644 --- a/content/terraform/v1.14.x/data/language-nav-data.json +++ b/content/terraform/v1.14.x/data/language-nav-data.json @@ -354,6 +354,7 @@ { "title": "Component configuration", "routes": [ { "title": "Overview", "path": "block/stack/tfcomponent" }, { "title": "component", "path": "block/stack/tfcomponent/component" }, + { "title": "stack", "path": "block/stack/tfcomponent/stack" }, { "title": "required_providers", "path": "block/stack/tfcomponent/required_providers" }, { "title": "provider", "path": "block/stack/tfcomponent/provider" }, { "title": "variable", "path": "block/stack/tfcomponent/variable" }, @@ -423,7 +424,7 @@ { "title": "lifecycle", "path": "meta-arguments/lifecycle", - "alias": "actions" + "alias": "actions" }, { "title": "provider", diff --git a/content/terraform/v1.14.x/docs/language/block/stack/tfcomponent/stack.mdx b/content/terraform/v1.14.x/docs/language/block/stack/tfcomponent/stack.mdx new file mode 100644 index 0000000000..313a49d219 --- /dev/null +++ b/content/terraform/v1.14.x/docs/language/block/stack/tfcomponent/stack.mdx @@ -0,0 +1,150 @@ +--- +page_title: stack block reference for Terraform Stack component configurations +description: 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. +--- + +# `stack` block reference + +Use the `stack` block to source component configurations from the [HCP Terraform private registry](/terraform/cloud-docs/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 `.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](/terraform/language/block/stack/tfcomponent/component) which source individual Terraform modules, the `stack` block sources an entire component configuration. Refer to [Publish Stack component configurations](/terraform/cloud-docs/registry/publish-stack-configuration) to learn more about publishing Stack configurations to the private registry. + +When you define a `stack` block in a `.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](/terraform/cloud-docs/registry/using) to learn more about using the stack block to define a new Stack. + +## Configuration model + +The `stack` block supports the following arguments: + +- [`stack "