Skip to content

Latest commit

 

History

History
146 lines (111 loc) · 5.4 KB

installation.md

File metadata and controls

146 lines (111 loc) · 5.4 KB

Installation

Requirements

Deploy with Helm

You'll need Helm version v3.8.0 or newer since we're using Helm's support for OCI-based registries.

Inline configuration

The simplest way to get up and running is by deploying our Helm chart with an inline configuration:

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 graphqlToken=<Buildkite GraphQL-enabled API Access Token> \
    --set config.org=<Buildkite Org Slug> \
    --set config.cluster-uuid=<Buildkite Cluster UUID> \
    --set-json='config.tags=["queue=kubernetes"]'

Configuration values YAML file

Create a YAML file with the following values:

# values.yml
agentToken: <Buildkite Cluster Agent Token>
graphqlToken: <Buildkite GraphQL-enabled API Access Token>
config:
  org: <Buildkite Org Slug>
  cluster-uuid: <Buildkite Cluster UUID>
  tags:
    - queue=kubernetes

Now deploy the Helm chart, referencing the configuration values YAML file:

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 will:

  • Create a Kubernetes deployment and install the agent-stack-k8s controller as a Pod running in the buildkite Namespace
    • The buildkite Namespace is created if it does not already exist in the Kubernetes cluster
  • The controller will use the provided graphqlToken to query the Buildkite GraphQL API looking for jobs:
    • In your Organization (config.org)
    • Assigned to the kubernetes Queue in your Cluster (config.cluster-uuid)

How to find a Buildkite Cluster's UUID

To find the UUID of a Cluster:

  • Go to the Clusters page
  • Click on the Cluster containing your Cluster Queue
  • Click on "Settings"
  • The UUID of the Cluster UUID will shown under "GraphQL API Integration"

Store Buildkite tokens in Kubernetes Secret

If you would prefer to store your Agent Token and GraphQL API Access Token as a Kubernetes Secret to be referenced by the agent-stack-k8s controller. Start by converting the tokens to base64-encoded strings:

echo -n <Buildkite Cluster Agent Token> | base64
echo -n <Buildkite GraphQL-enabled API Access Token> | base64

Now create a Kubernetes Secret containing both of the base64-encoded tokens:

kubectl create secret generic <secret-name> \
  --from-literal=BUILDKITE_AGENT_TOKEN=<base64 encoded Buildkite Cluster Agent Token> \
  --from-literal=BUILDKITE_TOKEN=<base64 encoded Buildkite GraphQL-enabled API Access Token>

This Kubernetes Secret name can be provided to the controller with the agentStackSecret option, replacing both agentToken and graphqlToken options. You can then reference your Kubernetes Secret by name during Helm chart deployments with inline configuration:

helm upgrade --install agent-stack-k8s oci://ghcr.io/buildkite/helm/agent-stack-k8s \
    --namespace buildkite \
    --create-namespace \
    --set agentStackSecret=<Kubernetes Secret name> \
    --set config.org=<Buildkite Org Slug> \
    --set config.cluster-uuid=<Buildkite Cluster UUID> \
    --set-json='config.tags=["queue=kubernetes"]'

Or with your configuration values YAML file:

# values.yml
agentStackSecret: <Kubernetes Secret name>
config:
  org: <Buildkite Org Slug>
  cluster-uuid: <Buildkite Cluster UUID>
  tags:
    - queue=kubernetes

Other installation methods

You can also use this chart as a dependency:

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

You can also use this chart as a Helm template:

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

Latest and previous agent-stack-k8s versions (with digests) can be found under Releases.

Controller configuration

Detailed configuration options can be found under Controller Configuration

Running builds

After the agent-stack-k8s Kubernetes controller has been configured and deployed, you are ready to run a Buildkite build.