Updates for tfc-agent release 1.25.0

content/terraform-docs-agents/v1.25.x/data/cloud-docs-agents-nav-data.json

@@ -0,0 +1,16 @@
+[
+  {
+    "heading": "HCP Terraform Agents"
+  },
+  { "title": "Overview", "path": "" },
+  { "title": "Requirements", "path": "requirements" },
+  { "title": "Install and Run Agents", "path": "agents" },
+  { "title": "Inject Custom Run Actions (Hooks)", "path": "hooks" },
+  { "title": "Manage Agent Pools", "path": "agent-pools" },
+  { "title": "Request Forwarding", "path": "request-forwarding" },
+  { "title": "Telemetry", "path": "telemetry" },
+  { "title": "Logging", "path": "logging" },
+  { "title": "Metrics", "path": "metrics" },
+  { "title": "Tracing", "path": "tracing" },
+  { "title": "Changelog", "path": "changelog" }
+]

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

@@ -0,0 +1,187 @@
+---
+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 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 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 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.
+
+[permissions-citation]: #intentionally-unused---keep-for-maintainers
+
+## Create an agent pool
+
+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 or Stack's settings.
+
+1. Enter a token **Description**, and then click **Create Token**.
+
+1. Save your token information in a secure location. You need the token to connect an agent to this HCP Terraform agent pool, and HCP Terraform does not display the token again after this step.
+
+1. Click **Finish**.
+
+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
+
+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, 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, 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 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, 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, projects, and Stacks can use the agent pool.
+
+## Configure workspaces to use the agent
+
+Use the following steps to configure a workspace to use an agent pool.
+
+### Step 1: Manage existing runs
+
+Changing a workspace's [execution mode](/terraform/cloud-docs/workspaces/settings#execution-mode) after Terraform completes a plan causes that run to error during apply. To minimize these errors, do the following in the workspace before you change the execution mode:
+
+1. Disable [auto-apply](/terraform/cloud-docs/workspaces/settings#auto-apply-and-manual-apply).
+1. Wait for the workspace to complete any runs that are no longer in the [pending stage](/terraform/cloud-docs/run/states#1-the-pending-stage).
+1. [Lock the workspace](/terraform/cloud-docs/workspaces/settings#locking) to prevent new runs.
+
+### Step 2: Select agent pool
+
+To configure the workspace to execute runs using an agent:
+
+1. Go to the workspace's **General Settings** page.
+1. Select **Agent** as the [execution mode](/terraform/cloud-docs/workspaces/settings#execution-mode), and select the agent pool this workspace should use.
+1. Click **Save Settings**.
+
+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.
+
+## Configure Stacks to use the agent
+
+Use the following steps to configure a Stack to use an agent pool.
+
+### Step 1: Manage existing runs
+
+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.
+
+### Step 2: Select agent pool
+
+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).
+
+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.
+
+## Configure projects to use the agent
+
+To configure the project to execute runs using an agent:
+
+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**.
+
+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.
+
+## Exclude workspaces and Stacks from accessing an agent pool
+
+Excluding workspaces and Stacks from an agent pool prevents the specified workspaces and Stacks from using it.
+
+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**.
+
+1. Click **Add exclusions**. A menu opens where you can search for workspaces and Stacks within this organization.
+
+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. Click **Save**.
+
+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 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.
+
+1. Navigate to your organization's settings, click **Agents**, and then click the name of the agent pool you want to manage.
+
+1. Click **Revoke Token** for the token you want to revoke.
+
+1. Click **Yes, delete token** to confirm.
+
+## Delete an agent pool
+
+~> **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 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.
+
+
+## View agent statuses
+
+To view agent statuses, go to your organization's settings and click **Agents**. The **Agents** page appears, containing a list of agents and their corresponding statuses. An agent can have one of the following statuses:
+
+- **Idle**: The agent is running normally and waiting for jobs to be available.
+- **Busy**: The agent is running normally and currently executing a job.
+- **Unknown**: The agent has not reported any status for an unexpected period of time. The agent may yet recover if the agent's situation is temporary, such as a short-lived network partition.
+- **Errored**: The agent encountered an unrecoverable error or has been in an Unknown state for long enough that HCP Terraform considers it errored. This status may indicate that something interrupted the agent process, the process crashed, a permanent network partition exists, or another similar problem. If the agent was in the process of running an operation (such as a plan or apply), the agent marks that operation as errored. If the current agent process recovers, it exits immediately.
+- **Exited**: The agent exited normally and successfully informed Terraform of it doing so.
+
+## Agent capacity usage
+
+Refer to [HCP Terraform pricing](https://www.hashicorp.com/products/terraform/pricing) for more information about HCP Terraform Agents.
+
+Agents count towards the organization's purchased agent capacity if they are in the **Idle**, **Busy**, or **Unknown** state. Agents that are in the **Errored** or **Exited** state do not count towards the organization's total agent capacity.
+
+Agents in the **Unknown** state continue to count against the organization's total agent allowance, as this status is typically an indicator of a temporary communication issue between the agent and HCP Terraform. **Unknown** agents that do not respond after a period of 5 minutes automatically transition to an **Errored** state, at which point they do not count against the agent allowance.
+
+Agents may have an **Unknown** status if they terminate without gracefully exiting. Agents should always be shut down according to the [Stop the Agent](/terraform/cloud-docs/agents/agents#stop-the-agent) section to allow them to deregister from HCP Terraform. To minimize **Unknown** agent statuses, we strongly recommend configuring any process supervisor, application scheduler, or other runtime manager to follow this procedure.
+
+You can deregister agents that are **Unknown**, **Errored**, or **Exited** through either the **Organization Settings > Agents** page or through the [Agent API](/terraform/cloud-docs/api-docs/agents#delete-an-agent). Deregistered agents no longer appear in the settings page or count against the organization's agent allowance.
+
+## Change the agent pool architecture
+
+All agents in a pool must have the same architecture, which is determined by the first agent to register. If you need to change the architecture of the agent pool, such as switching from x86 to ARM64, you can complete the following steps:
+
+1. Spin down all existing agents in the pool so that no agents are registered.
+1. Spin up and register an agent of the desired architecture.
+
+This agent pool will require subsequent registered agents to have the same architecture.