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 or environment 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

  • 201 Created –

    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