Manage clusters

This page provides instructions for common tasks when managing clusters.

Set up clusters

Follow these instructions when setting up a cluster.

Create a cluster

To create a new cluster:

  1. Navigate to Clusters.
  2. Select Create a Cluster.
  3. Enter a name, description, and emoji.
  4. Select Create Cluster.

Create a queue

When you create your first cluster, it will have an initial default queue.

To create additional queues:

  1. Navigate to the cluster’s Queues.
  2. Select Create a Queue.
  3. Enter a key and description.
  4. Select Create Queue.

Connect agents to a cluster

Agents are associated with a cluster through the cluster’s agent tokens.

To connect an agent:

  1. Navigate to the cluster's Agent tokens.
  2. Select New Token.
  3. Enter a description.
  4. Select Create Token.
  5. Select Copy to Clipboard and save the token somewhere secure.
  6. Select Okay, I'm done!
  7. Use the token with the relevant agents, along with the key from the relevant cluster queue.

You can also create, edit, and revoke other agent tokens from the cluster’s Agent tokens.

Add pipelines to a cluster

Add a pipeline to a cluster to ensure the pipeline’s builds run only on agents connected to that cluster.

To add a pipeline to a cluster:

  1. Navigate to the Pipeline Settings for the pipeline.
  2. Under Cluster Settings, select the relevant cluster.

Add maintainers to a cluster

Only Buildkite administrators or users with the change organization permission can create clusters.

You can assign other users or teams as a cluster’s maintainers to permit them to manage the cluster. Cluster maintainers can:

  • Update or delete the cluster.
  • Manage cluster agent tokens.
  • Add or remove pipelines to the cluster.

To add a maintainer to a cluster:

  1. Navigate to the cluster’s Maintainers.
  2. Select a user or team.
  3. Click Add Maintainer.

Restrict access for a cluster token by IP address

Each cluster token can be locked down so that only agents with an allowed IP address can use them to register.

You can set the Allowed IP Addresses when creating a token, or you can modify existing tokens:

  1. Navigate to the cluster's Agent Tokens.
  2. Select the token to which you wish to restrict access.
  3. Select Edit.
  4. Update the Allowed IP Addresses setting, using space-separated CIDR notation.
  5. Select Save Token.

Modifying the Allowed IP Addresses forcefully disconnects any existing agents with IP addresses outside the updated value. This prevents the completion of any jobs in progress on those agents.

Note the following limitations:

  • This setting does not restrict access to the Metrics API for the given cluster token.
  • There is a maximum of 24 CIDR blocks per agent token.
  • IPv6 is currently not supported.

Migrate to clusters

If you migrate all your existing agents over to clusters, make sure to add all your pipelines to the relevant clusters. Otherwise, any builds for those pipelines will never find agents to run them.

Pause a queue

You can pause a queue to prevent jobs from being dispatched to agents associated with that queue.

To pause a queue:

  1. Navigate to your cluster’s Queues.
  2. Select the queue you wish to pause.
  3. Select Edit.
  4. Under Queue Management, select Pause Queue.
  5. Enter an optional note in the dialog, and confirm that you wish to pause the queue.

    You can use the note to explain why you're pausing the queue. The note will display on the queue page and 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.

Trigger steps do not rely on agents, so they will run unless they have dependencies waiting on the paused queue. The behavior of the jobs they trigger depends on their configuration. If a triggered job targets the paused queue, it will wait until the queue is resumed. If a triggered job does not target the paused queue, it will run as usual.

Select Resume Queue to resume a paused queue. Jobs will resume dispatching to the queue as usual, including any jobs waiting to run.