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 to use an agent pool.

Refer to Permissions in the Terraform Cloud documentation for details.

Create an Agent Pool

To create an agent pool:

1. Go to your organization's settings, click Agents, and then click Create agent pool.

2. Enter an Agent Pool Name, and then click Continue. Terraform Cloud uses this name to distinguish agent pools in a workspace's settings.

3. Enter a token Description, and then click Create Token.

4. 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.

5. Click Finish.

To connect an agent to this pool, 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.

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.

2. Click the name of the pool you want to update.

3. Click Grant access to specific workspaces. A menu opens where you can search for workspaces within this organization.

4. Type in the search field to find available workspaces and select the workspaces that should have access to the agent pool.

5. 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 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.
2. Wait for the workspace to complete any runs that are no longer in the pending stage.
3. Lock the workspace 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.
2. Select Agent as the execution mode, and select the agent pool this workspace should use.
3. 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.

2. Click Revoke Token for the token you want to revoke.

3. Click Yes, delete token to confirm.

Delete an Agent Pool

To delete an agent pool:

1. Wait for all associated workspaces to complete all in progress runs.
2. Remove the agent pool from all associated workspaces.
3. Navigate to your organization's settings, click Agents, and then click the name of the agent pool you want to delete.
4. Click Delete agent pool.
5. 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.

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 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. Deregistered agents no longer appear in the settings page or count against the organization's agent allowance.