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.

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 HCP Terraform 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. HCP Terraform 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 HCP Terraform agent pool, and HCP Terraform does not display the token again after this step.

5. Click Finish.

To connect an agent to this pool, configure and start an agent using the official Docker image. Alternatively, configure and start an agent using the binary then provide then agent with your agent pool's token.

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

Excluding workspaces from an agent pool prevents the specified workspaces from using it.

To exclude a workspace 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.

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

3. Click Grant access to specific projects and workspaces.

4. Click Add exclusions. A menu opens where you can search for workspaces within this organization.

5. Type in the search field to find available workspaces and select the workspaces that should be restricted from accessing the agent pool.

6. Click Save.

Only the specified workspaces will be restricted from accessing the agent pool.

Scope an agent pool to specific projects

You can scope an agent pool to specific projects. Only the selected projects are able to use the agent pool.

To scope an agent pool to specific projects 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 projects and workspaces. A menu opens where you can search for projects within this organization.

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

5. Click Save.

Only the specified projects can use the agent 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.
2. Select Agent as the execution mode, and select the agent pool this project should use.
3. 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.

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.

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.

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 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 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 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. 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.
2. Spin up and register an agent of the desired architecture.

This agent pool will require subsequent registered agents to have the same architecture.