Clusters overview

Every tenant cluster in Celum lives on a supervisor, and every supervisor runs a Cluster API (CAPI) engine that Celum installs and operates. On top of that one engine the platform offers three cluster models. They differ in how a cluster is described and how much of a cluster you actually get. All three are applied straight to the supervisor’s Kubernetes API; Celum writes nothing to Git.

<supervisor> and <cluster> are placeholders throughout — substitute your own names.

The three cluster models

Model	What you describe	How it is created
CAPI topology cluster	A declarative spec: cluster class, Kubernetes version, control-plane replicas and VM size, worker groups	`POST /api/supervisors/<supervisor>/capi/clusters`, or from a cluster template
vcluster hosted control plane	A virtual cluster whose control plane runs as pods on the supervisor, sharing its nodes	A flat `Cluster` + `VCluster` CR on the supervisor (`POST /api/supervisors/<supervisor>/capi/vclusters`)
Kamaji Talos workers	A Talos worker pool attached to a Kamaji hosted control plane	Reconciled on demand via `POST /api/supervisors/<supervisor>/capi/clusters/<cluster>/kamaji-talos-workers`

Earlier releases also had GitLab-managed guest clusters, committed to a GitOps repository. That model was removed with the GitOps integration in 1.202.0; see Repositories & manifests. A cluster created that way keeps running, but Celum no longer edits its files.

Topology clusters

The primary model. A topology cluster is one declarative spec. Celum reads it back in the same shape for editing (GET /api/supervisors/<supervisor>/capi/clusters/<cluster>), updates it with PUT, and deletes it with a single DELETE that cascades through everything the Cluster CR owns:

{
  "name": "demo-cl",
  "namespace": "proj-demo",
  "clusterClass": "talos-kubevirt",
  "kubernetesVersion": "v1.36.2",
  "controlPlaneReplicas": 1,
  "controlPlaneVmSize": { "numCPUs": 2, "memoryMiB": 4096, "diskGiB": 20 },
  "workerGroups": [
    { "name": "md0", "class": "default-worker", "replicas": 6,
      "vmSize": { "numCPUs": 2, "memoryMiB": 4096, "diskGiB": 20 } }
  ],
  "podsCidr": "10.246.0.0/16",
  "servicesCidr": "10.113.0.0/16",
  "addons": { "cniCilium": true, "platformAddons": true, "monitoring": true, "logs": true, "flows": true },
  "tenantLB": { "enabled": true, "pool": "project" }
}

The addons block is what the CAAPH engine (below) acts on, and tenantLB wires the guest’s LoadBalancer Services into the supervisor’s IP pools. Clusters created inside a project land in that project’s namespace. The create page walks through the form.

A healthy topology cluster — health/nodes/workloads/API tiles, the CAPI machines backing it, and its Helm releases

Hosted control planes

When a tenant needs API-server isolation but not its own machines, a vcluster gives them a full Kubernetes control plane running as pods, sharing the supervisor’s nodes. Kamaji Talos workers go one step further: a hosted control plane plus real Talos worker VMs attached to it. Both are covered in Hosted control planes.

The CAPI engine

Everything above depends on the engine Celum installs per supervisor in Onboarding → Cluster API. It reports state through the standard component-status model and is managed with:

Concern	Endpoints
Install / status / recover	`POST /api/supervisors/<supervisor>/capi/install` · `GET .../capi/status` · `POST .../capi/recover-rollback`
Providers	`GET /api/capi/provider-versions` (release dropdown) · `POST /api/capi/vsphere-probe` (vCenter TLS thumbprint)
ClusterClasses	`POST .../capi/clusterclasses/install` · `GET .../cluster-classes`
CAAPH add-on engine	`POST .../capi/addons` · `GET .../capi/addons/status`
Version discovery	`GET .../kubernetes-versions`

GET /api/supervisors/<supervisor>/capi/status shows the operator release plus every provider — core, bootstrap, control plane (including Kamaji), and infrastructure:

{
  "helmRelease": { "exists": true, "ready": true, "revision": "0.27.0" },
  "coreProvider": { "exists": true, "ready": true, "installedVersion": "v1.13.2" },
  "bootstrap": { "talos": { "exists": true, "ready": true, "installedVersion": "v0.7.0-alpha.2" } },
  "controlPlane": {
    "kamaji": { "exists": true, "ready": true, "installedVersion": "v0.20.0" },
    "talos": { "exists": true, "ready": true, "installedVersion": "v0.6.0-pr251" }
  },
  "infrastructure": {
    "kubevirt": { "exists": true, "ready": true, "installedVersion": "v0.11.2" },
    "vsphere": { "exists": true, "ready": true, "installedVersion": "v1.16.1" }
  }
}

The CAAPH add-on engine (Cluster API Add-on Provider for Helm) delivers platform charts into every guest — CNI, monitoring agents, CSI — as HelmChartProxy objects per namespace, from the add-on catalog the Cluster API step installs. Its status endpoint reports the provider and each proxy’s readiness:

{
  "provider": { "exists": true, "ready": true, "installedVersion": "v0.3.2" },
  "helmChartProxyCRD": true,
  "proxies": [
    { "name": "cilium-for-guests", "namespace": "proj-demo", "ready": true },
    { "name": "prometheus-agent-for-guests", "namespace": "proj-demo", "ready": true },
    { "name": "cluster-agent-for-guests", "namespace": "proj-demo", "ready": true }
  ],
  "installedChartVersion": "0.6.11"
}

Which model when

A tenant needs a real cluster with its own nodes — topology cluster

The default. Declarative spec, direct apply, full edit/delete lifecycle, add-ons delivered automatically.

API-server isolation without dedicated machines — vcluster

Seconds to create, near-zero infrastructure cost, shares the supervisor’s nodes. Not suitable when the tenant needs its own kernel, CNI, or node-level configuration.

A hosted control plane with real worker nodes — Kamaji Talos workers

The control plane runs as supervisor pods, workers are Talos VMs. Good middle ground when control-plane VMs are the cost you want to avoid.

Permissions

Task	Action
Read engine / add-on status	`capi:GetStatus`
Install engine, providers, ClusterClasses, add-ons; recover a rollback	`capi:Install`
Create a cluster (any model)	`cluster:Create`
Update / delete a cluster	`cluster:Update` / `cluster:Delete`
List ClusterClasses for the create form	`discovery:ListClusterClasses`

The in-product assistant, Celum AI, answers cluster questions from these same APIs — list_clusters, get_guest_cluster, and get_component_status (component capi or capi-addons) read the identical data these pages render.

The Clusters pages

Create a cluster

The cluster form and the template wizard.

Cluster templates

Reusable blueprints with Go-template variables.

Day-2 operations

Everything read inside a running tenant — nodes, events, metrics, Helm, workloads.

Hosted control planes

vcluster instances and Kamaji Talos workers.

Get Started

Concepts

Clusters

GitOps & Apps

Virtual machines

Networking

Security

Platform Health

Storage

Reference

Administration

Clusters overview

The three cluster models

Topology clusters

Hosted control planes

The CAPI engine

Which model when

Permissions

The Clusters pages

Create a cluster

Cluster templates

Day-2 operations

Hosted control planes

​The three cluster models

​Topology clusters

​Hosted control planes

​The CAPI engine

​Which model when

​Permissions

​The Clusters pages

Create a cluster

Cluster templates

Day-2 operations

Hosted control planes

The three cluster models

Topology clusters

Hosted control planes

The CAPI engine

Which model when

Permissions

The Clusters pages