Skip to main content
Everything in Celum hangs off two nouns. A supervisor is a Kubernetes cluster that runs Cluster API and that Celum holds a kubeconfig for. A tenant cluster (also called a guest cluster) is a Cluster API Cluster object living on a supervisor. Celum never invents either — it reads what is already there.
Celum supervisor overview showing node, CPU, memory and storage tiles above a table of tenant clusters

A supervisor's Summary tab — node, CPU, memory and storage rollups, and the tenant clusters provisioned on it.

​
What a supervisor is

A supervisor is, concretely, one kubeconfig plus the name Celum files it under. That name appears in the URL of every scoped page (/s/<supervisor>/...), in every API path (/api/supervisors/<supervisor>/...), and in every KRN (krn:vks:supervisor:<supervisor>).

​
Where kubeconfigs come from

Celum reads supervisors from three sources, and a supervisor may come from any of them:

A directory of files

Every file in KUBECONFIGS_DIR becomes a supervisor. The filename is the supervisor name — there is no name field inside the file that Celum reads.

The database

Kubeconfigs uploaded through the UI are stored in PostgreSQL with a name, server URL, an optional platform label, and an optional site.

A single file

KUBECONFIG_PATH names one kubeconfig, used as a fallback.

In-cluster

When Celum runs inside Kubernetes with no kubeconfig configured, it uses its own service account.
The last two produce a synthesized supervisor named __default__. An empty supervisor name in a request resolves to it, which is why single-supervisor deployments work without naming anything.
Renaming a kubeconfig file renames the supervisor. Because the name is embedded in every KRN, IAM policies written against the old name stop matching, and the URLs your team has bookmarked break. Treat supervisor names as stable identifiers.

​
Client caching

Kubernetes clients are built once per supervisor and cached. The cache is invalidated when a database-backed kubeconfig changes or is removed, so an uploaded credential takes effect without a restart. A kubeconfig file that changes on disk is not detected the same way — restart the backend after editing one.

​
Labels and sites

Database-backed supervisors carry two optional descriptors: Neither affects authorization. Both are descriptive only.

​
Managing supervisors

kubeconfig:Download hands out a working credential for the supervisor itself. None of the built-in policies grant it except K8sGateAdmin — keep it that way unless you have a reason not to.

​
What a tenant cluster is

A tenant cluster is a cluster.x-k8s.io/v1beta1 Cluster on a supervisor. Celum reads it directly; there is no mirror of it in Celum’s own database. Each cluster surfaces:
A cluster still provisioning legitimately has no API server endpoint. An empty value there is not an error — it means Cluster API has not assigned one yet.

​
Provider detection

The provider is never configured; it is read from the infrastructure reference: Anything else falls back to the kind name with the Cluster suffix stripped — so an unknown CAPI provider still gets a sensible label rather than an error.

​
The hosts behind a supervisor

The Infrastructure tab lists the supervisor’s own nodes rather than its tenant clusters — status, role, CPU and memory pressure, disks, NIC throughput, and load.
Celum supervisor Infrastructure tab listing three control-plane hosts with CPU, memory, disk and NIC metrics

The Infrastructure tab — the supervisor's own hosts. Each row drills into per-host hardware, network, storage, and sensors.

​
How the two are addressed

KRNs nest the cluster inside its supervisor, which is what lets a policy scope access to one supervisor, one cluster, or a name prefix:
Several cluster read endpoints take the supervisor from a ?supervisor= query parameter rather than the URL path. When it is absent it resolves to *, so a policy written as krn:vks:supervisor:*:cluster:<cluster> will match those calls. Scope such policies by cluster name, not by assuming the supervisor segment will be concrete.

Projects

The namespace and address-space abstraction on top of a supervisor.

Permissions model

How a request resolves to an action and a KRN.

Create a cluster

Provision a tenant cluster on a supervisor.

Architecture

Where supervisor calls sit in the request pipeline.