Kamaji or vCluster for the environment reef¶
Keep vCluster as the Nereid of today's Environments; register Kamaji as the candidate Nereid for an Environment, or a cluster, with nodes of its own. The owner asked on 2026-11-07 whether Kamaji should replace vCluster. Facts come from Kamaji's README and versioning page, opened on GitHub that day; kamaji.clastix.io was not reachable from the session.
What each one gives¶
| Question | vCluster (the vcluster Nereid) |
Kamaji |
|---|---|---|
| What it makes | A virtual cluster: control plane in a pod, tenant pods synced into a host namespace | A hosted control plane: kube-apiserver, scheduler and controller manager in pods (TenantControlPlane), state in a Datastore |
| Where the tenant's pods run | On the host cluster's own nodes | On worker nodes that join the control plane (kubeadm, Konnectivity); Kamaji does not create them, Cluster API does |
| What an Environment needs | A Helm release in env-vcluster-<name>: one chart, no machine |
A control plane plus at least one node: a VM or a machine per Environment |
| Datastore | Embedded, in an emptyDir today |
etcd, or MySQL, PostgreSQL or NATS through kine, one store shared by many control planes |
| Cluster API | A control plane provider | |
| Licence and releases | Apache-2.0; the chart 0.37.5 pinned by SHA-256 | Apache-2.0; monthly -edge releases only; stable, semantically versioned artifacts only by subscription to CLASTIX since July 2024 |
Why not swap¶
- The use case is an Environment per agent on one k3d cluster (#620, #568). vCluster runs it with no new machine; Kamaji would need a node per Environment, a VM or a kubeadm container, for the same result, with more to delete at expiry.
- The scenes stay small:
make scene-environmentmakes two vclusters at once on the throwaway cluster; with Kamaji each would also need node containers of its own beside the throwaway cluster. - Releases: only edge versions are open; Nereus pins what it installs, and pinning an edge release means following one every month.
Where Kamaji fits¶
- An Environment with its own nodes, isolated at the node level: a second Nereid of the environment reef, chosen by Mandate, without changing the reef (ADR 0002).
- Bootstrapping from a local seed (#61): the clusters the platform creates in a cloud, with Cluster API, could get their control planes from Kamaji, many on one management cluster and one shared datastore (CloudNativePG, already a Nereid).
Learn more¶
- Kamaji README and releases and versions (CLASTIX).
- The vcluster Nereid (#620, #633).