Agent Pools¶
The AgentPool resource¶
With the agent pool resource you can manage a pool of self-hosted agents
A workspace may be configured to use an agent pool to execute terraform runs. Agents could be hosted on a physical or virtual machines within the customer’s network.
Key path
Description
type* (string)
Available values:agent-pools
id (string)
attributes.name* (string)
The name of the agent pool. This must be unique within a Scalr scope (e.g. account or environment).
relationships.account (object)
The account the agent pool belongs to.
relationships.account.data.type* (string)
Available values:accounts
relationships.account.data.id* (string)
relationships.agents (object)
The list of agents connected to the pool.
relationships.agents.data* (array)
relationships.environment (object)
The environment the agent pool belongs to.
relationships.environment.data.type* (string)
Available values:environments
relationships.environment.data.id* (string)
relationships.workspaces (object)
The list of workspaces attached to the pool. Can be used to bulk link/unlink workspaces.
relationships.workspaces.data* (array)
links.self (string)
List Agent Pools¶
-
GET
/api/iacp/v3/agent-pools
¶ This endpoint returns a list of agent pools by various filters.
- Query Parameters
filter[agent-pool] (string) – The id of the agent pool.
filter[name] (string) – The agent pool name.
filter[account] (string) – The account filter.
filter[environment] (string) – The environment filter.
page[number] (string) – Page number
page[size] (string) – Page size
include (array) – The comma-separated list of relationship paths. (Available values:
account
,agents
,environment
,workspaces
)sort (array) – The comma-separated list of attributes. (Available values:
account
,environment
,name
)
Example Request:
GET /api/iacp/v3/agent-pools HTTP/1.1 Host: my.scalr.io Prefer: profile=preview
- Status Codes
200 OK – Success.
404 Not Found – User not authorized to perform this action.
4XX – Client error.
5XX – Server error.
Create an Agent Pool¶
-
POST
/api/iacp/v3/agent-pools
¶ Create a new agent pool resource.
Agent pools can be created at the
account
orenvironment
scope. The scope must be defined as part of the agent pool creation. If a pool is created at the account scope, all environments and workspaces within those environments will have access to use the pool. If a pool is created at the environment scope, then only the workspaces in that environment can use that pool.The typical flow for configuring a new agent pool involves the following operations:
Create an agent pool
Create an access token for the pool. The pool token is needed by an agent in order to join the agent pool. During the agent<->server handshake phase, the API server will generate a unique session token for each agent which will be used for all communication with the API server.
Install/Configure an agent on the customer’s network.
- Query Parameters
include (array) – The comma-separated list of relationship paths. (Available values:
account
,agents
,environment
,workspaces
)
Request body:
Key path
Description
data.type* (string)
Available values:agent-pools
data.id (string)
data.attributes.name* (string)
The name of the agent pool. This must be unique within a Scalr scope (e.g. account or environment).
data.relationships.account (object)
The account the agent pool belongs to.
data.relationships.account.data.type* (string)
Available values:accounts
data.relationships.account.data.id* (string)
data.relationships.environment (object)
The environment the agent pool belongs to.
data.relationships.environment.data.type* (string)
Available values:environments
data.relationships.environment.data.id* (string)
data.relationships.workspaces (object)
The list of workspaces attached to the pool. Can be used to bulk link/unlink workspaces.
data.relationships.workspaces.data* (array)
Create an agent pool at the environment scope:
POST /api/iacp/v3/agent-pools HTTP/1.1 Host: my.scalr.io Content-Type: application/vnd.api+json Prefer: profile=preview { "data": { "type": "agent-pools", "attributes": { "name": "my-pool" }, "relationships": { "environment": { "data": { "type": "environments", "id": "env-svrcnchebt61e30" } } } } }
- Status Codes
Successfully created.
Example Respone:
HTTP/1.1 201 Created Content-Type: application/vnd.api+json Preference-Applied: profile=preview { "data": { "attributes": { "name": "my-pool" }, "id": "apool-tkacmbjoemheukg", "links": { "self": "https://my.scalr.io/api/iacp/v3/agent-pools/apool-tkacmbjoemheukg" }, "relationships": { "account": { "data": { "id": "acc-svrcncgh453bi8g", "type": "accounts" } }, "agents": null, "environment": { "data": { "id": "env-svrcnchebt61e30", "type": "environments" } }, "type": "agent-pools" }, "included": null, "meta": null }
403 Forbidden – User unauthorized to perform this action.
409 Conflict – Quota exceeded error.
422 Unprocessable Entity – Malformed request body (missing attributes, wrong types, etc.).
4XX – Client error.
5XX – Server error.
Delete an Agent Pool¶
-
DELETE
/api/iacp/v3/agent-pools/{agent_pool}
¶ This endpoint deletes an agent pool by ID.
- Parameters
agent_pool (string) – The ID of the agent pool to be deleted.
- Status Codes
204 No Content – Successfully deleted.
403 Forbidden – User unauthorized to perform this action.
404 Not Found – Agent pool not found or user unauthorized.
409 Conflict – Can’t be deleted. Has busy agents.
4XX – Client error.
5XX – Server error.
Get an Agent Pool¶
-
GET
/api/iacp/v3/agent-pools/{agent_pool}
¶ Show details of a specific agent pool.
- Parameters
agent_pool (string) – The ID of the agent pool to show.
- Query Parameters
include (array) – The comma-separated list of relationship paths. (Available values:
account
,agents
,environment
,workspaces
)
Example Request:
GET /api/iacp/v3/agent-pools/{agent_pool} HTTP/1.1 Host: my.scalr.io Prefer: profile=preview
- Status Codes
200 OK – Success.
404 Not Found – User not authorized or agent pool not found.
4XX – Client error.
5XX – Server error.
Update an Agent Pool¶
-
PATCH
/api/iacp/v3/agent-pools/{agent_pool}
¶ This endpoint updates an agent pool by ID.
- Parameters
agent_pool (string) – The ID of the agent pool to be updated.
- Query Parameters
include (array) – The comma-separated list of relationship paths. (Available values:
account
,agents
,environment
,workspaces
)
Request body:
Key path
Description
data.type* (string)
Available values:agent-pools
data.id (string)
data.attributes.name* (string)
The name of the agent pool. This must be unique within a Scalr scope (e.g. account or environment).
data.relationships.account (object)
The account the agent pool belongs to.
data.relationships.account.data.type* (string)
Available values:accounts
data.relationships.account.data.id* (string)
data.relationships.environment (object)
The environment the agent pool belongs to.
data.relationships.environment.data.type* (string)
Available values:environments
data.relationships.environment.data.id* (string)
data.relationships.workspaces (object)
The list of workspaces attached to the pool. Can be used to bulk link/unlink workspaces.
data.relationships.workspaces.data* (array)
Bulk link the agent pool to multiple workspaces:
PATCH /api/iacp/v3/agent-pools/{agent_pool} HTTP/1.1 Host: my.scalr.io Content-Type: application/vnd.api+json Prefer: profile=preview { "data": { "type": "agent-pools", "id": "apool-tkacmbjoemheukg", "relationships": { "workspaces": { "data": [ {"type": "workspaces", "id": "ws-tkklps8s31vseto"}, {"type": "workspaces", "id": "ws-tkklq6v7im56cd0"}, {"type": "workspaces", "id": "ws-tkklqi19gvk7jc0"} ] } } } }
- Status Codes
200 OK – Successfully updated.
403 Forbidden – User unauthorized to perform this action.
404 Not Found – User not authorized or agent pool not found.
409 Conflict – Quota exceeded error.
422 Unprocessable Entity – Malformed request body (missing attributes, wrong types, etc.).
4XX – Client error.
5XX – Server error.