Clusters

A collection of common tasks with clusters using the GraphQL API.

You can test out the Buildkite GraphQL API using the Buildkite GraphQL console. This includes built-in documentation under its Documentation tab.

List clusters

Get the first 10 clusters and their information for an organization:

query getClusters {
  organization(slug: "organization-slug") {
    clusters(first: 10) {
      edges {
        node {
          id
          uuid
          color
          description
        }
      }
    }
  }
}

List queues

Get the first 10 cluster queues for a particular cluster, specifying the clusters' UUID as the id argument of the cluster query:

query getQueues {
  organization(slug: "organization-slug") {
    cluster(id: "cluster-uuid") {
      queues(first: 10) {
        edges {
          node {
            id
            uuid
            key
            description
          }
        }
      }
    }
  }
}

List agent tokens

Get the first 10 agent tokens for a particular cluster, specifying the clusters' UUID as the id argument of the cluster query:

query getAgentTokens {
  organization(slug: "organization-slug") {
    cluster(id: "cluster-uuid") {
      agentTokens(first: 10){
        edges{
          node{
            id
            uuid
            description
            allowedIpAddresses
          }
        }
      }
    }
  }
}

Cluster token field deprecation

The token field of the ClusterToken object has been deprecated to improve security. Please use the tokenValue field from the ClusterAgentTokenCreatePayload object instead after creating a token.

Create agent token with an expiration date

Create an agent token with an expiration date. The expiration date is displayed in the Buildkite interface and cannot be changed using another Buildkite API call.

mutation createToken {
  clusterAgentTokenCreate(input: {
    organizationId: "organization-id",
    description: "A token with an expiration date",
    clusterId:"cluster-id",
    expiresAt: "2026-01-01T00:00:00Z"
  }) {
    tokenValue
  }
}

Revoke an agent token

First, get the agent token's ID from your list of agent tokens, followed by your Buildkite organization's ID. Then, use these ID values to revoke the agent token:

mutation revokeClusterAgentToken {
  clusterAgentTokenRevoke(input: {
    id: "agent-token-id"
    organizationId: "organization-id"
    }) {
    clientMutationId
    deletedClusterAgentTokenId
  }
}

Create a self-hosted queue

Create a new self-hosted queue in a cluster, which are queues created for agents that you host yourself.

mutation {
  clusterQueueCreate(input: {
    organizationId: "organization-id",
    clusterId: "cluster-id",
    key: "default",
    description: "The default queue for this cluster."
  }) {
    clusterQueue {
      id
      uuid
      key
      description
      hosted
      createdBy {
        id
        uuid
        name
      }
      cluster {
        id
        uuid
        name
      }
    }
  }
}

Create a Buildkite hosted queue

Learn more about how to create a Buildkite hosted queue in Create a Buildkite hosted queue of the Hosted agents page of this cookbook.

Update a queue

Update an existing queue.

mutation {
  clusterQueueUpdate(input: {
    organizationId: "organization-id",
    id: "cluster-id",
    description: "The default queue for this cluster, but this time with a modified description.",
  }) {
    clusterQueue {
      id
      uuid
      key
      description
      hosted
      createdBy {
        id
        uuid
        name
      }
      cluster {
        id
        uuid
        name
      }
    }
  }
}

Learn more about how to update a Buildkite hosted queue's instance shape in Change the instance shape of a Buildkite hosted queue's agents of the Hosted agents page of this cookbook.

Delete a queue

Deletes an existing queue using the queue's ID.

mutation {
  clusterQueueDelete(input: {
    organizationId: "organization-id",
    id: "queue-id"
  }) {
    deletedClusterQueueId
  }
}

List jobs in a particular queue

To get jobs within a particular queue of a cluster, use the clusterQueue argument of the jobs query, passing in the ID of the queue to filter jobs from:

query getQueueJobs {
  organization(slug: "organization-slug") {
    jobs(first: 10, clusterQueue: "cluster-queue-id") {
      edges {
        node {
          ... on JobTypeCommand {
            id
            state
            label
            url
            build {
              number
            }
            pipeline {
              name
            }
          }
        }
      }
    }
  }
}

To obtain jobs in specific states within a particular queue of a cluster, specify the queues' ID with the clusterQueue argument and one or more JobStates with the state argument in the jobs query:

query getQueueJobsByJobState {
  organization(slug: "organization-slug") {
    jobs(
      first: 10,
      clusterQueue: "cluster-queue-id",
      state: [WAITING, BLOCKED]
    ){
      edges {
        node {
          ... on JobTypeCommand {
            id
            state
            label
            url
            build {
              number
            }
            pipeline {
              name
            }
          }
        }
      }
    }
  }
}

List agents in a cluster

Get the first 10 agents within a cluster, use the cluster argument of the agents query, passing in the ID of the cluster:

query getClusterAgents {
   organization(slug:"organization-slug") {
    agents(first: 10, cluster: "cluster-id") {
      edges {
        node {
          name
          hostname
          version
          clusterQueue{
            uuid
            id
          }
        }
      }
    }
  }
}

List agents in a queue

Get the first 10 agents in a particular queue of a cluster, specifying the clusterQueue argument of the agents query, passing in the ID of the cluster queue:

query getQueueAgents {
   organization(slug:"organization-slug") {
    agents(first: 10, clusterQueue: "cluster-queue-id") {
      edges {
        node {
          name
          hostname
          version
          id
          clusterQueue{
            id
            uuid
          }
        }
      }
    }
  }
}

Associate a pipeline with a cluster

First, get the Cluster ID you want to associate the Pipeline with. Second, get the Pipeline's ID. Then, use the IDs to archive the pipelines:

mutation AssociatePipelineWithCluster {
  pipelineUpdate(input:{id: "pipeline-id" clusterId: "cluster-id"}) {
    pipeline {
      cluster {
        name
        id
      }
    }
  }
}