Docs for Stacks in private registry

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",

content/terraform-docs-common/docs/cloud-docs/registry/publish-stack-configuration.mdx

@@ -0,0 +1,82 @@
+---
+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 `<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](/terraform/cloud-docs/registry/using#use-a-stack-component-configuration) to learn more about using the `stack` block.
+
+## 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 `<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).
+
+### Tag versions
+
+The HCP Terraform private registry uses Git tags to identify component configuration versions. Tags must follow semantic versioning format: `x.y.z`. 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

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<!-- BEGIN: TFC:only name:stacks-tfe -->, Stack component configurations,<!-- END: TFC:only name:stacks-tfe --> 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,<!-- BEGIN: TFC:only name:stacks-tfe --> Stacks,<!-- END: TFC:only name:stacks-tfe --> and usage examples in the HCP Terraform private registry UI.
+<!-- BEGIN: TFC:only name:stacks-tfe -->
+- **Stacks support:** The private registry supports publishing and using Stack component configurations.
+<!-- END: TFC:only name:stacks-tfe -->
 - **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<!-- BEGIN: TFC:only name:stacks-tfe --> and Stacks<!-- END: TFC:only name:stacks-tfe --> using version 0.11 and higher can automatically access private modules during Terraform runs. Workspaces<!-- BEGIN: TFC:only name:stacks-tfe --> and Stacks<!-- END: TFC:only name:stacks-tfe --> 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<!-- BEGIN: TFC:only name:stacks-tfe -->, Stack component configurations,<!-- END: TFC:only name:stacks-tfe --> 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**<!-- BEGIN: TFC:only name:stacks-tfe -->, **Stack component configurations**, <!-- END: TFC:only name:stacks-tfe --> 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**<!-- BEGIN: TFC:only name:stacks-tfe --> or **Components**<!-- END: TFC:only name:stacks-tfe --> 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 `<NAME>.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), `<NAME>.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 `<NAME>.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).
+
 <!-- END: TFC:only name:stacks-tfe -->
 
-## Provider and Module Availability
+## Provider and module availability
 
 A workspace<!-- BEGIN: TFC:only name:stacks-tfe --> or Stack <!-- END: TFC:only name:stacks-tfe -->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:
 

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.
 
+<!-- BEGIN: TFC:only name:stacks-tfe -->
+
+### 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.
+
+<!-- END: TFC:only name:stacks-tfe -->
+
 <!-- BEGIN: TFC:only name:public-registry -->
 
 ## Public registry permissions

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",