Cluster requirements
Kaja runs on any Kubernetes cluster. Most things work everywhere — apps, domains, builds, secrets and routing need nothing special.
Storage is the exception, and it is worth checking before you connect a cluster rather than after. A cluster with no working storage will happily accept a database and then leave it waiting forever, because Kubernetes has nowhere to put the data.
Every row below says what breaks, not just what is needed. A requirements list that doesn't say what happens when you ignore it is a list people ignore.
Storage
| Requirement | Needed for | If it's missing |
|---|---|---|
| A default StorageClass with a dynamic provisioner | any service with a volume — PostgreSQL, durable Redis, metrics and logs | Kaja refuses to install those services and tells you why. Pick a class explicitly in the service's advanced settings, or mark one default on the cluster. |
| ReadWriteOnce support | all volumes | Nothing that stores data can run. Every CSI driver supports this; it is listed for completeness. |
Volume expansion (allowVolumeExpansion) | resizing a service later | Storage size is fixed when the service is created. Create a new service at the size you need and migrate. |
| Kubernetes ≥ 1.27 | the cluster cleaning up its own volumes | Kaja deletes them itself when a service is removed. Nothing breaks. |
Checking what your cluster has
kubectl get storageclass
The class marked (default) is the one an unqualified volume request goes to. If none is marked,
that's the case worth fixing — Kubernetes will not choose for you, and a volume request binds to
nothing.
kubectl patch storageclass <name> \
-p '{"metadata":{"annotations":{"storageclass.kubernetes.io/is-default-class":"true"}}}'
Kaja shows the same information under Cluster → Agent → Storage once the agent connects, so you can confirm from the console rather than the terminal.
Clusters that need setup
- Amazon EKS — a new cluster has no working default class until the EBS CSI driver add-on is installed. This is the most common cause of a service that never starts.
- Bare metal and on-prem — no storage exists until you install a CSI driver. local-path-provisioner is the simplest option for a single-node cluster; it stores data on the node, so it does not survive that node.
- k3s, k3d, kind, Docker Desktop — a default class is already there. Note it does not support expansion and does not enforce the size you request.
- GKE, AKS, DigitalOcean, and most managed clouds — ready as-is.
Log collection
The Observability service collects container logs by reading them from each node. Some clusters forbid that:
- GKE Autopilot, OpenShift with its default security policies, Talos, and any cluster
running Pod Security Admission at
restricted.
On those clusters metrics still work — they are collected through the Kubernetes API and touch nothing on the node. Only log collection is affected, and Kaja says so on the Observability service rather than leaving you to notice logs never arrive.
Everything else
| Requirement | Notes |
|---|---|
| Outbound HTTPS to the Kaja control plane | The agent connects out. No inbound ports need opening — this is what lets Kaja manage clusters with no public IP. |
| A namespace the agent can create resources in | The agent is installed with the permissions it needs; see Connecting clusters. |
| Any Kubernetes distribution | Managed, self-hosted, single-node or multi-node. |