SpitfireLoad Testing & APMWhat's new

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

  1. Check that you are on the right cluster:

    bash
    kubectl config current-context
  2. Check the prerequisites (changes nothing):

    bash
    curl -fsSL https://spitfire.sh | bash -s -- kubernetes --check

    The last line must be ✔ Prerequisites are met. If you see There is no reachable Kubernetes cluster on this system, set one up (on one Linux machine curl -sfL https://get.k3s.io | sh -, on macOS/Windows Docker Desktop → Settings → Kubernetes → Enable, or kind create cluster) and run the check again.

  3. Install (default namespace spitfire, the current context; change them with --namespace NS, --context C):

    bash
    curl -fsSL https://spitfire.sh | bash -s -- kubernetes
  4. Success check: within 3 minutes the pods are Running and 1/1.

    bash
    kubectl -n spitfire get pods
  5. Copy 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-forward in 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…).

  1. Pre-check; the commands must return without error and the second must print yes:

    bash
    kubectl cluster-info
    kubectl auth can-i create namespaces
    helm version --short

    If 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-namespace below.

  2. Install:

    bash
    helm repo add spitfire https://spitfire.sh/helm
    helm install spitfire spitfire/spitfire -n spitfire --create-namespace
  3. Success check: kubectl -n spitfire get pods -w; within 3 minutes every pod is Running and 1/1. For a pod stuck in Pending, 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.