Running the agent on Kubernetes

Deploy a self-hosted Airplane agent on Kubernetes.

The Airplane agent can be quickly installed on Kubernetes using Helm. When installed, the agent will use Kubernetes APIs to run Airplane tasks and runbooks.

Installation guide

Install Helm

First, install Helm if you haven't yet. On macOS, you can brew install helm. For other operating systems, see the Helm installation docs.

Configure

You'll need the following values:

YOUR_API_TOKEN: generate a new token by running airplane apikeys create <token name> from the Airplane CLI.
YOUR_TEAM_ID: get your team ID via airplane auth info or visit the Team Settings page.

Create a values.yaml configuration file:

yaml
Copied
1
airplane:
2
  apiToken: YOUR_API_TOKEN
3
  teamID: YOUR_TEAM_ID
4
  # Change this to run pods in a different namespace
5
  runNamespace: default
6
  # Optional: attach labels to agents for constraints
7
  agentLabels:
8
    orchestration: kubernetes
9
  # Optional: if set, only allows agents to execute runs from environment
10
  # with the provided slug
11
  envSlug: ""

Keep track of your values.yaml file. You'll need it for subsequent upgrades. We recommend you store this in version control.

Setting the agentLabels key will add the provided labels to the agent for use in run constraints. For details on using labels, see Execute rules & constraints.

Setting the envSlug key will only permit the agent to execute runs from the given environment. For details on using environments, see Environments.

This example writes the API token inline into the values.yaml file. If you would like to avoid committing it directly into the file, see Using Secrets below.

Install

Add the Airplane chart repo:

bash
Copied
1
helm repo add airplane https://airplanedev.github.io/charts

Update your chart repos:

bash
Copied
1
helm repo update

Install the helm chart:

bash
Copied
1
helm install -f values.yaml airplane airplane/airplane-agent

That's it! Visit app.airplane.dev/agents to check that the the agents are up and running.

Upgrading

To update your chart in the future (e.g. when there are newer updates to the agent), you can run helm upgrade:

bash
Copied
1
helm upgrade -f values.yaml airplane airplane/airplane-agent

Using secrets

If you would prefer to use Kubernetes secrets for the token and avoid typing them into a file, you can create a secret:

bash
Copied
1
kubectl create secret generic airplane-secrets \
2
  --from-literal=token=YOUR_API_TOKEN

And reference it from the values.yaml file:

yaml
Copied
1
airplane:
2
  apiTokenSecret:
3
    name: airplane-secrets
4
    key: token
5
  teamID: YOUR_TEAM_ID
6
  # Change this to run pods in a different namespace
7
  runNamespace: default

If you're applying this after having already created the agent, you can run an upgrade to apply the changes—see Upgrading.

Setting a custom service account

By default, the agent will run all Airplane task pods with the namespace default service account. You can change this by setting the taskServiceAccountName parameter in the airplane section of the values.yaml file. This will allow these pods to hit the Kubernetes API with custom permissions, among other use cases.

Using Terraform and Helm

You can optionally use the Terraform helm_release resource to manage the Helm chart from Terraform.

You'll need to first add the Helm provider, if you haven't already:

hcl
Copied
1
provider "helm" {
2
  kubernetes {
3
    config_path = "~/.kube/config"
4
  }
5
}

Then, add the helm_release resource:

hcl
Copied
1
resource "helm_release" "airplane" {
2
  name             = "airplane-agent"
3
  repository       = "https://airplanedev.github.io/charts"
4
  chart            = "airplane-agent"
5

6
  # Change namespace if desired:
7
  # namespace        = "default"
8
  # create_namespace = true
9

10
  timeout          = "600"
11
  set {
12
    name  = "airplane.apiToken"
13
    value = var.airplane_api_token
14
  }
15
  # Alternatively, to use an existing secret:
16
  # set {
17
  #   name = "airplane.apiTokenSecret.name"
18
  #   value = "airplane-secrets"
19
  # }
20
  # set {
21
  #   name = "airplane.apiTokenSecret.key"
22
  #   value = "token"
23
  # }
24
  set {
25
    name  = "airplane.teamID"
26
    value = var.airplane_team_id
27
  }
28
}

See the docs on helm_release for more details.