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 ten agent tokens and their scopes for a particular cluster, specifying the cluster's UUID as the id argument of the cluster query:
query getAgentTokens {
organization(slug: "organization-slug") {
id
cluster(id: "cluster-uuid") {
id
agentTokens(first: 10) {
edges {
node {
id
uuid
description
allowedIpAddresses
permissions
allowAllQueues
allowedQueueIds
}
}
}
}
}
}
Use a personal API access token with the graphql scope, shown as Enable GraphQL API Access. Listing agent tokens requires the see_cluster_tokens permission for the cluster. Creating or updating tokens requires manage_cluster; creation also requires see_cluster_tokens.
The agent token mutations below use GraphQL global IDs for the organization, cluster, token, and queues. Use the returned id values, not REST UUIDs. The allowedQueueIds field contains global IDs for ClusterQueue objects. Get queue IDs using List queues.
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.
List cache registries
Get the first ten cache registries for a particular cluster, specifying the cluster's UUID as the id argument of the cluster query:
query getCacheRegistries {
organization(slug: "organization-slug") {
id
cluster(id: "cluster-uuid") {
id
cacheRegistries(first: 10) {
pageInfo {
hasNextPage
endCursor
}
edges {
node {
id
uuid
slug
name
description
}
}
}
}
}
}
Results are ordered by slug. If hasNextPage is true, pass endCursor as the after argument to cacheRegistries to fetch the next page.
Listing and managing cache registries requires organization administrator or cluster maintainer permissions. Use an API access token with the Enable GraphQL API Access permission selected.
The query returns both Relay global IDs (id) and UUIDs (uuid). Use the organization, cluster, and registry id values in the mutations below, not their UUIDs or slugs. Unlike the mutations, organization.cluster(id:) takes the cluster UUID.
This API manages registry metadata and policies, not cache entries or agent save and restore operations. Use the web interface to configure cache stores. To select a cluster's default registry, use the web interface or the REST API's Update a cluster endpoint.
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: "2030-01-01T00:00:00Z"
}) {
tokenValue
clusterAgentToken {
id
permissions
allowAllQueues
allowedQueueIds
}
}
}
Omitting permissions grants all current Agent API permissions. Omitting both queue fields allows all queues in the cluster. Copy tokenValue to secure storage immediately; the API returns this secret only when creating the token.
Create a scoped agent token
Create a token that allows agents to run jobs, access code repositories through the Agent API, and write build metadata on a selected queue:
mutation createScopedAgentToken {
clusterAgentTokenCreate(input: {
organizationId: "organization-id",
clusterId: "cluster-id",
description: "Windows agents",
allowedIpAddresses: "192.0.2.0/24",
permissions: ["run_jobs", "code_repository_access", "write_build_metadata"],
allowAllQueues: false,
allowedQueueIds: ["queue-id"]
}) {
tokenValue
clusterAgentToken {
id
description
allowedIpAddresses
permissions
allowAllQueues
allowedQueueIds
}
}
}
Copy tokenValue to secure storage immediately. Subsequent queries and updates do not return the secret.
Each permission grants only its own actions; run_jobs does not grant the other permissions. See Scoped agent tokens and the available permissions to select the actions your agents need.
- Omit
permissionsto grant all current permissions. An explicit array grants only the supplied permissions, with duplicates removed. An empty array grants no permission-controlled actions. - Omit both queue fields to allow all queues. With
allowAllQueues: false, supplyallowedQueueIdscontaining queues from the same cluster. An empty array then denies all queues. - With
allowAllQueues: true,allowedQueueIdsmust be empty.
Unknown permission names, including read_pipelines and modify_steps, and null permissions are rejected. Invalid permission or queue settings reject the mutation without changing the token. Check the response's errors array even when the HTTP status is 200 OK.
Update a scoped agent token
Use the token's global ID from List agent tokens to replace its permissions and allowed queues:
mutation updateScopedAgentToken {
clusterAgentTokenUpdate(input: {
organizationId: "organization-id",
id: "agent-token-id",
description: "Windows build agents",
allowedIpAddresses: "192.0.2.0/24",
permissions: ["run_jobs", "code_repository_access", "write_build_metadata"],
allowAllQueues: false,
allowedQueueIds: ["queue-id"]
}) {
clusterAgentToken {
id
description
allowedIpAddresses
permissions
allowAllQueues
allowedQueueIds
}
}
}
The description argument is required. Supply the token's existing allowedIpAddresses value to preserve its IP restriction, as shown above. Omitting allowedIpAddresses clears the restriction.
Omit permissions, allowAllQueues, or allowedQueueIds to preserve the corresponding stored value. Supplied permission and queue arrays replace the existing arrays. To switch a restricted token to all queues, send allowAllQueues: true and allowedQueueIds: [] together. Clearing the array while allowAllQueues is false denies all queues.
Saved permission changes take effect on subsequent requests from connected agents and running jobs, without re-registration. Queue changes apply to new registrations, including registrations using previously issued job acquisition tokens, and new stack batch JAT issuance.
Explicit job acquisition also checks current queue bindings. Removing queue access after registration can make the Agent API's /acquire endpoint return 404, including for a JAT-backed agent. Queue edits do not disconnect existing agents or cancel running jobs.
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
}
}
Create a cache registry
Create another cache registry in a cluster, specifying the cluster's ID as the clusterId argument:
mutation createCacheRegistry {
cacheRegistryCreate(input: {
organizationId: "organization-id",
clusterId: "cluster-id",
name: "Build cache",
description: "Compiler output cache"
}) {
cacheRegistry {
id
uuid
slug
name
description
cluster {
id
uuid
}
}
}
}
New registries use agent-managed storage. The cache store can't be set through this API.
Set the policy argument to a JSON-encoded string of the structured policy document described in Configure a cache policy. For example, add this argument to the create input to allow both saves and restores:
policy: "{\"save\":{\"scopes\":{}},\"restore\":{\"scopes\":[{}]},\"rules\":[{\"effect\":\"allow\",\"action\":\"save\"},{\"effect\":\"allow\",\"action\":\"restore\"}]}"
The GraphQL JSON type accepts a JSON-encoded string, not an object literal or authored YAML. The API validates and normalizes the policy. The returned policy field is also a JSON-encoded string, with rule actions normalized to arrays.
When creating a registry, omit policy or set it to null to use the default unrestricted policy.
Update a cache registry
Update an existing cache registry's attributes, specifying the registry's Relay global ID as the id argument. Omitted attributes are left unchanged:
mutation updateCacheRegistry {
cacheRegistryUpdate(input: {
organizationId: "organization-id",
id: "cache-registry-id",
description: "Updated compiler output cache"
}) {
cacheRegistry {
id
uuid
slug
name
description
}
}
}
Supplying policy replaces the entire policy rather than merging its nested properties. Set policy to null to clear it, which denies saves and restores. Unlike creation, updating with null doesn't apply the default unrestricted policy.
Changing name regenerates the registry's slug. Set description, emoji, or color to null to clear them. The registry's UUID and cache store can't be changed through this API.
Delete a cache registry
Delete an existing cache registry using the registry's GraphQL ID:
mutation deleteCacheRegistry {
cacheRegistryDelete(input: {
organizationId: "organization-id",
id: "cache-registry-id"
}) {
deletedCacheRegistryId
}
}
You can't delete a cluster's default cache registry. First, select another default registry in the web interface or with the REST API's Update a cluster endpoint.
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
}
}
}
}