Prerequisites
- Permission:
cluster:Createonkrn:celum:supervisor:<supervisor>:cluster:*, checked against the project you create the cluster in. The form’s lists are filled bydiscovery:*reads (ClusterClasses, instance types, storage classes) and the address plan bycilium:GetState; without one of them the field falls back to typed input. - A supervisor with Cluster API onboarded, and at least one ClusterClass offered on it. A class is installed by Onboarding → Cluster API.
- A project to put the cluster in.
- For the template wizard, at least one template under Settings → Cluster templates.
<supervisor> and <cluster> are placeholders throughout — substitute your own names.Two ways in
The cluster form
Workloads → New workload → Tenant cluster opens it as a drawer, “Create Kubernetes cluster”. It is also a page of the same name at
/s/<supervisor>/clusters/create-capi; the old address /s/<supervisor>/clusters/create redirects there.From a template
/s/<supervisor>/create-from-template — a five-step wizard over a stored template, with a review of the rendered files. On a supervisor whose label names another platform (a vSphere supervisor, for example), New workload → Tenant cluster opens this wizard instead of the form.
The cluster form
Cluster
With no class installed the form says so and points at Onboarding → Cluster API; a vCluster can still be created.
Setup: Simple or Advanced
After you pick a Talos or Kamaji class, Setup asks how much you want to set yourself.- Simple shows only the size and fills in the rest: the Image Library’s default Talos image (or the newest ready one; on vSphere the newest of Celum’s own
talos-<version>templates, else the newest other template with Talos in its name), the Kubernetes version that image supports, the supervisor’s default storage class, the class’s DNS, search-domain and NTP defaults and disk size, one worker poolmd0, every guest add-on on, and address ranges assigned automatically. - Advanced shows every section below.
ClusterClass variables (Advanced)
The fields come from the class’s own variable schema, in its order.
The newest Kubernetes version depends on the Talos image: the form says which range the picked image supports. DNS, search-domain and NTP fields left empty use the supervisor’s own servers.
Control plane and worker pools (Advanced)
- Control plane: replicas (use an odd number, 1, 3 or 5, to keep etcd quorum; on Kamaji, the number of control-plane pods), an instance type and a disk size per node. Kamaji has no control-plane VMs to size.
- Worker pools: each pool has a name, a replica count, an instance type and a disk size per node, and scales independently. Add worker pool adds one.
Guest add-ons (Advanced)
Networking (Cilium) is always installed. Each toggle below is on by default and installs its add-on into the guest through Cluster API’s Helm add-on provider:
Node setup is installed whatever these toggles say: the Talos cloud controller on talos-kubevirt, and the vSphere add-ons (cloud controller and CSI driver) on talos-vsphere. Persistent storage switches only the KubeVirt CSI driver.
Networking (Advanced)
- Pod addresses and Service addresses are assigned automatically from the supervisor’s guest ranges: the first free pod
/19and service/22, checked against the supervisor and every existing cluster. Turn on Choose address ranges myself only when the ranges must match something outside the platform, such as firewall rules; each must be at least a/22and must not overlap anything. - Give apps external IP addresses (KubeVirt classes) lets the guest’s LoadBalancer Services get addresses reachable from your network. Where addresses come from is either Shared with project (the project’s LB range, shared with its other clusters) or This cluster only (a range of its own, announced to your network, picked from the supervisor’s LB band).
vCluster
The vcluster card creates a virtual cluster that runs inside the supervisor, in the project’s namespace. One vCluster per project namespace.Create
Create cluster applies the Cluster straight to the supervisor: there is no preview step in this form. Over the API this isPOST /api/supervisors/<supervisor>/capi/clusters?namespace=<project-namespace> for a ClusterClass and POST /api/supervisors/<supervisor>/capi/vclusters?namespace=<project-namespace> for a vCluster.
Result: the Cluster API objects exist. Provisioning is asynchronous, so the cluster list is where you watch, not the response.
Template wizard
1
Template
Choose from the templates available for the supervisor.Result: the rest of the wizard is built from the template you picked — its variables, its defaults. An empty list is not a permissions problem: templates live in Celum’s database, so a deployment without one has nothing to offer here.
2
Cluster
Provide a cluster name (a DNS label, max 63 chars) and namespace.
3
Variables
Set the template’s variables. Known types (storage class, Kubernetes version, etc.) are offered as supervisor-aware dropdowns; a variable the template left as free text is checked against nothing.
4
Workers
Set control-plane replicas and one or more worker groups. The wizard keeps the control-plane count odd; the API does not, so a caller posting directly can create a two-node control plane that cannot lose either node.
5
Review
Celum renders the template and lists the files it will apply to the supervisor. Create applies them to the supervisor’s API at once and reports each resource.
POST /api/cluster-templates/<id>/preview (cluster-template:Get on the template) and the create POST /api/cluster-templates/<id>/create (cluster:Create on the template).
Template variables
Templates are rendered with Go templating ({{.VariableName}}). Every template can use these built-in variables without declaring them:
ClusterNameSupervisorSupervisorServerUrlSupervisorNamespaceNamespaceKubernetesVersionClusterClass
StorageClassControlPlaneReplicasControlPlaneVmClassEnvironmentDomainPodsCIDRServicesCIDRServiceDomain
name, label, default, and description, and surfaced as form fields in the wizard. Authoring them is covered in Cluster templates.
Verify it worked
The new cluster appears under Workloads and at/s/<supervisor>/clusters. Watch it move through its Cluster API phase (Provisioning → Provisioned) and its control-plane and worker replica counts converge on the desired numbers. Open the cluster to see its nodes, API server endpoint, and the pod/service ranges that were actually assigned. From here, Day-2 operations covers everything the detail page reads, and Access & credentials covers downloading its kubeconfig.
What commonly goes wrong
Reading a stall
A cluster that will not leaveProvisioning almost always says why in its events, and three signatures account for most of it:
The third is the one that sends people in the wrong direction: the missing secret is the most visible symptom and the least useful place to start.
Providers
Templates carry a provider (generic, tanzu, or talos), and Celum auto-detects a cluster’s provider from its Cluster API infrastructureRef. vSphere (VKS/TKGs) and CloudStack are tested; other CAPI providers are compatible.
Celum AI can walk this flow’s inputs with you —
list_cluster_templates and get_cluster_template show the available blueprints and their variables, and get_guest_cluster reads a created cluster back in the same spec shape. It can also create one: create_capi_cluster takes everything get_supervisor_capi_catalog supplies, including the legal Kubernetes versions, which differ per ClusterClass.It cannot delete one. Removing a cluster requires a person, by policy — so an assistant can get you into this flow but never out of it.Related
Clusters overview
The four cluster models and the CAPI engine behind this flow.
Cluster templates
Authoring the templates this wizard consumes.
Troubleshooting
The triage ladder when a new cluster misbehaves.
Supervisors & clusters
What a supervisor is and what Celum reads from each cluster.
Permissions reference
Every
cluster:* action and the KRN it is checked against.Projects
The namespace + address-space abstraction clusters are placed into.