Installation

Before proceeding, ensure that you have met the prerequisites for the Buildkite Agent Stack for Kubernetes controller.

The recommended way to install the Buildkite Agent Stack for Kubernetes controller is to deploy a Helm chart by running the following command with your appropriate configuration values:

helm upgrade --install agent-stack-k8s oci://ghcr.io/buildkite/helm/agent-stack-k8s \
    --namespace buildkite \
    --create-namespace \
    --set agentToken=<buildkite-cluster-agent-token> \
    --set-json='config.tags=["queue=kubernetes"]'

Versions 0.27.0 and earlier of the Agent Stack for Kubernetes controller also requires you to specify a Buildkite API access token with the GraphQL scope enabled, using the argument: --set graphqlToken=<buildkite-api-access-token-with-graphql-scope>

Alternatively, you can place these configuration values into a YAML configuration file by creating the YAML file in this format:

# values.yml
agentToken: "<buildkite-cluster-agent-token>"
config:
  tags:
    - queue=kubernetes

Versions 0.27.0 and earlier of the Agent Stack for Kubernetes controller also requires you to specify a Buildkite API access token with the GraphQL scope enabled, the organization slug, and the cluster UUID, as additional top-level configuration. For example, in the values.yml file:

graphqlToken: "<buildkite-api-access-token-with-graphql-scope>"config:
  org: "<buildkite-organization-slug>"
  cluster-uuid: "<buildkite-cluster-uuid>"

To find the Buildkite cluster UUID from the Buildkite interface:

Select Agents in the global navigation to access your Buildkite organization's Clusters page.

Select the cluster containing your configured queue.

Select Settings.

On the Cluster Settings page, scroll down to the GraphQL API Integration section and your Buildkite cluster's UUID is shown as the id parameter value.

Next, deploy the Helm chart, referencing the configuration values in the YAML file you've created:

helm upgrade --install agent-stack-k8s oci://ghcr.io/buildkite/helm/agent-stack-k8s \
    --namespace buildkite \
    --create-namespace \
    --values values.yml

Both of these deployment methods:

Create a Kubernetes deployment in the buildkite namespace with a single Pod containing the controller container.
- The buildkite namespace is created if it does not already exist in the Kubernetes cluster.
Use the provided agentToken to query the Buildkite Agent API looking for jobs:
- In your Buildkite organization (associated with the agentToken)
- Assigned to the kubernetes queue in your Buildkite cluster (associated with the agentToken)

Storing Buildkite tokens in a Kubernetes Secret

If you prefer to self-manage a Kubernetes Secret containing the agent token instead of allowing the Helm chart to create a secret automatically, the Buildkite Agent Stack for Kubernetes controller can reference a custom secret.

Here is how a custom secret can be created:

kubectl create namespace buildkite
kubectl create secret generic <kubernetes-secret-name> -n buildkite \
  --from-literal=BUILDKITE_AGENT_TOKEN='<buildkite-cluster-agent-token>'

This Kubernetes Secret name can be provided to the controller with the agentStackSecret option, replacing the agentToken option. You can then reference your Kubernetes Secret by name during Helm chart deployments.

To reference your Kubernetes Secret when setting up the Buildkite Agent Stack for Kubernetes controller, run the Helm chart deployment command with your appropriate configuration values:

helm upgrade --install agent-stack-k8s oci://ghcr.io/buildkite/helm/agent-stack-k8s \
    --namespace buildkite \
    --create-namespace \
    --set agentStackSecret=<kubernetes-secret-name> \
    --set-json='config.tags=["queue=kubernetes"]'

Alternatively, to reference your Kubernetes Secret with your configuration values in a YAML file by creating the YAML file in this format:

# values.yml
agentStackSecret: "<kubernetes-secret-name>"
config:
  tags:
    - queue=kubernetes

Next, deploy the Helm chart, referencing the configuration values in the YAML file you've created:

helm upgrade --install agent-stack-k8s oci://ghcr.io/buildkite/helm/agent-stack-k8s \
    --namespace buildkite \
    --create-namespace \
    --values values.yml

Other installation methods

You can also use the following chart as a dependency:

dependencies:
- name: agent-stack-k8s
  version: "0.28.0"
  repository: "oci://ghcr.io/buildkite/helm"

Alternatively, you can also use this chart as a Helm template:

helm template oci://ghcr.io/buildkite/helm/agent-stack-k8s --values values.yaml

The latest and earlier versions (with digests) of the Buildkite Agent Stack for Kubernetes controller can be found under Releases in the Buildkite Agent Stack for Kubernetes controller GitHub repository.

Controller configuration

Learn more about detailed configuration options in Controller configuration.

Running builds

After the Buildkite Agent Stack for Kubernetes controller has been configured and deployed, you are ready to run a Buildkite build.