Update Docs - Remove Screenshots, Reorganize content, Fix style concerns

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

@@ -3,8 +3,11 @@
  "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": "Logging", "path": "logging" },
  { "title": "Telemetry", "path": "telemetry" },
- { "title": "Monitoring", "path": "monitoring" },
- { "title": "Hooks", "path": "hooks" },
  { "title": "Changelog", "path": "changelog" }
 ]

website/docs/cloud-docs/agents/agent-pools.mdx

@@ -0,0 +1,136 @@
+---
+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](/cloud-docs/workspaces/settings#execution-mode) to use an agent pool.
+
+Refer to [Permissions](/cloud-docs/users-teams-organizations/permissions) in the Terraform Cloud documentation for details.
+
+[permissions-citation]: #intentionally-unused---keep-for-maintainers
+
+## Security Considerations
+
+!> **Warning:** We recommend carefully considering the implications of enabling agents within an organization and restricting organization access to trusted parties.
+
+Any workspace owner may configure their workspace to target the organization's agents. This action may allow a malicious workspace to access sensitive data on the host running the agent.
+
+## 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](/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. Click **Settings** and then **Agents**. A list of agent pools for the organization appears.
+
+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](/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](/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](/cloud-docs/run/states#1-the-pending-stage).
+1. [Lock the workspace](/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](/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
+
+The number of agents you can deploy depends on the number of concurrent runs allowed in your organization. Agents are available in the [Terraform Cloud Business Tier](https://www.hashicorp.com/products/terraform/pricing).
+
+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](/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.
+

website/docs/cloud-docs/agents/agents.mdx

@@ -0,0 +1,101 @@
+---
+page_title: Terraform Cloud Agents - Install and Run Agents - Terraform Cloud and Terraform Enterprise
+description: >-
+ Install, configure, and run agents on your own infrastructure.
+---
+
+# Install and Run Agents
+
+The agent software runs on your own infrastructure. The token you provide when starting the agent assigns it to a Terraform Cloud [agent pool](/cloud-docs/agents/agent-pools).
+
+## Operational Considerations
+
+Agents do not guarantee a clean working environment per Terraform execution. Each execution occurs in its own temporary directory with a clean environment, but references to absolute file paths or other machine state may cause interference between Terraform executions. We strongly recommend that you write your Terraform code to be stateless and idempotent. You may also want to consider using [single-execution mode](#optional-configuration-single-execution-mode) to ensure your agent only runs a single workload.
+
+### Run Multiple Agents
+
+You may choose to run multiple agents within your network, up to the organization's purchased agent limit. If there are multiple agents available within an organization, Terraform Cloud selects the first available agent within the target pool.
+
+Each agent process runs a single Terraform run at a time. Multiple agent processes can be concurrently run on a single instance, license limit permitting.
+
+### Resilience
+
+The agent distributes as a standalone binary that runs on any supported system. By default, the agent runs in the foreground as a long-running process that continuously polls for workloads from Terraform Cloud. An agent process may terminate unexpectedly due to stopping the process forcefully, power cycling the host machine, and other methods. We strongly recommend pairing the agent with a process supervisor to ensure that it automatically restarts in case of an error.
+
+## Download and Install the Agent
+
+1. Download the latest [agent release](https://releases.hashicorp.com/tfc-agent/), the associated checksum file (.SHA256sums), and the checksum signature (.sig).
+1. Verify the integrity of the downloaded archive, as well as the signature of the `SHA256SUMS` file using the instructions available on [HashiCorp's security page](https://www.hashicorp.com/security).
+1. Extract the release archive. The `unzip` utility is available on most Linux distributions, and you can invoke it by running `unzip <archive file>`. The `unzip` command extracts two individual binaries (`tfc-agent` and `tfc-agent-core`). These binaries must reside in the same directory for the agent to function properly.
+
+### Updates
+
+By default, the agent automatically updates itself to the latest minor version. Administrators must update the host operating system and all other installed software.
+
+To customize this update behavior, pass the flag `-auto-update` or set the environment variable `TFC_AGENT_AUTO_UPDATE` to one of the following settings.
+
+| Update Setting | Behavior |
+| -------------- | ------------------------------------------------------------------------------------------------------------ |
+| `minor` | Matches the default behavior, automatically updates the agent to the latest minor version. |
+| `patch` | The agent only updates to the newest patch version, new minor versions require a manual update. |
+| `disabled` | Disables automatic updates, all updates are manual.
+
+## Start the Agent
+
+To start the agent and connect it to a Terraform Cloud agent pool:
+
+1. Retrieve the [token](/cloud-docs/agents/agent-pools#create-an-agent-pool) from the Terraform Cloud agent pool you want to use.
+1. Set the `TFC_AGENT_TOKEN` environment variable.
+1. (Optional) Set the `TFC_AGENT_NAME` environment variable. This name is for your reference only. The agent ID appears in logs and API requests.
+
+```
+export TFC_AGENT_TOKEN=your-token
+export TFC_AGENT_NAME=your-agent-name
+./tfc-agent
+```
+Once complete, your agent and its status appear on the **Agents** page in the Terraform Cloud UI. Workspaces can now use this agent pool for runs. Refer to [Configure Workspaces to Use the Agent](/cloud-docs/agents/agent-pools#configure-workspaces-to-use-the-agent) for details.
+
+### Optional Configuration: Run an Agent Using Docker
+
+Alternatively, you can use our official agent Docker container to run the agent.
+
+```
+docker pull hashicorp/tfc-agent:latest
+docker run -e TFC_AGENT_TOKEN=your-token -e TFC_AGENT_NAME=your-agent-name hashicorp/tfc-agent
+```
+
+This Docker image executes the `tfc-agent` process as the non-root `tfc-agent` user. For some workflows, such as workflows requiring the ability to install software using `apt-get` during `local-exec` scripts, you may need to build a customized version of the agent Docker image for your internal use.
+
+```Dockerfile
+FROM hashicorp/tfc-agent:latest
+
+USER root
+
+# Install sudo. The container runs as a non-root user, but people may rely on
+# the ability to apt-get install things.
+RUN apt-get -y install sudo
+
+# Permit tfc-agent to use sudo apt-get commands.
+RUN echo 'tfc-agent ALL=NOPASSWD: /usr/bin/apt-get , /usr/bin/apt' >> /etc/sudoers.d/50-tfc-agent
+
+USER tfc-agent
+```
+
+An image customized in this way permits installation of additional software via sudo apt-get.
+
+### Optional Configuration: Single-Execution Mode
+
+You can also configure the agent to run in single-execution mode, which ensures that the agent only runs a single workload, then terminates. You can use this configuration in combination with Docker and a process supervisor to ensure a clean working environment for every Terraform run.
+
+To use single-execution mode, start the agent with the `-single` command line argument.
+
+## Stop the Agent
+
+~> **Important:** We strongly recommend that you only terminate the agent using one of these methods. Abruptly terminating an agent by forcefully stopping the process or power cycling the host does not let the agent deregister and results in an **Unknown** agent status. Abrupt termination may cause further capacity issues. Refer to [capacity issues](/cloud-docs/agents/agent-pools#agent-capacity-usage) for details.
+
+The agent maintains a registration and a liveness indicator within Terraform Cloud during the entire course of its runtime. When an agent retires, it must deregister itself from Terraform Cloud. The agent deregisters automatically as part of its shutdown procedure in the following scenarios:
+
+- You enter `Ctrl-C` in an interactive terminal.
+- The agent process ID receives one of `SIGINT`, `SIGTERM`, or `SIGQUIT`. It is important to send only one signal. The agent interprets a second signal as forceful termination signal exits immediately.
+
+After initiating a graceful shutdown by either of these methods, the terminal user or parent program should wait for the agent to exit. The amount of time this exit takes depends on the agent's current workload. The agent waits for any current operations to complete before deregistering and exiting.