Introduction
This document provides instructions for deleting an Agent to free up agent capacity.
Use Case
Agents are considered active and count towards the organization’s purchased agent capacity if they are in the Idle, Busy, or Unknown state. Agents which are in the Errored or Exited state do not count towards the organization’s total agent capacity.
Agents in the Unknown state continue to be counted 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 which do not respond after a period of 2 hours will automatically transition to an Errored state, at which point they will not count against the agent allowance.
Agents may also have an Unknown status if they are terminated without exiting gracefully. Agents should always be shut down according to the Stopping the Agent documentation to allow them to deregister from Terraform Cloud. We strongly recommend ensuring that any process supervisor, application scheduler, or other runtime manager is configured to follow this procedure to minimize Unknown agent statuses.
It is possible to delete the Agent to release the slot it occupies prior to the 2 hour transition window. Note that Agents must have a status of Unknown, Errored, or Exited before being deleted.
Procedure
-
Locate the Agent Pool ID that you wish to adjust the status for using the Locate the Agent Pool ID API endpoint.
Sample Request:
curl \ --header "Authorization: Bearer $TOKEN" \ --header "Content-Type: application/vnd.api+json" \ --request GET \ https://app.terraform.io/api/v2/organizations/$ORGANIZATION/agent-pools -
Once the Agent pool ID has been located, use the List the Agents API endpoint to list all Agents under the Agent pool.
Sample Request:
curl \ --header "Authorization: Bearer $TOKEN" \ --header "Content-Type: application/vnd.api+json" \ --request GET \ https://app.terraform.io/api/v2/agent-pools/$AGENT_POOL_ID/agents -
Using the Agent ID gathered from the previous call, use the Delete an Agent API endpoint to delete the agent.
Sample Request:
curl \ --header "Authorization: Bearer $TOKEN" \ --request DELETE \ https://app.terraform.io/api/v2/agents/$AGENT_ID
Additional Information
For more information about Terraform Cloud Agents and API endpoints please visit: