Skip to main content
A cluster template is a named blueprint that becomes a whole cluster. Templates live under Settings → Cluster templates, are stored in Celum’s database, and work the same on every supervisor. The template wizard is how one turns into a cluster.

​
What a template holds

Files are rendered with Go templating: {{.VariableName}} anywhere in a custom file is substituted at creation time. Besides the custom variables, every template can use the built-in variables listed on the create page. Built-ins are injected from the request, the supervisor and the template’s own infrastructure fields; a value you pass always wins over an injected one.
Templates are validated at save time: every {{.Name}} referenced in customFiles must be a declared variable or a known built-in. A typo fails the save, not the eventual cluster creation.SourceRepo is still accepted, so a template written when Celum committed to Git keeps saving, but it always renders empty.

​
The generated Cluster

Unless your customFiles already include a cluster.yaml, Celum generates the Cluster resource from the infrastructure fields, and the provider decides its shape: So a minimal generic template needs no hand-written Cluster at all.

​
Tanzu templates

A tanzu template is for a vSphere Supervisor (vSphere with Tanzu, now vSphere Kubernetes Service) that you registered in Celum as a supervisor. Celum generates the same Cluster for tanzu as for generic: a cluster.x-k8s.io/v1beta1 Cluster with a topology. Celum does no check of its own for the provider. A cluster becomes a Tanzu cluster because of the ClusterClass and the values you pick in the wizard. On a vSphere Supervisor, the template wizard fills its pickers from the Supervisor: For a ClusterClass that is not one of Celum’s own (talos-*, kamaji*), the generated Cluster has two topology variables: storageClass, and vmClass, which is set to the Control Plane VM Class. The control plane also gets the VM class as an override, and each worker group gets its own VM class as an override. On a supervisor that is not a vSphere Supervisor, the Kubernetes version and VM class pickers have nothing to read, so they become free text. A picker whose read you are not allowed to make becomes free text too. Celum creates the cluster anyway. It refuses only a supervisor that serves no Cluster API Cluster, with 412, and then the ClusterClass decides whether vmClass and storageClass have any meaning.
A new template’s Control Plane VM Class starts as best-effort-large. It must name a class that the vSphere Namespace offers. A class picked in the wizard goes to the control plane; the template’s class stays the cluster’s vmClass, which a worker group without a class of its own inherits, and the control plane’s when nothing is picked.
Settings → Cluster templates → create or edit a template and set Provider to Tanzu (VKS). To create a cluster from it, use the supervisor’s template wizard.

​
Render, preview, create

Three endpoints take a template from blueprint to cluster, in increasing order of commitment:
1

Render — resolve the variables

POST /api/cluster-templates/<id>/render merges variable defaults with the values you pass and returns the fully substituted templateData. Nothing touches a supervisor. The wizard uses it to keep its form live.
2

Preview — see the exact files

POST /api/cluster-templates/<id>/preview renders every custom file and the generated Cluster, and returns the complete file set with paths. Still nothing is created: this is the wizard’s review step.
3

Create — apply the result

POST /api/cluster-templates/<id>/create renders the same file set and applies it to the supervisor’s Kubernetes API, file by file, and reports each resource. It answers 201 when everything applied and 207 when some resources failed, so read the per-resource results.
Create, and the preview before it, enforce three guardrails:
  • StorageClass is required — through a template variable default, the infrastructure fields, or an explicit override. Creation fails at once with a clear message otherwise.
  • Address ranges must not collide. Leave the pod and service CIDRs blank and Celum assigns free ranges, checked against the supervisor and every existing cluster; the preview shows the ranges it would assign. A value is used instead when one is set, in this order: the request’s variables, a template variable’s default (PodsCIDR, ServicesCIDR, ServiceDomain), the template’s Network fields. Explicit CIDRs that overlap an existing cluster are refused with 409 Conflict, and ones that overlap the supervisor’s own pod or service range with 400.
  • An existing cluster keeps its network. Applying a template again to a cluster that already exists keeps the ranges it has. A cluster that has none keeps none: Celum assigns it nothing, and once a node has registered it refuses a value with 409 Conflict, because declaring one would move the range its nodes were given. When Celum cannot read the cluster to tell, it answers 503 rather than guess.
Celum writes nothing to Git. Earlier releases could commit a template’s files to a GitOps repository instead of applying them; that mode was removed with the GitOps integration in 1.202.0.

​
Permissions

Cluster add-ons are no longer a library here. The ClusterResourceSet library, with its push, import and the cluster-addon:* actions, was removed in 1.179.0: it fed no delivery path. A guest cluster’s add-ons come from the add-on catalog that Onboarding → Cluster API installs, switched per cluster with the Guest add-ons toggles on the cluster form.
Cloud-init templates (Linux) and sysprep templates (Windows) are the VM-side siblings of cluster templates — the same variable model, applied to one machine. See Guest customisation templates.
Celum AI answers template questions through the same APIs — list_cluster_templates and get_cluster_template return the blueprints, variables and files the settings page shows.

Create a cluster

The template wizard that consumes these templates, and the built-in variable list.

Clusters overview

Where templates fit among the cluster models.

Storage classes & profiles

What the required StorageClass variable should point at.

Permissions reference

Every cluster-template:* action with its KRN.