Terraform docs agents UDR launch

.gitignore

@@ -49,4 +49,5 @@ scripts/algolia/batch-post-records/algoliaRecords.json
 public/assets
 public/content
 app/api/versionMetadata.json
-app/api/docsPathsAllVersions.json
+app/api/docsPathsAllVersions.json
+scripts/test-output/**

CODEOWNERS

@@ -9,3 +9,4 @@
 /content/terraform-plugin-mux @hashicorp/terraform-devex @hashicorp/terraform-education
 /content/terraform-plugin-sdk @hashicorp/terraform-devex @hashicorp/terraform-education
 /content/terraform-plugin-testing @hashicorp/terraform-devex @hashicorp/terraform-education
+/content/terraform-docs-agents @hashicorp/terraform-devex @hashicorp/tfc-agent-core

app/utils/productConfig.mjs

@@ -247,15 +247,6 @@ export const PRODUCT_CONFIG = {
 	// 	websiteDir: 'website',
 	// },
 	// 'terraform-cdk': {
-	// 	/**
-	// 	 * ✅ Initial migration attempt: SEEMS TO WORK
-	// 	 *
-	// 	 * TODO: `terraform-cdk` doesn't seem to have an asset directory.
-	// 	 * Need to confirm this is true across ALL versions... if not,
-	// 	 * need to figure out a workaround to only copy it in some versions,
-	// 	 * without silently ignoring missing assets directories in other contexts.
-	// 	 * Maybe like a `versionsWithoutAssets` array or something?
-	// 	 */
 	// 	assetDir: '',
 	// 	basePaths: ['cdktf'],
 	// 	contentDir: 'docs',
@@ -265,25 +256,25 @@ export const PRODUCT_CONFIG = {
 	// 	versionedDocs: true,
 	// 	websiteDir: 'website',
 	// },
-	// 'terraform-docs-agents': {
-	// 	/**
-	// 	 * 🟢🟢🟡 Initial migration attempt: CONTENT NOT FOUND on older versions
-	// 	 *
-	// 	 * Fails for v1.5.x (and likely earlier) with error:
-	// 	 * `terraform-docs-agents/website/img: No such file or directory`
-	// 	 * This likely indicates that older versions of docs have a different
-	// 	 * directory structure that needs to be accounted for. Need to confirm.
-	// 	 * See note at top of this document on `pages` directories for details.
-	// 	 */
-	// 	assetDir: ['img', 'public/img'],
-	// 	basePaths: ['cloud-docs/agents'],
-	// 	contentDir: 'docs',
-	// 	dataDir: 'data',
-	// 	productSlug: 'terraform',
-	// 	semverCoerce: semver.coerce,
-	// 	versionedDocs: true,
-	// 	websiteDir: 'website',
-	// },
+	'terraform-docs-agents': {
+		/**
+		 * 🟢🟢🟡 Initial migration attempt: CONTENT NOT FOUND on older versions
+		 *
+		 * Fails for v1.5.x (and likely earlier) with error:
+		 * `terraform-docs-agents/website/img: No such file or directory`
+		 * This likely indicates that older versions of docs have a different
+		 * directory structure that needs to be accounted for. Need to confirm.
+		 * See note at top of this document on `pages` directories for details.
+		 */
+		assetDir: ['img', 'public/img', 'img/docs'],
+		basePaths: ['cloud-docs/agents'],
+		contentDir: 'docs',
+		dataDir: 'data',
+		productSlug: 'terraform',
+		semverCoerce: semver.coerce,
+		versionedDocs: true,
+		websiteDir: 'website',
+	},
 	// 'terraform-docs-common': {
 	// 	/**
 	// 	 * ✅ Initial migration attempt: SEEMS TO WORK

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

@@ -0,0 +1,15 @@
+[
+  {
+    "heading": "Terraform Cloud 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": "Telemetry", "path": "telemetry" },
+  { "title": "Logging", "path": "logging" },
+  { "title": "Metrics", "path": "metrics" },
+  { "title": "Tracing", "path": "tracing" },
+  { "title": "Changelog", "path": "changelog" }
+]

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

@@ -0,0 +1,130 @@
+---
+page_title: Terraform Cloud Agents - Managing Agent Pools - Terraform Cloud and Terraform Enterprise
+description: >-
+  Agent pools are groups of one or more agents in Terraform Cloud. Create agent pools and assign them to one or more workspaces.
+---
+
+# Manage Agent Pools
+
+Terraform Cloud organizes agents into pools. Each workspace can specify which agent pool should run its workloads.
+
+## 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.
+
+Refer to [Permissions](/terraform/cloud-docs/users-teams-organizations/permissions) in the Terraform Cloud 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**. Terraform Cloud uses this name to distinguish agent pools in a workspace'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 Terraform Cloud agent pool, and Terraform Cloud does not display the token again after this step.
+
+1. Click **Finish**.
+
+To connect an agent to this pool, [start an agent](/terraform/cloud-docs/agents/agents#start-an-agent) and provide it with the token for this agent pool.
+
+## Scope an Agent Pool to Specific Workspaces
+
+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.
+
+~> **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.
+
+To scope an agent pool to specific workspaces 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. Type in the search field to find available workspaces and select the workspaces that should have access to the agent pool.
+
+1. Click **Save**.
+
+Only the specified workspaces 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. Terraform Cloud may use different agents for the plan and apply operations, depending on agent availability within the 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. 
+
+You should allow active runs in the agent pool to finish before revoking the 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.
+
+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. 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 Terraform Cloud 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 [Terraform Cloud pricing](https://www.hashicorp.com/products/terraform/pricing) for more information about Terraform Cloud 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 Terraform Cloud. **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 [Stopping the Agent](#stopping-the-agent) section to allow them to deregister from Terraform Cloud. 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.
+