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 runningairplane apikeys create <token name>
from the Airplane CLI.YOUR_TEAM_ID
: get your team ID viaairplane auth info
or visit the Team Settings page.
Create a
values.yaml
configuration file:yamlCopied1airplane:2apiToken: YOUR_API_TOKEN3teamID: YOUR_TEAM_ID4# Change this to run pods in a different namespace5runNamespace: default6# Optional: attach labels to agents for constraints7agentLabels:8orchestration: kubernetes9# Optional: if set, only allows agents to execute runs from environment10# with the provided slug11envSlug: ""
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:
bashCopied1helm repo add airplane https://airplanedev.github.io/charts
Update your chart repos:
bashCopied1helm repo update
Install the helm chart:
bashCopied1helm 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
:bashCopied1helm 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:
bashCopied1kubectl create secret generic airplane-secrets \2--from-literal=token=YOUR_API_TOKEN
And reference it from the
values.yaml
file:yamlCopied1airplane:2apiTokenSecret:3name: airplane-secrets4key: token5teamID: YOUR_TEAM_ID6# Change this to run pods in a different namespace7runNamespace: 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:
hclCopied1provider "helm" {2kubernetes {3config_path = "~/.kube/config"4}5}
Then, add the
helm_release
resource:hclCopied1resource "helm_release" "airplane" {2name = "airplane-agent"3repository = "https://airplanedev.github.io/charts"4chart = "airplane-agent"56# Change namespace if desired:7# namespace = "default"8# create_namespace = true910timeout = "600"11set {12name = "airplane.apiToken"13value = var.airplane_api_token14}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# }24set {25name = "airplane.teamID"26value = var.airplane_team_id27}28}
See the
docs on
helm_release
for more details.