> ## Documentation Index
> Fetch the complete documentation index at: https://docs.celum.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a cluster

> Provision a tenant cluster from a form, a Cluster API class, or a reusable template — with a preview before anything is created.

Celum provisions tenant clusters on a supervisor. You describe the cluster, review a generated preview, and confirm — Celum then creates it. This page covers the interactive creation flows; how they relate to the platform's [four cluster models](/clusters/overview#the-four-cluster-models) — and the hosted-control-plane alternatives — lives on the [overview](/clusters/overview).

## Prerequisites

* **Permission**: `cluster:Create` on `krn:vks:supervisor:<supervisor>:cluster:*`. The preview step additionally needs `cluster:Preview`, and the form's dropdowns are populated by `discovery:*` reads.
* A supervisor whose kubeconfig Celum can reach, with Cluster API installed.
* For the template flow, at least one cluster template defined under **Settings → Cluster templates**.
* For the ClusterClass flow, at least one `ClusterClass` present on the supervisor.

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

## Creation flows

There are three entry points, all reachable from a supervisor:

<CardGroup cols={1}>
  <Card title="From a template" icon="copy">
    `/s/<supervisor>/create-from-template` — a guided wizard over a predefined template. Best for standardized, repeatable clusters.
  </Card>

  <Card title="Standard form" icon="pen-to-square">
    `/s/<supervisor>/clusters/create` — fill cluster settings directly and preview the generated configuration.
  </Card>

  <Card title="Cluster API class" icon="cubes">
    `/s/<supervisor>/clusters/create-capi` — spawn a cluster from a ClusterClass whose fields are driven by the class's own variable schema; applied directly to the supervisor.
  </Card>
</CardGroup>

## Template wizard

<Steps>
  <Step title="Select a template">
    Choose from the templates available for the supervisor.
  </Step>

  <Step title="Name the cluster">
    Provide a cluster name (a DNS label, max 63 chars) and namespace.
  </Step>

  <Step title="Fill variables">
    Set the template's variables. Known types (storage class, Kubernetes version, etc.) are offered as supervisor-aware dropdowns.
  </Step>

  <Step title="Define workers">
    Set control-plane replicas (an odd number for etcd quorum) and one or more worker groups.
  </Step>

  <Step title="Review & create">
    Preview the generated configuration, then confirm to create the cluster.
  </Step>
</Steps>

### Template variables

Templates are rendered with Go templating (`{{.VariableName}}`). Every template can use these **built-in variables** without declaring them:

<Columns cols={2}>
  <div>
    * `ClusterName`
    * `Supervisor`
    * `SupervisorServerUrl`
    * `SupervisorNamespace`
    * `Namespace`
    * `SourceRepo`
    * `KubernetesVersion`
    * `ClusterClass`
  </div>

  <div>
    * `StorageClass`
    * `ControlPlaneReplicas`
    * `ControlPlaneVmClass`
    * `Environment`
    * `Domain`
    * `PodsCIDR`
    * `ServicesCIDR`
    * `ServiceDomain`
  </div>
</Columns>

**Custom variables** are defined per template, each with a `name`, `label`, `default`, and `description`, and surfaced as form fields in the wizard.

## What you configure

Whichever flow you use, a cluster is described by fields such as:

| Group         | Fields                                                                                 |
| ------------- | -------------------------------------------------------------------------------------- |
| Identity      | cluster name, environment (`dev`/`staging`/`prod`), region                             |
| Kubernetes    | version, cluster class                                                                 |
| Storage       | storage class                                                                          |
| Network       | domain, pods CIDR, services CIDR (both auto-allocated when left blank), service domain |
| Control plane | replica count (odd)                                                                    |
| Worker groups | per group: name, machine class, VM class, replicas                                     |
| Applications  | the platform apps to enable                                                            |

Talos-based classes additionally take an image (golden PVC or VM template) and VM sizing.

<img src="https://mintcdn.com/celum-e0119be0/PP5CnCRurbHgq1sb/images/clusters/create-capi-form.png?fit=max&auto=format&n=PP5CnCRurbHgq1sb&q=85&s=8eabe1c850b857cddee586cdf3099e20" alt="The Create CAPI cluster form — ClusterClass variables, control plane sizing, worker pools, CAAPH guest add-ons, tenant LoadBalancer and cluster CIDRs" width="1459" height="2073" data-path="images/clusters/create-capi-form.png" />

## Preview and create

Both the standard and template flows generate the cluster configuration and show it to you **before** anything is created:

<Steps>
  <Step title="Preview">
    Celum renders the full set of configuration files for the cluster and lists them for review. Nothing is created yet.
  </Step>

  <Step title="Confirm">
    On confirm, the cluster is created on the supervisor and appears in the cluster list.
  </Step>
</Steps>

<Note>
  Leave the pod and service CIDRs **blank** and Celum allocates free, non-overlapping subnets automatically — checked against the supervisor and every existing cluster. An **explicit** CIDR that overlaps an existing cluster is rejected outright; pick another range or leave the field blank. A `StorageClass` must also resolve at creation time — from a template variable, the infrastructure fields, or an explicit value.
</Note>

In the template flow, *how* the confirmed files are applied depends on the supervisor: with an attached GitOps repository they are committed there in one atomic commit; without one they are applied directly to the supervisor's API. The repository attachment is the switch — you never pick a mode. Details in [Templates & addons](/clusters/templates#render-preview-create).

## Verify it worked

The new cluster appears 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 CIDRs that were actually assigned. From here, [Day-2 operations](/clusters/day-2-operations) covers everything the detail page reads, and [Access & credentials](/clusters/access-and-credentials) covers downloading its kubeconfig.

## What commonly goes wrong

| Symptom                                 | Cause                                                                                                                                                                                    |
| --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `403` before the form loads             | Missing `cluster:Create` on the target supervisor, or the dropdown reads (`discovery:*`) are denied so the form cannot populate.                                                         |
| Creation rejected for overlapping CIDRs | An explicitly entered pod or service range collides with the supervisor or an existing cluster. Clear the field so the allocator picks a free subnet, or choose a non-overlapping range. |
| Cluster stays in `Provisioning`         | Cluster API is waiting on the infrastructure provider. The cluster's events page (`/s/<supervisor>/clusters/<cluster>/events`) carries the provider's own reason.                        |
| No cluster classes offered              | The ClusterClass flow needs classes installed on that supervisor; a supervisor without Cluster API installed has none.                                                                   |
| Control plane never reaches quorum      | Control-plane replicas set to an even number. Use an odd count.                                                                                                                          |

## 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.

<Note>
  **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.
</Note>

## Related

<CardGroup cols={2}>
  <Card title="Clusters overview" icon="circle-nodes" href="/clusters/overview">
    The four cluster models and the CAPI engine behind this flow.
  </Card>

  <Card title="Templates & addons" icon="copy" href="/clusters/templates">
    Authoring the templates this wizard consumes — render, preview, apply modes.
  </Card>

  <Card title="Troubleshooting" icon="bug" href="/clusters/troubleshooting">
    The triage ladder when a new cluster misbehaves.
  </Card>

  <Card title="Supervisors & clusters" icon="layer-group" href="/concepts/supervisors-and-clusters">
    What a supervisor is and what Celum reads from each cluster.
  </Card>

  <Card title="Permissions reference" icon="list-check" href="/reference/permissions">
    Every `cluster:*` action and the KRN it is checked against.
  </Card>

  <Card title="Projects" icon="folder-tree" href="/concepts/projects">
    The namespace + address-space abstraction clusters are placed into.
  </Card>
</CardGroup>