Backport of Documentation for linking Stacks into v1.10 (#36424)

Author: github-actions[bot]

website/data/language-nav-data.json

@@ -33,7 +33,8 @@
         "routes": [
           { "title": "Define configuration", "path": "stacks/deploy/config" },
           { "title": "Set conditions for deployment plans", "path": "stacks/deploy/conditions" },
-          { "title": "Authenticate a Stack", "path": "stacks/deploy/authenticate" }
+          { "title": "Authenticate a Stack", "path": "stacks/deploy/authenticate" },
+          { "title": "Pass data from one Stack to another", "path": "stacks/deploy/pass-data" }
         ]
       },
       {

website/docs/language/stacks/deploy/pass-data.mdx

@@ -0,0 +1,113 @@
+---
+page_title: Pass data from one Stack to another  
+description: Learn how to pass data from one Stack to another using `publish_output` blocks to output data from one Stack, and `upstream_input` blocks to input that data into another Stack.   
+---
+
+# Pass data from one Stack to another
+
+If you have multiple Stacks that do not share a provisioning lifecycle, you can export data from one Stack for another Stack to consume. If the output value of a Stack changes after a run, HCP Terraform automatically triggers runs for any Stacks that depend on those outputs.
+
+
+## Background
+
+You may need to pass data between different Stacks in your project. For example, one Stack in your organization may manage shared services, such as networking infrastructure, and another Stack may manage application components. Using separate Stacks lets you manage the infrastructure independently, but you may still need to share data from your networking Stack to your application Stack. 
+
+To output information from a Stack, declare a `publish_output` block in the deployment configuration of the Stack exporting data. We refer to the Stack that declares a `publish_output` block as the upstream Stack.
+
+To consume the data exported by the upstream Stack, declare an `upstream_input` block in the deployment configuration of a different Stack in the same project. We refer to the Stack that declares an `upstream_input` block as the downstream Stack.
+
+## Requirements
+
+The `publish_output` and `upstream_input` blocks require at least Terraform version `terraform_1.10.0-alpha20241009` or higher. Download the [latest version of Terraform](https://releases.hashicorp.com/terraform/) to use the most up-to-date functionality.
+
+Downstream Stacks must also reside in the same project as their upstream Stacks.
+
+## Declare outputs
+
+You must declare a `publish_output` block in your deployment configuration for each value you want to output from your current Stack. 
+
+For example, you can add a `publish_output` block for the `vpc_id`  in your upstream Stack’s deployment configuration. You can directly reference a deployment's values with the `deployment.deployment_name` syntax.
+
+<CodeBlockConfig filename="network.tfdeploy.hcl">
+
+```hcl
+# Networking Stack deployment configuration
+
+publish_output "vpc_id" {
+  description = "The networking Stack's VPC's ID."
+  value       = deployment.network.vpc_id
+}
+```
+
+</CodeBlockConfig>
+
+After applying your configuration, any Stack in the same project can now reference your network deployment's `vpc_id` output by declaring an `upstream_input` block. 
+
+Once you apply a Stack configuration version that includes your `publish_output` block, HCP Terraform publishes a snapshot of those values, which allows HCP Terraform to resolve them. Meaning, you must apply your Stack’s deployment configuration before any downstream Stacks can reference your Stack's outputs. 
+
+Learn more about the [`publish_output` block](/terraform/language/stacks/reference/tfdeploy#publish_output-block-configuration).
+
+## Consume the output from an upstream Stack
+
+Declare an `upstream_input` block in your Stack’s deployment configuration to read values from another Stack's `publish_output` block. Adding an `upstream_input` block creates a dependency on the upstream Stack.
+
+For example, if you want to use the output `vpc_id` from an upstream Stack in the same project, declare an `upstream_input` block in your deployment configuration. 
+
+<CodeBlockConfig filename="application.tfdeploy.hcl">
+
+```hcl
+# Application Stack deployment configuration
+
+upstream_input "networking_stack" {
+  type   = "Stack"
+  source = "app.terraform.io/hashicorp/Default Project/networking-stack"
+}
+
+deployment "application" {
+  inputs = {
+    vpc_id = upstream_input.network_stack.vpc_id
+  }
+}
+```
+
+</CodeBlockConfig>
+
+After pushing your Stack's configuration into HCP Terraform, HCP Terraform searches for the most recently published snapshot of the upstream Stack your configuration references. If no snapshot exists, the downstream Stack's run fails. 
+
+If HCP Terraform finds a published snapshot for your referenced upstream Stack, then all of that Stack's outputs are available to this downstream Stack. Add `upstream_input` blocks for every upstream Stack you want to reference. Learn more about the [`upstream_input` block](/terraform/language/stacks/reference/tfdeploy#upstream_input-block-configuration).
+
+
+## Trigger runs when output values change
+
+If an upstream Stack's published output values change, HCP Terraform automatically triggers runs for any downstream Stacks that rely on those outputs. 
+
+In the following example, the `application` deployment depends on the upstream networking Stack. 
+
+<CodeBlockConfig filename="application.tfdeploy.hcl">
+
+```hcl  
+# Application Stack deployment configuration
+
+upstream_input "network_stack" {  
+  type   = "Stack"  
+  source = "app.terraform.io/hashicorp/Default Project/networking-stack"  
+}
+
+deployment "application" {  
+  inputs = {  
+    vpc_id = upstream_input.network_stack.vpc_id  
+  }  
+}
+```
+
+</CodeBlockConfig>
+
+The application Stack depends on the networking Stack’s output, so if the `vpc_id` changes then HCP Terraform triggers a new run for the application Stack. This approach allows you to decouple Stacks that have separate life cycles and ensures that updates in an upstream Stack propagate to downstream Stacks. 
+
+## Remove upstream Stack dependencies
+
+To stop depending on an upstream Stack’s outputs, do the following in your downstream Stack's deployment configuration:
+
+1. Remove the upstream Stack's `upstream_input` block  
+1. Remove any references to the upstream Stack's outputs
+1. Push your configuration changes to HCP Terraform and apply the new configuration

website/docs/language/stacks/design.mdx

@@ -27,11 +27,13 @@ Before writing your Stack configuration, we recommend assessing your current inf
 
 Each Stack should represent a single system or application with a shared lifecycle. Start by analyzing your current infrastructure and identifying the components HCP Terraform should manage together. Components are typically groups of related resources, such as an application’s backend, frontend, or database layer, deployed and scaled together. 
 
+We recommend structuring your Stacks along technical boundaries to keep them modular and manageable. For example, you can create a dedicated Stack for shared services, such as networking infrastructure for VPCs, subnets, or routing tables, and separate Stacks for application components that consume those shared services. This separation allows you to manage shared services independently while passing information between Stacks. For more details, refer to [Pass data from one Stack to another](/terraform/language/stacks/deploy/pass-data).
+
 ### Sketch out your configuration
 
 We recommend sticking to technical boundaries when structuring a Stack configuration. A single Stack should represent a single system with a shared lifecycle. 
 
-We recommend keeping a Stack as self-contained as possible. However, there are valid cases where outputs from one Stack, like a shared VPC networking service Stack, may need to pass inputs into another Stack, like an application Stack. If there’s a well-defined interface between two parts of your infrastructure, it makes sense to model them as separate Stacks.
+While keeping a Stack as self-contained as possible is ideal, there are valid cases where a Stack must consume outputs from another Stack. For example, a shared networking Stack can publish outputs, such as `vpc_id` or subnet IDs, that downstream application Stacks can consume as inputs. This approach ensures modularity and allows you to manage dependencies between Stacks using well-defined interfaces. For more details, refer to [Pass data from one Stack to another](/terraform/language/stacks/deploy/pass-data).
 
 Plan to add a component block to your configuration for every top-level module you want to include in your Stack. After establishing your top-level modules, you can use child modules without adding additional `component` blocks.
 

website/docs/language/stacks/reference/tfdeploy.mdx

@@ -41,6 +41,8 @@ Each Stack must have at least one `deployment` block, and the label of the `depl
 | :---- | :---- | :---- | :---- |
 | `inputs` | A mapping of Stack variable names for this deployment.  The keys in this map must correspond to the names of variables defined in the Stack. The values must be valid HCL literals meeting the type constraint of those variables. | map | Required |
 
+### Reference
+
 For example, the following `deployment` block accepts inputs for variables named `aws_region` and `instance_count` and creates a new deployment in HCP Terraform named “production”. 
 
 ```hcl
@@ -83,18 +85,6 @@ There are two orchestration rules to choose from:
 
 HCP Terraform evaluates the `check` blocks within your `orchestrate` block to determine if it should approve a plan. If all of the checks pass, then HCP Terraform approves the plan for you. If one or more `conditions` do not pass, then HCP Terraform shows the `reason` why, and you must manually approve that plan.
 
-For example, the following `orchestrate` block automatically approves deployments if a component has not changed.
-
-```hcl
-orchestrate "auto_approve" "no_pet_changes" {
-    check {
-        # Check that the pet component has no changes
-        condition = context.plan.component_changes["component.pet"].total == 0
-        reason = "Changes proposed to pet component."
-    }
-}
-```
-
 By default, each Stack has an `auto_approve` rule named `empty_plan`, which automatically approves a plan if it contains no changes. 
 
 ### Specification
@@ -159,6 +149,21 @@ The object in the `context.plan.deployment` field includes the following fields.
 | :---- | :---- | :---- |
 | `deployment_name` | The name of the current deployment HCP Terraform is running this plan on.  You can use this field to check which deployment is running this plan. For example, you can check if this plan is on your production deployment: `context.plan.deployment == deployment.production`. | string |
 
+### Reference
+
+For example, the following `orchestrate` block automatically approves deployments if a component has not changed.
+
+```hcl
+orchestrate "auto_approve" "no_pet_changes" {
+  check {
+    condition = context.plan.component_changes["component.pet"].total == 0
+    reason    = "Changes proposed to pet component."
+  }
+}
+```
+
+If nothing changes in the `component.pet` component, HCP Terraform automatically approves the plan.
+
 ## `identity_token` block configuration
 
 The `identity_token` block defines a JSON Web Token (JWT) that Terraform generates for a given deployment if that `deployment` block references an `identity_token` in its `inputs`. 
@@ -183,6 +188,8 @@ This section provides details about the fields you can configure in the `identit
 | :---- | :---- | :---- | :---- |
 | `audience` | The audience of your token is the resource(s) that uses this token after Terraform generates it. You specify an audience to ensure that the cloud service authorizing the workload is confident that the token you present is intended for that service. | set of strings | Required |
 
+### Reference
+
 Once defined, you can reference an identity token's `jwt` attribute in a deployment's inputs. For example, below we generate a token for a particular role ARN in AWS.
 
 ```hcl
@@ -223,8 +230,6 @@ provider "aws" "this" {
     region = var.region
     assume_role_with_web_identity {
       role_arn           = var.aws_role
-      # Your configuration anticipates the aws_token we created
-      # with the indentity_token block in your deployments file.
       web_identity_token = var.aws_token
     }
   }
@@ -249,23 +254,6 @@ store "store_type" "store_name" {
 
 A store’s type defines where Terraform should look for that store’s credentials and how to decode the credentials it finds. You cannot share arguments across store types.
 
-For example, if you have an HCP Terraform [variable set](/terraform/cloud-docs/workspaces/variables/managing-variables#variable-sets) that contains a value you want to use in your deployment, you can create a `store` block to access that variable set.
-
-```hcl
-store "varset" "tokens" {
-    id       = "<variable_set_id>"
-    category = "terraform"
-}
-
-deployment "main" {
-    inputs = {
-        token = store.varset.tokens.example_token
-    }
-}
-```
-
-You cannot access an entire store and must specifically access individual keys within that store. Meaning, we can access your example’s `example_token` variable by accessing the store’s `varset` type, `store.varset`, then accessing the specific store, `store.varset.tokens.example_token`.
-
 ### `varset` specification and configuration
 
 Use the `varset` store to enable your Stacks to access [variable sets](/terraform/cloud-docs/workspaces/variables/managing-variables#variable-sets) in HCP Terraform. Your Stack must have access to the variable set you are targeting, meaning it must be globally available or assigned to the project containing your Stack.
@@ -309,6 +297,131 @@ deployment "main" {
 
 You can access specific environment variables by key from the `store.varset.available_regions` store, and you can access specific Terraform variables by key using the `store.varset.tokens` store.
 
+### Reference
+
+For example, if you have an HCP Terraform [variable set](/terraform/cloud-docs/workspaces/variables/managing-variables#variable-sets) that contains a value you want to use in your deployment, you can create a `store` block to access that variable set.
+
+```hcl
+store "varset" "tokens" {
+    id       = "<variable_set_id>"
+    category = "terraform"
+}
+
+deployment "main" {
+    inputs = {
+        token = store.varset.tokens.example_token
+    }
+}
+```
+
+You cannot access an entire store and must specifically access individual keys within that store. Meaning, we can access your example’s `example_token` variable by accessing the store’s `varset` type, `store.varset`, then accessing the specific store, `store.varset.tokens.example_token`.
+
 ## `locals` block configuration
 
 A local value assigns a name to an expression, so you can use the name multiple times within your Stack configuration instead of repeating the expression. The `locals` block works exactly as it does in traditional Terraform configurations. Learn more about [the `locals` block](/terraform/language/values/locals).
+
+## `publish_output` block configuration
+
+The `publish_output` block requires at least Terraform version `terraform_1.10.0-alpha20241009` or higher. Download [latest version of Terraform](https://releases.hashicorp.com/terraform/) to use the most up-to-date functionality.
+
+Specifies a value to export from your current Stack, which other Stacks in the same project can consume. Declare one `publish_output` block for each value to export your Stack.
+
+### Complete configuration
+
+When every field is defined, a `publish_output` block has the following form:
+
+<CodeBlockConfig hideClipboard>
+
+```hcl
+publish_output "output_name" {
+  description = "Description of the purpose of this output"
+  value       = deployment.deployment_name.some_value
+}
+```
+
+</CodeBlockConfig>
+
+### Specification
+
+This section provides details about the fields you can configure in the output block.
+
+| Field | Description | Type | Required |
+| :---- | :---- | :---- | :---- |
+| `value` | The value to output.  | any | Required |
+| `description` | A human-friendly description for the output. | string | Optional |
+
+### Reference
+
+For example, you could output the VPC ID from your networking deployment, making it available to other Stacks to input.
+
+<CodeBlockConfig filename="network.tfdeploy.hcl">
+
+```hcl
+# Network Stack's deployment configuration
+
+publish_output "vpc_id" {
+  description = "The networking Stack's VPC's ID."
+  value       = deployment.network.vpc_id
+}
+```
+
+</CodeBlockConfig>
+
+To learn more about passing information between Stacks, refer to [Pass data from one Stack to another](/terraform/language/stacks/deploy/pass-data).
+
+## `upstream_input` block configuration 
+
+The `upstream_input` block requires at least Terraform version `terraform_1.10.0-alpha20241009` or higher. Download [latest version of Terraform](https://releases.hashicorp.com/terraform/) to use the most up-to-date functionality.
+
+The `upstream_input` block specifies another Stack in the same project to consume outputs from. Declare an `upstream_input` block for each Stack you want to reference. If an output from a upstream Stack changes, HCP Terraform automatically triggers runs for any Stacks that depend on those outputs. 
+
+To learn more about passing information between Stacks, refer to [Pass data from one Stack to another](/terraform/language/stacks/deploy/link-stacks). 
+
+### Complete configuration
+
+When every field is defined, an `upstream_input` block has the following form:
+
+<CodeBlockConfig hideClipboard>
+
+```hcl
+upstream_input "upstream_stack_name" {
+  type   = "stack"
+  source = "app.terraform.io/{organization_name}/{project_name}/{upstream_stack_name}"
+}
+```
+
+</CodeBlockConfig>
+
+### Specification
+
+This section provides details about the fields you can configure in the `upstream_input` block.
+
+| Field | Description | Type | Required |
+| :---- | :---- | :---- | :---- |
+| `type` | The only supported type is “stack”. | string | Required |
+| `source` | The upstream Stack’s URL, in the format: `"app.terraform.io/{organization_name}/{project_name}/{upstream_stack_name}"` | string | Required |
+
+### Reference
+
+For example, you could input a VPC ID from an upstream Stack that manages your shared networking service. You can use the `upstream_input` block to pass information from your network Stack into your application Stack.
+
+<CodeBlockConfig filename="application.tfdeploy.hcl">
+
+```hcl
+# Application Stack's deployment configuration
+
+upstream_input "network_stack" {
+  type   = "stack"
+  source = "app.terraform.io/hashicorp/Default Project/networking-stack"
+}
+
+deployment "application" {
+  inputs = {
+    vpc_id = upstream_input.network_stack.vpc_id
+  }
+}
+```
+
+</CodeBlockConfig>
+
+Your application Stack can now securely consume and use outputs from your network Stack. To learn more about passing information between Stacks, reference [Pass data from one Stack to another](/terraform/language/stacks/deploy/pass-data).