Merge branch 'RK/agents-updates' into sahar/update_agents_for_stacks_ga

Author: rkoron007

content/terraform-docs-agents/v1.24.x/docs/cloud-docs/agents/agent-pools.mdx

@@ -1,19 +1,25 @@
 ---
 page_title: Manage HCP Terraform agent pools
 description: >-
-  Agent pools are groups of one or more agents. Learn how to manage agent pools and assign them to specific workspaces.
+  Agent pools are groups of one or more agents. Learn how to manage agent pools and assign them to specific workspaces or Stacks.
 ---
 
 # Manage agent pools
 
-HCP Terraform organizes agents into agent pools. An agent pool represents a group of agents that lets HCP Terraform communicate with isolated, private, or on-premises infrastructure. When you configure a workspace to execute runs using agents, any available agent in that workspace's associated agent pool can complete the run. 
+HCP Terraform organizes agents into agent pools. An agent pool represents a group of agents that lets HCP Terraform communicate with isolated, private, or on-premises infrastructure. When you configure a workspace or Stack to execute runs using agents, any available agent in that workspace or Stack's associated agent pool can complete the run.
+
+<Note>
+
+Terraform Enterprise does not support Stacks. You can only scope agent pools to workspaces and projects in Terraform Enterprise.
+
+</Note>
 
 ## Permissions
 
 Managing agent pools requires the following permissions:
 
-- You must be a member of the **Owners** team within your organization to manage an organization's agents.
-- You must have **Admin** access to a workspace before you can change its [execution mode](/terraform/cloud-docs/workspaces/settings#execution-mode) to use an agent pool.
+- You must have the [**Manage Agent Pools**](/terraform/cloud-docs/users-teams-organizations/permissions/organization#manage-agent-pools) permission in your organization to manage an organization's agents.
+- You must have **Admin** access to a workspace or Stack before you can change its execution mode to use an agent pool.
 
 Refer to [Permissions](/terraform/cloud-docs/users-teams-organizations/permissions) in the HCP Terraform documentation for details.
 
@@ -25,7 +31,7 @@ To create an agent pool:
 
 1. Go to your organization's settings, click **Agents**, and then click **Create agent pool**.
 
-1. Enter an **Agent Pool Name**, and then click **Continue**. HCP Terraform uses this name to distinguish agent pools in a workspace's settings.
+1. Enter an **Agent Pool Name**, and then click **Continue**. HCP Terraform uses this name to distinguish agent pools in a workspace or Stack's settings.
 
 1. Enter a token **Description**, and then click **Create Token**.
 
@@ -36,26 +42,25 @@ To create an agent pool:
 To connect an agent to this pool, configure and [start an agent using the official Docker image](/terraform/cloud-docs/agents/agents#quick-start).
 Alternatively, configure and [start an agent using the binary](/terraform/cloud-docs/agents/agents#start-an-agent) then provide then agent with your agent pool's token.
 
-## Scope an agent pool to specific workspaces
+## Scope an agent pool
 
-Scoping an agent pool lets you specify which workspaces can use it. The agent pool is only available from within the chosen workspaces, and it does not appear other workspace's lists of available agent pools.
+Scoping an agent pool lets you specify which workspaces, projects, or Stacks can use it. The agent pool is only available from within the chosen workspaces, projects, or Stacks, and it does not appear in other workspace's, project's, or Stack's lists of available agent pools.
 
-~> **Important:** Scoping an agent pool does not remove it from workspaces that are actively using it. To remove access, you must first remove the agent pool from within the workspace's settings.
+~> **Important:** Scoping an agent pool does not remove it from workspaces, projects, or Stacks that are actively using it. To remove access, you must first remove the agent pool from within the workspace, project, or Stack settings.
 
-To scope an agent pool to specific workspaces within the organization:
+To scope an agent pool to specific workspaces, projects, or Stacks within the organization:
 
 1. Go to your organization's settings, and then click **Agents**. The **Agents** page appears, with a list of agent pools for the organization.
 
 1. Click the name of the pool you want to update.
 
-1. Click **Grant access to specific workspaces**. A menu opens where you can search for workspaces within this organization.
+1. Click **Grant access to specific projects, workspaces, and Stacks**. A menu opens where you can search for workspaces, projects, and Stacks within this organization.
 
-1. Type in the search field to find available workspaces and select the workspaces that should have access to the agent pool.
+1. Type in the search field to find available workspaces, projects, and Stacks and select the workspaces, projects, and Stacks that should have access to the agent pool.
 
 1. Click **Save**.
 
-Only the specified workspaces can use the agent pool.
-
+Only the specified workspaces, projects, and Stacks can use the agent pool.
 
 ## Configure workspaces to use the agent
 
@@ -79,61 +84,55 @@ To configure the workspace to execute runs using an agent:
 
 The workspace begins using the agent for Terraform runs. Runs involving an agent include information about that agent in the run details. HCP Terraform may use different agents for the plan and apply operations, depending on agent availability within the pool.
 
-## Exclude workspaces from accessing an agent pool
+## Configure Stacks to use the agent
 
-Excluding workspaces from an agent pool prevents the specified workspaces from using it.
+Use the following steps to configure a Stack to use an agent pool.
 
-To exclude a workspace from an agent pool:
+### Step 1: Manage existing runs
 
-1. Go to your organization's settings, and then click **Agents**. The **Agents** page appears, with a list of agent pools for the organization.
+Changing a Stack's [execution mode](/terraform/cloud-docs/stacks/configure#change-execution-mode) after Terraform completes a plan causes that run to error during apply. To minimize these errors, wait for all in-progress deployment runs to complete before you change the execution mode.
 
-1. Click the name of the pool you want to update.
+### Step 2: Select agent pool
 
-1. Click **Grant access to specific projects and workspaces**.
+To learn how to configure a Stack to execute runs using an agent, refer to [Configure a Stack](/terraform/cloud-docs/stacks/configure#configure-a-stack-1).
 
-1. Click **Add exclusions**. A menu opens where you can search for workspaces within this organization.
+After changing the execution mode, your Stack begins using the agent for deployment runs. Runs involving an agent include information about that agent in the run details. HCP Terraform may use different agents for the plan and apply runs, depending on agent availability within the pool.
 
-1. Type in the search field to find available workspaces and select the workspaces that should be restricted from accessing the agent pool.
+## Configure projects to use the agent
 
-1. Click **Save**.
+To configure the project to execute runs using an agent:
 
-Only the specified workspaces will be restricted from accessing the agent pool.
+1. Go to the project's **General Settings** page.
+1. Select **Agent** as the [execution mode](/terraform/cloud-docs/workspaces/settings#execution-mode), and select the agent pool this project should use.
+1. Click **Save Settings**.
 
-## Scope an agent pool to specific projects
+The project begins using the agent for Terraform runs. Any workspace within the project will inherit the execution mode, which will be passed onto the run. Runs involving an agent include information about that agent in the run details. HCP Terraform may use different agents for the plan and apply operations, depending on agent availability within the pool.
 
-You can scope an agent pool to specific projects. Only the selected projects are able to use the agent pool.
+## Exclude workspaces and Stacks from accessing an agent pool
 
-~> **Important:** Scoping an agent pool does not remove it from projects that already use it. To remove access, you must first remove the agent pool from the project's settings.
+Excluding workspaces and Stacks from an agent pool prevents the specified workspaces and Stacks from using it.
 
-To scope an agent pool to specific projects within the organization:
+To exclude a workspace or Stack from an agent pool:
 
 1. Go to your organization's settings, and then click **Agents**. The **Agents** page appears, with a list of agent pools for the organization.
 
 1. Click the name of the pool you want to update.
 
-1. Click **Grant access to specific projects and workspaces**. A menu opens where you can search for projects within this organization.
-
-1. Type in the search field to find available projects and select the projects that should have access to the agent pool.
-
-1. Click **Save**.
-
-Only the specified projects can use the agent pool.
+1. Click **Grant access to specific projects and workspaces**.
 
-## Configure projects to use the agent
+1. Click **Add exclusions**. A menu opens where you can search for workspaces and Stacks within this organization.
 
-To configure the project to execute runs using an agent:
+1. Type in the search field to find available workspaces and Stacks and select the workspaces and Stacks that should be restricted from accessing the agent pool.
 
-1. Go to the project's **General Settings** page.
-1. Select **Agent** as the [execution mode](/terraform/cloud-docs/workspaces/settings#execution-mode), and select the agent pool this project should use.
-1. Click **Save Settings**.
+1. Click **Save**.
 
-The project begins using the agent for Terraform runs. Any workspace within the project will inherit the execution mode, which will be passed onto the run. Runs involving an agent include information about that agent in the run details. HCP Terraform may use different agents for the plan and apply operations, depending on agent availability within the pool.
+Only the specified workspaces and Stacks are restricted from accessing the agent pool.
 
 ## Revoke an agent token
 
 You may revoke an issued token from your agents at any time.
 
-Revoking a token causes the agents using it to exit. You must reinitialize agents with a new token before they can continue servicing workspace jobs. 
+Revoking a token causes the agents using it to exit. You must reinitialize agents with a new token before they can continue servicing runs.
 
 Allow active runs in the associated agent pool to finish before revoking a token. If you de-authorize an agent while it is still performing a run, the agent does not post updates about that run. We recommend generating a new token first, initializing the agents using it, and then revoking the old token once no agents are using it. Agent tokens display information about the last time an agent used them. You can use this information to help you decide whether a token is safe to revoke.
 
@@ -145,12 +144,12 @@ Allow active runs in the associated agent pool to finish before revoking a token
 
 ## Delete an agent pool
 
-~> **Important:** You cannot delete an agent pool that is still associated with one or more workspaces.
+~> **Important:** You cannot delete an agent pool that is still associated with one or more workspaces or Stacks.
 
 To delete an agent pool:
 
-1. Wait for all associated workspaces to complete all in progress runs.
-1. Remove the agent pool from all associated workspaces.
+1. Wait for all associated workspaces and Stacks to complete all in progress runs.
+1. Remove the agent pool from all associated workspaces and Stacks.
 1. Navigate to your organization's settings, click **Agents**, and then click the name of the agent pool you want to delete.
 1. Click **Delete agent pool**.
 1. Click **Yes, delete agent pool** to confirm.

content/terraform-docs-agents/v1.24.x/docs/cloud-docs/agents/agents.mdx

@@ -97,7 +97,7 @@ RUN echo 'tfc-agent ALL=NOPASSWD: /usr/bin/apt-get , /usr/bin/apt' >> /etc/sudoe
 
 USER tfc-agent
 ```
- 
+
 The above customized Dockerfile lets an agent install additional software using `sudo apt-get`.
 
 ### Single-execution mode
@@ -130,15 +130,15 @@ If a provider does not support your agent’s architecture, the following error
 ```plaintext
 Error: Incompatible provider version
 
-Provider registry.terraform.io/<namespace>/<name_version> does not have a 
+Provider registry.terraform.io/<namespace>/<name_version> does not have a
 package available for your current platform, <os_architecture>.
 
-Provider releases are separate from Terraform CLI releases, so not all 
-providers are available for all platforms. Other versions of this provider 
+Provider releases are separate from Terraform CLI releases, so not all
+providers are available for all platforms. Other versions of this provider
 may have different platforms supported.
 ```
 
-You can call the [Terraform provider registry API](/terraform/internals/provider-registry-protocol#list-available-versions) to confirm the architectures available for a provider. 
+You can call the [Terraform provider registry API](/terraform/internals/provider-registry-protocol#list-available-versions) to confirm the architectures available for a provider.
 
 Sample request:
 
@@ -177,7 +177,7 @@ Sample response:
 
 <!--
   ⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️
-  WARNING: This the CLI options section is auto-generated during agent release process. 
+  WARNING: This the CLI options section is auto-generated during agent release process.
   Do not edit this section directly as your changes will be overwritten.
   ⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️
 -->
@@ -308,7 +308,7 @@ Sample response:
 
 
 * `-request-forwarding`:
-    Enable handling of forwarded HTTP requests. Enable this option only if you 
+    Enable handling of forwarded HTTP requests. Enable this option only if you
     are using product features which require it.
 
     Default: `false`
@@ -331,4 +331,3 @@ Sample response:
 
 * `-v`:
     Display the version and exit.
-

content/terraform-docs-agents/v1.24.x/docs/cloud-docs/agents/hooks.mdx

@@ -12,6 +12,10 @@ functionality of Terraform runs. For example, you may create a hook to
 dynamically download software required by the Terraform run or send an HTTP
 request to a system to kick off an external workflow.
 
+<Note>
+Agent hooks do not support Stack workflows in HCP Terraform.
+</Note>
+
 ## Supported Hooks
 
 HCP Terraform Agents support the following hooks:
@@ -26,7 +30,7 @@ HCP Terraform Agents support the following hooks:
 - `post-apply` - Runs after `terraform apply` during an `apply` operation
 	regardless of whether or not `terraform apply` completed successfully.
 
-## Hook Behavior 
+## Hook Behavior
 
 Please note the following behavior when using hooks:
 
@@ -41,13 +45,13 @@ Please note the following behavior when using hooks:
 	create a `pre-plan` and `pre-apply` hook, but you cannot create two
 	`pre-plan` hooks.
 - Each hook must have the execute permission set.
-- Each hook has a default timeout of 60 seconds and a max timeout of 10 minutes. 
-  You can configure hook timeouts using global timeouts or hook-specific timeouts. 
-  You can set the value of any hook timeout in seconds. If a hook times out, the Terraform 
+- Each hook has a default timeout of 60 seconds and a max timeout of 10 minutes.
+  You can configure hook timeouts using global timeouts or hook-specific timeouts.
+  You can set the value of any hook timeout in seconds. If a hook times out, the Terraform
   run fails immediately.
     - To set global timeouts, use the `TFC_AGENT_HOOK_TIMEOUT` environment variable.
-    - To set hook-specific timeouts, use an environment variable with the hook’s name 
-      `TFC_AGENT_HOOK_[HOOK NAME]_TIMEOUT`. For example, you can set the timeout for the 
+    - To set hook-specific timeouts, use an environment variable with the hook’s name
+      `TFC_AGENT_HOOK_[HOOK NAME]_TIMEOUT`. For example, you can set the timeout for the
       pre-plan hook to 2 minutes by setting `TFC_AGENT_HOOK_PRE_PLAN_TIMEOUT=120`.
       A hook-specific timeout takes precedence over the global hook timeout.
 - Terraform environment variables do not persist across hooks. For example, if a
@@ -136,7 +140,7 @@ user interface.
   Initializing plugins and modules...
   ```
 
-### Running an Agent with Docker 
+### Running an Agent with Docker
 
 When running `tfc-agent` using Docker, you must build a new Docker image
 containing the hooks. To configure hooks:

content/terraform-docs-agents/v1.24.x/docs/cloud-docs/agents/requirements.mdx

@@ -28,9 +28,9 @@ You can use the agent with the following versions of Terraform.
 Workspaces configured to use Terraform versions older than 0.12 cannot select the agent-based execution mode.
 
 
-## Hardware 
+## Hardware
 
-The host running the agent has varying resource requirements depending on the workspaces the agent serves and the agent's configuration. A host can be a dedicated or shared cloud instance, virtual machine, bare metal server, or a container. You should monitor and adjust memory, CPU, and disk space based on each workspace's usage and performance.
+The host running the agent has varying resource requirements depending on the workspaces and Stacks the agent serves, and the agent's configuration. A host can be a dedicated or shared cloud instance, virtual machine, bare metal server, or a container. You should monitor and adjust memory, CPU, and disk space based on each workspace and Stack's usage and performance.
 
 All agents in an agent pool should have the same hardware resources available. If the agents use different resources, run performance can vary significantly between each agent in the pool.
 
@@ -68,7 +68,7 @@ Terraform's `local-exec` provisioners, an `external` data source, or a tfc-agent
 * `tar` - Unarchiver for tar archives.
 * `gzip` - Decompression utility for gzipped archives.
 
-## Networking 
+## Networking
 
 In order for an agent to function properly, it must be able to make outbound TCP connections to the HCP Terraform application APIs. These requests may require perimeter networking as well as container host networking changes, depending on your environment. Refer to the [HCP Terraform IP Ranges documentation](/terraform/cloud-docs/architectural-details/ip-ranges) for more details on the IP ranges.
 
@@ -80,4 +80,4 @@ Additionally, the agent must also be able to communicate with any services requi
 | registry.terraform.io  | tcp/443, HTTPS | Outbound       | Downloading public modules from the Terraform Registry                                                                              |
 | releases.hashicorp.com | tcp/443, HTTPS | Outbound       | Updating agent components and downloading Terraform binaries                                                                        |
 | archivist.terraform.io | tcp/443, HTTPS | Outbound       | Blob Storage   |
-| agents.terraform.io    | tcp/7146, TCP  | Outbound       | Agent RPC interface (currently used for request forwarding and hold your own key features) |
+| agents.terraform.io    | tcp/7146, TCP  | Outbound       | Agent RPC interface (currently used for request forwarding and hold your own key features) |