Merge pull request #374 from hashicorp/RK/stacks-docs

[Hashiconf] Stacks Docs

Author: rkoron007

website/data/cloud-docs-nav-data.json

@@ -375,6 +375,22 @@
       { "title": "Private VCS Providers", "path": "vcs/private"},
       { "title": "Troubleshooting", "path": "vcs/troubleshooting" }
     ]
+  },
+   {
+    "title": "Stacks <sup>BETA</sup>",
+    "routes": [
+      { "title": "Overview", "path": "stacks" },
+      { "title": "Create a Stack", "path": "stacks/create" },
+      { "title": "Configure a Stack", "path": "stacks/configure" },
+      {
+        "title": "Deploy infrastructure",
+        "routes": [
+          { "title": "Configuration versions", "path": "stacks/deploy/configuration-versions" },
+          { "title": "Review deployment plans", "path": "stacks/deploy/plans" }
+        ]
+      },
+      { "title": "Destroy a Stack", "path": "stacks/destroy" }
+    ]
   },
   {
     "title": "Private Registry",

website/docs/cloud-docs/stacks/configure.mdx

@@ -0,0 +1,38 @@
+---
+page_title: Configure a Stack
+description: Learn how to configure a Stack’s name, description, and VCS settings in HCP Terraform.
+tfc_only: true
+---
+
+# Configure a Stack
+
+This guide explains configuring a Stack’s name, description, and VCS settings in HCP Terraform.
+
+## Requirements
+
+To view a Stack and its configurations, you must also be a member of a team in your organization with one of the following permissions:
+
+* [Organization-level **Manage all projects**](/terraform/cloud-docs/users-teams-organizations/permissions#manage-all-projects) or higher  
+* [Project-level **Maintain**](/terraform/cloud-docs/users-teams-organizations/permissions#maintain) or higher
+
+## Configure a stack
+
+You can configure a Stack by performing the following steps:
+
+1. In the navigation menu, click **Projects** under **Manage**.  
+1. Select the project containing your Stack.  
+1. Click **Stacks** in the navigation menu.  
+1. Select the Stack you want to configure.  
+1. Click **Stack settings** in the navigation menu.  
+1. Update any of the following settings:  
+   * Name   
+   * Description  
+   * Version control settings, including:
+        * Stacks automatically trigger new plans when you push them to your repositories’ default branch. To deactivate this behavior,  uncheck **VCS Trigger Enabled**.  
+        * You can also configure Stacks to work from either a branch or tag-based workflow.   
+        * By default, HCP Terraform fetches your stack’s configuration after creating your Stack. To fetch your Stack configuration manually, uncheck **Fetch configuration after HCP Terraform creates stack**.  
+1. Click **Save settings** to apply your changes.
+
+## Next steps
+
+After configuring your stack, you can learn more about how to [review your stack’s deployment plans](/terraform/cloud-docs/stacks/deploy/plans) or [destroy your stack](/terraform/cloud-docs/stacks/destroy).

website/docs/cloud-docs/stacks/create.mdx

@@ -0,0 +1,51 @@
+---
+page_title: Create a Stack
+description: Learn how to create a Stack in HCP Terraform so you can get started deploying your infrastructure.
+tfc_only: true
+---
+
+# Create a Stack
+
+Stacks enable you to provision and coordinate your infrastructure lifecycle at scale, offering an organized and reusable approach that expands upon infrastructure as code (IaC). 
+
+> **Hands-on**: Try out the [Deploy a Stack with HCP Terraform](/terraform/tutorials/cloud/stacks-deploy) tutorial to get started with Stacks quickly.
+
+This article explains how to create a Stack in HCP Terraform using a Stack’s configuration and deployment configuration files.
+
+## Requirements
+
+Stacks are not available for users on legacy HCP Terraform team plans. Learn more about [migrating to current HCP Terraform plans](/terraform/cloud-docs/overview/migrate-teams-standard). 
+
+To create a Stack in HCP Terraform, you must set up the following:
+* [Connect a VCS provider](/terraform/cloud-docs/vcs) using the Github App, GitHub OAuth workflow, or a GitLab VCS workflow.
+* A repository with a top-level [Stack configuration](/terraform/language/stacks/create/config) and a [deployment configuration](/terraform/language/stacks/reference/tfdeploy). Your Stack configuration file should include at least one `component` block, and your deployment configuration file should include at least one `deployment` block.
+
+You must also be a member of a team in your organization with one of the following permissions:
+* [Organization-level **Manage all projects**](/terraform/cloud-docs/users-teams-organizations/permissions#manage-all-projects)
+* [Project-level **Maintain**](/terraform/cloud-docs/users-teams-organizations/permissions#maintain) or higher
+
+## Create a Stack
+
+If you are creating a Stack in an organization for the first time, you should first enable Stacks for your organization. Navigate to your organization’s **Settings** page, and in the **General** settings, check the box next to **Stacks** to enable them. 
+
+Stacks live alongside workspaces in a project. To create a new Stack in HCP Terraform, perform the following steps:
+
+1. In the navigation menu, click **Projects** under **Manage**.  
+1. Select the project where you want to create your Stack.  
+1. In the project's navigation menu, select **Stacks**.  
+1. Click **+ New stack**.  
+1. Select a version control provider from the list.  
+1. Choose an organization and repository from the filterable list. If your repository is missing, enter its ID in the text field below the list. The list only displays the first 100 repositories from your VCS provider.  
+1. Enter a new **Stack Name**.   
+    * The name must be unique within the project and can include letters, numbers, dashes (`-`), and underscores (`_`). We recommend using 90 characters or less for the name of your Stack.   
+1. You can optionally add a description for your Stack.  
+1. You can optionally adjust your version control settings by expanding **Advanced Options.**  
+    * Stacks automatically trigger new plans when you push them to your repositories’ default branch. You can deactivate this by toggling the **VCS Trigger Enabled** setting.  
+    * You can configure Stacks to use either a branch or tag-based workflow.   
+    * By default, HCP Terraform fetches your stack’s configuration after creating your Stack. To fetch your Stack configuration manually, uncheck **Fetch configuration after HCP Terraform creates stack.**  
+1. Click **Create Stack**.
+
+## Next steps
+
+After creating your Stack, you can continue to iterate on your configuration and [review configuration versions](/terraform/cloud-docs/stacks/deploy/configuration-versions) or learn how to [review your Stack’s deployment plans](/terraform/cloud-docs/stacks/deploy/plans).
+

website/docs/cloud-docs/stacks/deploy/configuration-versions.mdx

@@ -0,0 +1,69 @@
+---
+page_title: Fetch and review configuration versions
+description: Learn how to fetch and review configuration versions for your Stacks in HCP Terraform.
+tfc_only: true
+---
+
+# Fetch and review configuration versions
+
+Stacks automatically detect when you push changes to your configuration from your VCS-linked repository. Every time you push changes to your repository, HCP Terraform automatically fetches your configuration and creates a new configuration version.
+
+Whether automatic or manual, every time HCP Terraform fetches a new version of your configuration file, it creates a new configuration version, whether you made changes to that file or not. HCP Terraform uses a new configuration version to [plan](/terraform/cloud-docs/stacks/deploy/plans) how that configuration version would affect each of your deployments.
+
+This guide explains creating and reviewing new configuration versions in HCP Terraform.
+
+## Requirements
+
+To view a Stack and its configurations, you must also be a member of a team in your organization with one of the following permissions:
+* [Organization-level **Manage all projects**](/terraform/cloud-docs/users-teams-organizations/permissions#manage-all-projects)
+* [Project-level **Maintain**](/terraform/cloud-docs/users-teams-organizations/permissions#read) or higher
+
+## Create configuration versions
+
+Stacks automatically detect when you push changes to your configuration from your VCS-linked repository. Every time you push changes to your repository, HCP Terraform automatically fetches your configuration and creates a new configuration version.
+
+Whether automatic or manual, every time HCP Terraform fetches a new version of your configuration file, it creates a new configuration version, whether you made changes to that file or not.
+
+HCP Terraform then creates a new plan to roll out that new configuration version to your deployments. Learn more about [reviewing and approving deployment plans](/terraform/cloud-docs/stacks/deploy/plans).
+
+### Manually fetch new configurations
+
+If you are not already on your Stack’s deployment page, navigate to it:
+
+1. In the navigation menu, click **Projects** under **Manage**.  
+1. Select the project containing your Stack.  
+1. Click **Stacks** in the navigation menu.  
+1. Select the Stack you want to review.
+
+Stacks automatically detect when you push changes to your configuration from your VCS-linked repository. Every time you push changes to your repository, HCP Terraform automatically fetches your configuration and creates a new configuration version.
+
+If something changes outside of your configuration, you can fetch your configuration manually by clicking **Fetch Configurations from VCS** on a Stack’s **Overview** page or clicking **Fetch configuration** on a Stack’s **Configurations** page. For example, if someone changes resources directly in the AWS console, you can manually fetch your configuration to update your Stack.
+
+## Review configurations
+
+To review your configuration versions, click **Configurations** in the side navigation menu of your Stack.
+
+The **Configurations** page lists the available configuration versions of your Stack. The top-level dashboard lists your configurations and the percentage of deployments that use each configuration version.
+
+Clicking on an individual configuration version reveals more details, including:
+
+* The ID of the configuration version.  
+* The latest commit that HCP Terraform based this configuration version on.  
+* The deployments using this configuration version.  
+* The corresponding plans for each deployment, along with what triggered each plan. Clicking **Quick View** next to a plan lists the differences introduced in that plan.
+
+You can use the **Deployment** filter to filter by deployment name or the **Status** filter to filter by plan status.
+
+### Download configuration data
+
+You can download configuration data from a Stack so you can debug and analyze how your Stack changes over time.  
+
+Select one of the following options in the **Inspect** drop-down to download specific information about your configuration:
+
+* **Configuration event stream** downloads a log file of your configuration’s events.  
+* **Provider schemas** downloads the schema of the providers of your configuration version.   
+* **Source bundle** downloads the files that HCP Terraform built this configuration version.
+
+## Next steps
+
+The overview page for each Stack contains a chart of a Stack's configuration version and its respective deployment. You can [approve or discard deployment plans](/terraform/cloud-docs/stacks/deploy/plans) to manage your deployments.  

website/docs/cloud-docs/stacks/deploy/plans.mdx

@@ -0,0 +1,103 @@
+---
+page_title: Review deployment plans
+description: Learn how to review deployment plans in HCP Terraform Stacks.
+tfc_only: true
+---
+
+# Review deployment plans
+
+Deployment plans are a combination of an individual configuration version and one of your stack’s deployments. As in the traditional Terraform workflow, HCP Terraform creates plans every time a new configuration version introduces potential changes for a deployment. 
+
+This guide explains how to review and approve deployment plans in HCP Terraform.
+
+## Requirements
+
+To view a Stack and its plans, you must also be a member of a team in your organization with one of the following permissions:
+* [Organization-level **View all projects**](/terraform/cloud-docs/users-teams-organizations/permissions#view-all-projects) or higher
+* [Project-level **Write**](/terraform/cloud-docs/users-teams-organizations/permissions#write) or higher
+
+## View a deployment
+
+If you are not already on your stack’s deployment page, navigate to it:
+
+1. In the navigation menu, click **Projects** under **Manage**.  
+1. Select the project containing your Stack.  
+1. Click **Stacks** in the navigation menu.  
+1. Select the Stack you want to review.
+
+A stack’s **Overview** page displays the following information:
+
+* The number of your stack’s components and deployments  
+* Your deployment’s current [health](#check-deployment-health)  
+* The latest configuration version  
+* A chart listing each deployment’s recent configuration versions
+
+To view all of the plans for a deployment, click the name of the deployment you want to review.
+
+A deployment’s page lists its components and the last five deployment plans. Clicking on a component reveals all of the resources it contains. Opening the **Inspect** dropdown menu on a deployment's page reveals the option to download: 
+
+* **State description** downloads that deployment’s current state.  
+* **Provider schemas** downloads the schema of the providers of your deployment. 
+
+### View plans
+
+A Stack deployment can have multiple plans. In a deployment's page, underneath **Latest plans**, each deployment plan lists:
+
+* The plan name   
+* The trigger why HCP Terraform created this plan  
+* The configuration version HCP Terraform created the plan with  
+* When HCP Terraform created the plan
+
+You can see a plan’s full details by clicking the plan’s name or an abbreviated list of the plan’s changes by clicking **Quick View**. You can also click **View all plans** to display a list of all the plans for this deployment. You can filter plans by [health status](#check-deployment-health) in the list of all plans. 
+
+Each plan includes a timeline detailing when the plan started, when it received its configuration version, and when it was approved.  
+
+### Check deployment health
+
+Click **Overview** in the sidebar of your Stack to view the status of each of your deployments. 
+
+| Status | Description |
+| :---- | :---- |
+| Healthy | HCP Terraform is not applying this deployment, no plans await approval, and no diagnostic alerts exist. |
+| Deploying | A plan is approved, and HCP Terraform is applying it. |
+| Plans waiting for approval | HCP Terraform created a plan successfully and is waiting for approval. |
+| Error diagnostics | The deployment has error diagnostic alerts. You can review these errors in |
+| Warning diagnostics | The deployment has warning diagnostic alerts. |
+
+
+## Download plan data
+
+You can download Stack plan data to debug and analyze how your Stack changes over time. 
+
+Select one of the following options in the **Inspect** drop-down to perform the associated action:
+
+* **View plan orchestration results** displays HCP Terraform's decisions while making this plan.  
+* **Download plan event stream** downloads a log file of your plan’s events.   
+* **Download plan description** downloads a file with all plan information.  
+* **View apply orchestration results** displays HCP Terraform's decisions to apply this plan.  
+* **Download apply event stream** downloads a log file of your plan’s events.  
+* **Download apply description** downloads a file with all the information about this applied plan.
+
+## Approve plans
+
+Like traditional Terraform plans, Stack deployment plans list the changes that will occur if you approve that plan. Each component lists its expected resource changes, and you can review those changes as you decide whether to apply a plan. 
+
+When viewing a deployment plan, HCP Terraform notes if that plan is awaiting approval. Click **Approve plan** if you want HCP Terraform to apply a plan to this deployment or **Discard plan** to ignore it. You manage each deployment independently, so any plans you approve only affect the current deployment you are interacting with.
+
+### Convergence checks
+
+After applying any plan, HCP Terraform automatically triggers a plan called a convergence check. A convergence check is a re-plan to ensure components do not have any [deferred changes](#deferred-changes). HCP Terraform continues to trigger new plans until the convergence check returns a plan that does not contain changes. 
+
+By default, each Stack has an `auto-approve` rule named `empty_plan`, which auto-approves a plan if it does not contain changes. When a convergence check contains no changes, HCP Terraform auto-applies that plan.
+
+## Deferred changes
+
+Like with Terraform configuration files, HCP Terraform generates a dependency graph and creates resources defined in `*.tfstack.hcl` and `*.tfdeploy.hcl` files. 
+
+When you deploy a Stack with resources that depend on resources provisioned by other components in your stack, HCP Terraform recognizes the dependency between components and automatically defers that plan until HCP Terraform can complete it successfully. Plans with deferred changes are plans with resources that depend on resources that don't exist yet, requiring follow-up plans.
+
+-> **Hands-on**: Complete the [Manage Kubernetes workloads with stacks](/terraform/tutorials/cloud/stacks-eks-deferred) tutorial to create plans with deferred changes.
+
+HCP Terraform notifies you in the UI if a plan contains deferred changes. Approving a plan with deferred changes makes HCP Terraform automatically create a follow-up plan to properly set up resources in the order of operations those resources require. 
+
+After applying a plan with deferred changes, HCP Terraform notifies you of any replans it creates with a link to **View replan**. You can review the replan to ensure HCP Terraform created your resources as expected.