Skip to main content
A hosted control plane inverts the usual cost structure of a tenant cluster: instead of dedicating VMs to etcd and API servers, the control plane runs as ordinary pods on the supervisor. Celum ships two flavors — vcluster (control plane and workloads share the supervisor’s nodes) and Kamaji with Talos workers (hosted control plane, real worker VMs).

​
When to choose a hosted control plane

A vcluster is the cheapest and fastest tenant you can hand out; its limit is that workloads still run on the supervisor’s shared nodes. Kamaji keeps only the control plane shared and gives the tenant its own machines.

​
vcluster

​
The engine

The vcluster provider is installed from the onboarding wizard and reports through the standard component-status model: The install call takes an instanceName (a DNS-1123 slug of at most 30 characters), and defaults the namespace to vcluster-<instance> — so several instances coexist on one supervisor, each in its own namespace. Options cover the service type, storage size and class (defaulting to the supervisor’s default StorageClass), a resource profile (small / medium / large), an optional ServiceMonitor for the tenant control plane, and optional OIDC so end users can kubectl into the tenant with their platform identity.
High availability via embedded etcd is a licensed feature of the upstream chart and is rejected by Celum’s OSS-only install — requests with highAvailability enabled fail validation rather than silently degrading.

​
vclusters as CAPI clusters

POST /api/supervisors/<supervisor>/capi/vclusters creates a vcluster as a Cluster API cluster: a plain Cluster CR whose infrastructure and control-plane references both point at a single VCluster CR. That flat shape means the instance shows up in GET /api/clusters alongside every other tenant (provider vCluster), and the provider writes the standard <cluster>-kubeconfig Secret — so GET /api/clusters/<cluster>/kubeconfig and the whole day-2 surface work unchanged. Deleting it is the same canonical DELETE /api/supervisors/<supervisor>/capi/clusters/<cluster> cascade, which removes the VCluster CR along with the Cluster.

​
Per-instance kubeconfig

Wizard-installed instances export their tenant kubeconfig to a Secret, downloadable as YAML:
A 404 here means the chart has not written the Secret yet — or kubeconfig export was never enabled for the instance — not that the instance is broken.

​
Kamaji Talos workers

The CAPI engine ships a Kamaji control-plane provider next to the Talos one (visible in GET /api/supervisors/<supervisor>/capi/status):
A Kamaji-class topology cluster runs its tenant control plane as pods on the supervisor and attaches a pool of Talos worker VMs. Those workers need a machine configuration that can only be assembled after the control plane is up — the tenant CA, a bootstrap token, and the control-plane endpoint. That is what the reconcile endpoint does:
It gathers the runtime pieces, renders the worker machine config into the cluster’s topology, and rolls the worker pool. The call is idempotent — the generated worker identity is persisted on the supervisor, so re-running it produces a byte-identical config and does not cause spurious node rollouts.
1

Create the Kamaji-class cluster

Via the ClusterClass flow. Celum fires the worker reconcile automatically in the background once the control plane reports Ready.
2

Re-run when scaling later

Bootstrap tokens expire. If you scale the worker pool well after creation, call the reconcile again first — only a token close to expiry triggers a re-render, so this is safe to do routinely.
This integration is marked experimental in the backend. The moving parts — token lifetimes, config rotation on existing clusters — are handled for you, but expect it to evolve.

​
Permissions

Celum AI reads the same state — get_component_status (component vcluster or capi), list_clusters, and get_guest_cluster answer “is the vcluster engine healthy?” or “how is this hosted cluster built?” from the identical APIs.

Clusters overview

The four cluster models side by side, including when a full cluster wins.

Access & credentials

The kubeconfig paths for both hosted flavors.

Day-2 operations

The tenant views that work identically on hosted control planes.

Projects

The namespace + addressing model hosted clusters are placed into.