Manage queues

This page provides details on how to manage queues within a cluster of your Buildkite organization.

Setting up queues

When a new Buildkite organization is created, along with the automatically created default cluster (named Default cluster), a default queue (named default-queue) within this cluster is also created.

A cluster can be configured with multiple queues, each of which can be used to represent a specific combination of your build/agent infrastructure, based on:

Architecture (x86-64, arm64, Apple silicon, etc.)
Size of agents (small, medium, large)
Type of machine (Mac, Linux, Windows, etc.)

Some example queues might be mac_medium_x86, mac_large_silicon, etc.

Having individual queues according to these breakdowns allows you to scale a set of similar agents, which Buildkite can then report on.

Agent infrastructure

As part of setting up a queue, you can choose between setting up your agents using either hosted or self-hosted infrastructure.

Buildkite provides a hosted infrastructure for your Buildkite Agents, as well as support for self-hosted infrastructure, where you provide the infrastructure that hosts Buildkite Agents.

Creating Buildkite hosted agent queues is currently only supported through the Buildkite interface. It is not possible to create hosted agent queues using the REST or GraphQL APIs.

Create a queue

New queues can be created by a cluster maintainer using the Queues page of a cluster, as well as the REST API's or GraphQL API's create a queue feature.

For these API requests, the cluster ID value submitted in the request is the target cluster the queue will be created in.

When you create a new cluster through the Buildkite interface, this cluster automatically has an initial default queue.

Using the Buildkite interface

To create a new queue using the Buildkite interface:

Select Agents in the global navigation to access the Clusters page.
Select the cluster in which to create the new queue.
On the Queues page, select New Queue to open the Create a new Queue page.
In the Create a key field, enter a unique key for the queue, which can only contain letters, numbers, hyphens, and underscores, as valid characters.
Select the Add description checkbox to enter an optional longer description for the queue. This description appears under the queue's key, which is listed on the Queues page, as well as when viewing the queue's details.
In the Select your agent infrastructure section, select between Hosted or Self hosted for your agent infrastructure.
If you chose Hosted, complete the remaining sub-steps:
1. In the new Configure your hosted agent infrastructure section, select your Machine type (Linux or macOS).
2. If you selected Linux, within Architecture, you can choose between AMD64 (the default and recommended) or ARM64 architectures for the Linux machines running as hosted agents. To switch to ARM64, select Change, followed by ARM64 (AArch64).
3. Select the appropriate Capacity for your hosted agent machine type (Small, Medium or Large). Take note of the additional information provided in the new Hosted agents trial section, which changes based on your selected Capacity.
Select Create Queue.

The new queue's details are displayed, indicating the queue's key and its description (if configured) underneath this key. Select Queues on the interface again to list all configured queues in your cluster.

Using the REST API

To create a new self-hosted agent queue using the REST API, run the following example curl command:

curl -H "Authorization: Bearer $TOKEN" \
  -X POST "https://api.buildkite.com/v2/organizations/{org.slug}/clusters/{cluster.id}/queues" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "mac_large_silicon",
    "description": "The queue for powerful macOS agents running on Apple silicon architecture."
  }'

where:

$TOKEN is an API access token scoped to the relevant Organization and REST API Scopes that your agent needs access to in Buildkite.

{org.slug} can be obtained:
- From the end of your Buildkite URL, after accessing Pipelines in the global navigation of your organization in Buildkite.
- By running the List organizations REST API query to obtain this value from slug in the response. For example:
```
curl -H "Authorization: Bearer $TOKEN" \
  - X GET "https://api.buildkite.com/v2/organizations"
```

{cluster.id} can be obtained:
- From the Cluster Settings page of your target cluster. To do this:
  1. Select Agents (in the global navigation) > the specific cluster > Settings.
  2. Once on the Cluster Settings page, copy the id parameter value from the GraphQL API Integration section, which is the {cluster.id} value.
- By running the List clusters REST API query and obtain this value from the id in the response associated with the name of your target cluster (specified by the name value in the response). For example:
```
curl -H "Authorization: Bearer $TOKEN" \
  - X GET "https://api.buildkite.com/v2/organizations/{org.slug}/clusters"
```

key (required) is displayed on the cluster's Queues pages, and this value can only contain letters, numbers, hyphens, and underscores, as valid characters.
description (optional) is a longer description for the queue, which appears under the queue's key, when listed on the Queues page, as well as when viewing the queue's details.

Using the GraphQL API

To create a new self-hosted agent queue using the GraphQL API, run the following example mutation:

mutation {
  clusterQueueCreate(
    input: {
      organizationId: "organization-id"
      clusterId: "cluster-id"
      key: "mac_large_silicon"
      description: "The queue for powerful macOS agents running on Apple silicon architecture."
    }
  ) {
    clusterQueue {
      id
      uuid
      key
      description
      dispatchPaused
      createdBy {
        id
        uuid
        name
        email
        avatar {
          url
        }
      }
    }
  }
}

where:

organizationId (required) can be obtained:
- From the GraphQL API Integration section of your Organization Settings page, accessed by selecting Settings in the global navigation of your organization in Buildkite.
- By running a getCurrentUsersOrgs GraphQL API query to obtain the organization slugs for the current user's accessible organizations, followed by a getOrgId query, to obtain the organization's id using the organization's slug. For example:
  
  Step 1. Run getCurrentUsersOrgs to obtain the organization slug values in the response for the current user's accessible organizations:
```
query getCurrentUsersOrgs {
  viewer {
    organization {
      edges {
        node {
          name
          slug
        }
      }
    }
  }
}
```
  Step 2. Run getOrgId with the appropriate slug value above to obtain this organization's id in the response:
```
query getOrgId {
  organization(slug: "organization-slug") {
    id
    uuid
    slug
  }
}
```
  Note: The organization-slug value can also be obtained from the end of your Buildkite URL, by selecting Pipelines in the global navigation of your organization in Buildkite.

clusterId (required) can be obtained:
- From the Cluster Settings page of your target cluster. To do this:
  1. Select Agents (in the global navigation) > the specific cluster > Settings.
  2. Once on the Cluster Settings page, copy the cluster parameter value from the GraphQL API Integration section, which is the cluster.id value.
- By running the List clusters GraphQL API query and obtain this value from the id in the response associated with the name of your target cluster (specified by the name value in the response). For example:
```
query getClusters {
  organization(slug: "organization-slug") {
    clusters(first: 10) {
      edges {
        node {
          id
          name
          uuid
          color
          description
        }
      }
    }
  }
}
```

key (required) is displayed on the cluster's Queues pages, and this value can only contain letters, numbers, hyphens, and underscores, as valid characters.
description (optional) is a longer description for the queue, which appears under the queue's key, when listed on the Queues page, as well as when viewing the queue's details.

Pause and resume a queue

You can pause a queue to prevent any jobs of the cluster's pipelines from being dispatched to agents associated with this queue.

Enterprise feature

Queue pausing is only available to Buildkite customers with Pro and Enterprise plans.

To pause a queue:

Select Agents in the global navigation to access the Clusters page.
Select the cluster with the queue to pause.
On the Queues page, select the queue to pause.
On the queue's details page, select Pause Queue.
Enter an optional note in the confirmation dialog, and select Pause Queue to pause the queue.

Note: Use this note to explain why you're pausing the queue. The note will be displayed on the queue's details page and on any affected builds.

Jobs already dispatched to agents in the queue before pausing will continue to run. New jobs that target the paused queue will wait until the queue is resumed.

Since trigger steps do not rely on agents, these steps will run, unless they have dependencies waiting on the paused queue. The behavior of the triggered jobs depends on their configuration:

If a triggered job targets a paused queue, the job will wait until the queue is resumed.
If a triggered job does not target the paused queue, the job will run as usual.

To resume a queue:

Select Agents in the global navigation to access the Clusters page.
Select the cluster with the queue to resume.
On the Queues page, select the queue to resume.
On the queue's details page, select Resume Queue.

Jobs will resume being dispatched to the resumed queue as usual, including any jobs waiting to run.