Installing on Kubernetes
On Kubernetes, Spitfire goes into one namespace as controller, Postgres and runner pods, with kubectl or the Helm chart. Scaling the runner pods is a single line as load grows, so for work above 5,000 VUs this is the path we suggest. For a trial on one machine, installing with Docker is shorter. The demo app (--with-demo) is not part of Kubernetes installs.
Installing on Kubernetes
Check that you are on the right cluster:
kubectl config current-contextCheck the prerequisites (changes nothing):
curl -fsSL https://spitfire.sh | bash -s -- kubernetes --checkThe last line must be
✔ Prerequisites are met. If you seeThere is no reachable Kubernetes cluster on this system, set one up (on one Linux machinecurl -sfL https://get.k3s.io | sh -, on macOS/Windows Docker Desktop → Settings → Kubernetes → Enable, orkind create cluster) and run the check again.Install (default namespace
spitfire, the current context; change them with--namespace NS,--context C):curl -fsSL https://spitfire.sh | bash -s -- kubernetesSuccess check: within 3 minutes the pods are
Runningand1/1.kubectl -n spitfire get podsCopy the setup code from the output and open the address. The UI is on NodePort 30470; if this machine cannot reach the NodePort, the installer starts a
kubectl port-forwardin the background (deploy/kubernetes/.port-forward.pid).
Pods run as non-root with a read-only root filesystem, no capabilities and the RuntimeDefault seccomp profile. NetworkPolicies (where the CNI enforces them) let only the controller reach Postgres and only this installation's runners reach the plaintext runner port (8475). Stopping the controller stops active runs and stores their results first (up to 30 s; the pod gets 45 s).
| Option | Meaning |
|---|---|
--namespace NS, --context C |
Target (default spitfire, current-context) |
--service-type T, --node-port N |
NodePort (default, 30470), LoadBalancer, ClusterIP |
--storage-class SC, --storage-size S |
Postgres PVC (default: cluster default, 5Gi) |
--local-port N |
Local port for the port-forward fallback |
--runners N |
Number of always-on runners |
--on-demand-runners N |
Runners started as pods during a run (Runners) |
--build --registry REG |
Source tree only: builds the image and pushes it to your registry (kind, minikube, k3d and Docker Desktop need no --registry). The downloaded bundle has no source code. |
With Helm
For clusters managed with Helm, Argo CD or Flux, the chart installs the same parts with the same security settings and names (spitfire-controller, spitfire-secrets…).
Pre-check; the commands must return without error and the second must print
yes:kubectl cluster-info kubectl auth can-i create namespaces helm version --shortIf the first fails there is no cluster (step 2 above). If the second prints
no, ask your admin for a namespace and use-n <that-namespace>instead of--create-namespacebelow.Install:
helm repo add spitfire https://spitfire.sh/helm helm install spitfire spitfire/spitfire -n spitfire --create-namespaceSuccess check:
kubectl -n spitfire get pods -w; within 3 minutes every pod isRunningand1/1. For a pod stuck inPending,kubectl -n spitfire describe pod <name>; usually there is no default StorageClass (kubectl get storageclass, then--set postgres.storage.storageClass=<name>).
https://spitfire.sh/helm is short for https://spitfire.tr/download/helm; behind a proxy or firewall, allow spitfire.tr. The install notes say how to open the UI and read the setup code.
| Value | Meaning |
|---|---|
controller.service.type |
ClusterIP (default; with an ingress or port-forward), NodePort, LoadBalancer |
ingress.enabled, ingress.host, ingress.className, ingress.tls |
The UI behind your ingress controller |
controller.grpcPublicAddr |
The host:8471 runners in other locations connect to |
runners.replicas, runners.location |
Always-on runners (default 2, local) |
onDemandRunners.max |
Runners started as pods during a run (0: off) |
postgres.enabled, externalDatabase.existingSecret |
Postgres in the cluster, or your own (a Secret with the DSN) |
secrets.existingSecret |
Bring the installation's keys yourself |
admin.email, admin.password, license.key |
First admin and license key (optional) |
proxy.httpsProxy, proxy.noProxy |
The controller's outbound proxy |
The keys are generated on the first install, kept on every upgrade and not deleted by helm uninstall; the database disk stays too. Back up the spitfire-secrets Secret. To update (the card shows this command too): helm repo update spitfire && helm upgrade spitfire spitfire/spitfire -n spitfire --reuse-values.
Common problems
Symptom: There is no reachable Kubernetes cluster on this system.
Cause: kubectl has no active context, or the cluster does not answer.
Fix: Check with kubectl config get-contexts and kubectl cluster-info; without a cluster, set one up with one of the ways in step 2. For a single machine, installing with Docker is simpler.