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

# Platform onboarding

> The ten steps that turn a registered Talos supervisor into somewhere workloads can live — what each one installs, and what gates what.

By the end of this page the supervisor runs a CNI, has storage it can bind claims against, can issue TLS certificates, and is ready to host workloads or spawn tenant clusters. You will also know which of the ten steps you are allowed to skip, and why the four you are not are in that order.

This page starts where [Register a supervisor](https://docs.celum.io/get-started/register-a-supervisor.md) ended: a registered, reachable supervisor labelled `talos`, with a domain attached.

## What this changes on your cluster

A great deal, and this is the boundary the previous page promised.

Registration wrote a row in Celum's database and touched nothing on your cluster. Onboarding installs Flux, a per-node agent, a CNI, a storage layer, cert-manager, and whatever optional components you enable — as HelmReleases that Flux then keeps reconciled. Cilium in particular replaces the cluster's networking.

Run it on a supervisor you are prepared to have changed.

```mermaid theme={null}
flowchart LR
    P[Source and Bootstrap] -->|"Flux + cluster agent Ready"| N[Networking]
    N -->|"Cilium Ready"| E[every remaining step]
    E --> C[Certificates]
    C -->|"cert-manager Ready"| A[Cluster API]
    C -->|"cert-manager Ready"| M[Monitoring]
    E --> S[Secret Store]
    S -->|"only when the backend holds a Vault credential"| M
```

## Before you start

Four things gate onboarding from outside the wizard. Three of them fail **silently** — nothing on screen names them — which is the reason this section exists.

* **The supervisor's label must be exactly `talos`.** Anything else and the page renders one sentence and no wizard: *"Platform Onboarding is only available on Talos supervisors."* Fixable in place, from Settings → Kubeconfigs.
* **Omni must be configured**, if you intend to install any backend that consumes raw disks — Ceph, LINSTOR, or anything else with a disk picker. That inventory is read from Omni, and when Omni is disabled or unreachable the endpoint returns **200 with an empty machine list** and a `source` of `omni-disabled` / `omni-error`. On screen that is an empty disk table — indistinguishable from a cluster with no free disks — and such a backend cannot be installed through the UI at all. The `source` field is the only thing that tells the two apart.
* **A domain attached to the supervisor**, if you want certificates. Certificates derive their names from it; without one they sit Pending with nothing explaining why.
* **`DATABASE_URL` on the backend.** Without it IAM allows everything regardless of `IAM_ENABLED`, so the permissions below are not actually enforced.

You also need the install permissions for the steps you intend to run: `supervisor:Onboard` and `supervisor:Bootstrap`, `cilium:Apply` and `project:Configure` for the Networking declarations, `cilium:Install`, `storage:InstallDriver`, `certs:Install`, and one for each optional component. A step whose *status* read is refused behaves differently from one whose *install* is refused, and the wizard distinguishes them: see [What commonly goes wrong](#what-commonly-goes-wrong).

## The shape of it

Ten steps. **Four are required and six are optional**, and the difference is mechanical rather than advisory: the **Next** button is withheld until a required step reports `done`, while an optional one can always be stepped past.

Two more behaviours worth knowing before you start clicking:

* **While a step is reconciling, all navigation freezes** — the stepper pills and Next alike — so you cannot wander off mid-apply. This applies to optional steps too.
* **Every step is deep-linkable** as `?step=<key>`, which is how the supervisor page's Configure links land you in the right place. Retired keys still resolve: `?step=cilium`, `?step=interface-roles`, `?step=bgp-engine` and `?step=network-features` all redirect into Networking, and `?step=cluster-agent` into Source & Bootstrap. The URL is then rewritten to the canonical key, so an old bookmark works and stops being a second identity.

| # | Step | | Installs | Unlocks |
| - | - | - | - | - |
| 1 | **Source & Bootstrap** | required | Flux, cluster agent (and declares where charts and images come from) | everything |
| 2 | **Networking** | required | Cilium, the BGP engine, the North-South gateway | everything below |
| 3 | **Secret Store** | optional | External Secrets Operator | Monitoring — conditionally |
| 4 | **Storage** | required | a backend from the catalogue — software-defined, an array, or NFS — plus the CSI snapshot controller (not with the NFS server card) | claims that bind |
| 5 | **Certificates** | required | cert-manager + a ClusterIssuer of the type you pick | Cluster API, and TLS everywhere |
| 6 | **DNS Publishing** | optional | external-dns | A records for published routes |
| 7 | **Monitoring** | optional | kube-prometheus-stack, Loki, Alloy, the ClickHouse flow store | the store Flow Telemetry writes to |
| 8 | **Virtualization** | optional | KubeVirt + CDI | VMs |
| 9 | **Cluster API** | optional | cluster-api-operator, the providers and ClusterClasses for the tenant cluster kinds you offer, the CAAPH guest add-on engine | tenant clusters |
| 10 | **Flow Telemetry** | optional | ClickHouse schema + agent dispatchers | every Security surface |

Every option each step asks for, with its default and the API route and MCP tool behind it, is on [Onboarding options](https://docs.celum.io/reference/onboarding-options.md).

The order is not cosmetic. Secret Store sits at position 3 — before Storage, which it does not need — because a credential can only migrate into Vault if ESO is already installed when its step runs. Everything below it is eligible; everything above it is permanently excluded. The DNS-01 tokens the Certificates step uses are the first beneficiaries.

![Platform Onboarding on supervisor prod with the step pills Source & Bootstrap, Networking, Secret Store, Storage, Certificates, DNS Publishing, Monitoring and Virtualization, the Source & Bootstrap step open with its registry mirror table, and an Installation Summary listing every step as Installed](https://mintcdn.com/celum-e0119be0/sA7S2Ajgv1l2CH1V/images/get-started/onboarding-wizard.png?fit=max\&auto=format\&n=sA7S2Ajgv1l2CH1V\&q=85\&s=5d97e1cef1e63b88150133d3f84ce529)

The wizard: the step pills across the top, the open step, and the Installation Summary on the right

## The five gates

A locked step says why, in one sentence, and the sentence names the **earliest** missing prerequisite rather than the nearest.

| Gate | Opens | What stays locked until it does |
| - | - | - |
| **Flux** | Flux and the cluster agent both Ready | Networking, and by transitivity everything |
| **Cilium** | the Cilium HelmRelease reports Ready | every step from 3 to 10 |
| **cert-manager** | Certificates done | Cluster API — *"cluster-api-operator requires cert-manager"*, a hard prerequisite of the operator itself — and Monitoring |
| **Storage** | any catalogue backend serving a usable class | Monitoring — Prometheus and Grafana both want PVCs |
| **Secret Store** | ESO connected to Vault, or the backend holds no Vault credential | Monitoring |

> [!NOTE]
>
> The Storage gate used to ask three hardcoded questions — is Rook's cluster ready, is the NFS release ready, is the Hitachi HSPC driver ready. The catalogue then grew, and most of its backends were invisible to that check, so a supervisor running LINSTOR had working storage, a green storage panel, a Storage step stuck below `done`, and **Monitoring locked behind it with nothing on any screen saying why.**
>
> It now asks the question from the other end: which StorageClasses does the cluster actually have, and which catalogue backend owns each one's provisioner. One list, then a probe of only what is really there — so the cost does not grow with the catalogue, and a backend nobody has documented yet still counts.

The Secret Store gate is the one that surprises people, and it has an escape hatch that is not a workaround: **when the backend holds no Vault credential at all, the gate simply opens.** Running without Vault is a supported configuration, not a degraded one — credentials are then written straight into the cluster, which is exactly how it worked before the migration. The step stays optional for that reason. Making it required would dead-end onboarding on a component the platform does not require, since "done" here means the ClusterSecretStore authenticated to Vault.

## The four you cannot skip

### 1. Source & Bootstrap

Two halves with one dependency between them. First you declare where charts and images come from — a registry mirror and per-role sources — and then Flux and the cluster agent are installed *through that declaration*. Leaving the declaration empty is valid: the supervisor then uses its site's default registry, then the estate-wide default, then each chart's public source. The cluster agent is the exception. Its chart has no public source, so register the registry that holds Celum's charts first.

The bootstrap half is what makes this step required. Every step after it installs through helm-controller, so Flux is the gate they all wait on.

> [!WARNING]
>
> A HelmRelease's chart source is written at apply time and **nothing ever revisits it**. Declare a registry after a chart is installed and that chart keeps pulling from upstream forever, while everything applied afterwards comes from the mirror. Declare your registries *here*, before anything else is installed — or audit afterwards with `get_onboarding_registry_provenance` and move the strays with `repoint_onboarding_chart`.

**Result:** Flux and the cluster agent both report Ready, and the install half of the Networking step unlocks. Its three declarations work before Flux.

### 2. Networking

One step, three sections: what each interface is for, how the block is addressed and routed, then Cilium itself — plus the BGP engine when you peer, and the North-South gateway.

You do not choose the North-South gateway. On a new supervisor, the step's single Apply installs **Envoy Gateway** once Cilium is ready. Envoy runs as its own release, outside the CNI, so a Gateway API change cannot take the datapath down. It is also the engine a project's dedicated gateway needs.

A supervisor whose Cilium already runs the built-in Gateway API keeps it. Re-applying Networking never moves it to the other engine, and installs nothing for the gateway while Cilium's release cannot be read.

Over the API, Cilium's built-in engine is still available: send `gatewayApi: true` with the Cilium install. `POST /api/supervisors/{name}/networking/cilium-feature` with the feature `gatewayApi` turns it on or off on an installed supervisor. Turning it on is refused with `409` while Envoy Gateway owns the Gateway API CRDs. Turning it off takes down the shared Gateway it serves, so move that Gateway's routes first.

> [!NOTE]
>
> Before release 1.232 the step offered a choice between Cilium's built-in engine and Envoy Gateway, and proposed Cilium's. Cilium's Ingress controller was also on by default then. It is now off for new supervisors, and supervisors that run it keep it.

The interface roles come first for a reason: the Cilium install defaults build their `devices` set from the interfaces you tag, and the storage tag is what Rook, LINSTOR and the NFS route automation use to find the storage subnet later. **Install Networking** stays disabled until all three declarations are saved: the interface roles, an address plan with a block and its **Project LB**, **VM identity** and **Egress** bands, and a routing plan.

**Result:** Cilium reaches Ready, and steps 3 through 10 unlock.

### 4. Storage

One step over a catalogue in three families — **software-defined** (LINSTOR, Rook-Ceph and others built from the nodes' own disks or a shared LUN), **arrays** (a vendor CSI driver carving volumes externally), and **NFS**. Picking a family narrows the list; picking a backend renders its own parameters, including a disk picker wherever it consumes raw devices. The CSI snapshot controller arrives with the first Rook-Ceph or catalogue backend. The **NFS server** card does not install it.

Anything that consumes raw disks depends on the Omni-backed inventory — see Omni, above. That is not only the Ceph path: the same disk table feeds every backend that picks devices.

**Result:** a StorageClass that binds. Test it before moving on. The **NFS server** card has **Run smoke test**. For any other backend, use the [test-PVC diagnostic](https://docs.celum.io/storage/classes-and-profiles.md#the-test-pvc-diagnostic) or `test_storage_class`. The same class then satisfies the gate that Monitoring waits on.

### 5. Certificates

cert-manager plus one ClusterIssuer, of the type you pick:

* **Appliance CA**: certificates are signed by the appliance's OpenBao under the appliance CA, so every client that trusts the appliance trusts this cluster's routes too. It signs in through the auth mount the Secret Store step creates, so that step has to be done first.
* **Let's Encrypt**: ACME, answering DNS-01 challenges through your DNS provider's API.
* **Self-signed**: a root CA generated on the cluster.
* **CA (import)**: a CA keypair of your own.
* **AD CS**: Microsoft Active Directory Certificate Services, through its Web Enrollment.

[Certificates](https://docs.celum.io/platform-health/certificates.md) covers each one and how to change the default issuer later. This step is what makes TLS work across the platform, and it is a hard prerequisite of the Cluster API step.

**Result:** an issuer reporting Ready, and the Cluster API step unlocks.

## The six you can

| Step | Take it when |
| - | - |
| **Secret Store** | you run Vault and want credentials stored once centrally rather than copied into every cluster. Skipping is supported; credentials are then written into the cluster, where they cannot be rotated or restored from anywhere else |
| **DNS Publishing** | you want published routes to become A records automatically. Skip if you publish DNS by other means |
| **Monitoring** | always, in practice — Prometheus, Grafana and Alertmanager, plus Loki, Alloy and the ClickHouse flow store, which are on by default and can each be turned off |
| **Virtualization** | you intend to run VMs on this supervisor, or to build KubeVirt-backed tenant clusters |
| **Cluster API** | you intend to spawn tenant clusters from this supervisor. Requires Certificates. The Talos on KubeVirt and Kamaji kinds also need Virtualization before their guests can start |
| **Flow Telemetry** | you want any of the Security surfaces — topology, sessions, forensics, policy coverage. They are all empty without it. Needs the ClickHouse store, which the Monitoring step installs and publishes on the supervisor's domain |

## Three surfaces, and where two of them stop

Onboarding is the least evenly covered area in the product, and pretending otherwise is how someone ends up scripting against a tool that does not exist. Measured against the tool table:

| Step | Dashboard | API | MCP |
| - | - | - | - |
| Source & Bootstrap | yes | yes | **partial** — registry sources, image registry, provenance, chart re-point, registry trust, cluster agent install; **not Flux**, which no tool installs |
| Networking | yes | yes | **partial** — interface roles and the address plan can be set, Cluster Mesh toggled (`set_cilium_feature`) and FRR-K8s installed (`install_frr_k8s`); the routing plan cannot be set, and neither Cilium nor the supervisor's Envoy Gateway can be installed |
| Secret Store | yes | yes | **yes** — install, Vault bootstrap (pasted or standing credential), configure, re-check |
| Storage | yes | yes | **partial** — catalogue backends can be listed, installed and probed (`install_storage_backend`), and disks read; Rook-Ceph and the NFS server cannot be installed, and disks cannot be erased |
| Certificates | yes | yes | **partial** — issuers can be listed and Celum's certificates moved onto the default issuer (`reissue_certificates`), but neither cert-manager nor an issuer can be installed |
| DNS Publishing | yes | yes | **yes** — install, check, status and the declared zone; zone reclaim (`pdnsZoneMode`) and record purge are left out on purpose |
| Monitoring | yes | yes | **partial** — stack (including Grafana SSO and alert routing), service monitors, Loki, Alloy, exporters; **not** the ClickHouse store the step also installs |
| Virtualization | yes | yes | **read only** — status (`get_component_status`), versions and the feature-gate catalogue (`get_kubevirt_platform`); installing it does not |
| Cluster API | yes | yes | **partial** — guest DNS and NTP (`set_onboarding_host_resolution`) and the vCenter certificate and registration have tools; the operator, the providers, the ClusterClasses and the add-on engine do not. Clusters can be created once the step has installed a ClusterClass |
| Flow Telemetry | yes | yes | **read only** — every flow query has a tool; enabling the pipeline does not |

So an assistant can carry a supervisor a long way, and cannot finish it: **Flux, Networking and Certificates are all required and none of them can be installed over MCP**, which means no supervisor can be onboarded end to end without the dashboard or the API.

Each step's Apply calls these endpoints:

| Step | Apply | Permission |
| - | - | - |
| Source & Bootstrap | `PUT .../onboarding/image-registry` and `PUT .../onboarding/registry-sources` for the declarations, then `POST /api/supervisors/{name}/flux/install` and `.../cluster-agent/install/helm` | `cilium:Apply` for the declarations; `supervisor:Onboard`, `supervisor:Bootstrap` |
| Networking | `PUT .../onboarding/interface-roles`, `PUT .../projects/config` and `PUT .../networking/routing-plan` for the declarations; `POST .../onboarding/networking/apply` (Cilium at once, then FRR-K8s and Envoy Gateway as a backend job); `POST .../networking/routing-plan/apply-bgp` once FRR-K8s is Ready | `cilium:Apply`, `project:Configure`; `cilium:Install`, plus `gateway:Create` when it installs Envoy Gateway |
| Secret Store | `POST .../external-secrets/install`, then `.../external-secrets/vault-bootstrap-ephemeral` and `.../external-secrets/configure` | `secrets:Install`, `secrets:Configure` |
| Storage | `POST .../storage/csi/{backend}/install` for a catalogue backend, `.../storage/rook/install` for Rook-Ceph, `.../storage/nfs/install` for the NFS server | `storage:InstallDriver` |
| Certificates | `POST .../certs/install` (cert-manager and the selected issuer, in one call) | `certs:Install` |
| DNS Publishing | `POST .../external-dns/validate`, then `.../external-dns/install` | `dns:GetStatus`, `dns:Install` |
| Monitoring | `POST .../monitoring/install`, `.../monitoring/loki/install`, `.../monitoring/alloy/install`, `.../clickhouse/install`, then `.../clickhouse/chi/apply` | `monitoring:Install` |
| Virtualization | `POST .../virt/install` | `virt:Install` |
| Cluster API | `POST .../capi/install`, then `.../capi/addons` and `.../capi/clusterclasses/install`; **What guest nodes inherit** saves on its own with `PUT .../onboarding/host-resolution` | `capi:Install`; `cilium:Apply` for the save |
| Flow Telemetry | `POST .../flow-pipeline/configure` | `monitoring:Install` |

## Verify

The wizard's own Installation Summary is the running answer, but it reads the same endpoints you can read yourself. Outside the wizard, the [supervisor overview](https://docs.celum.io/platform-health/supervisor-overview.md) is where onboarding's result lives: **Summary** lists the supervisor's Helm releases, and the **Storage**, **Monitoring** and **Cluster API** tabs show each component's state. Those tabs appear on every `talos` supervisor whose components you may read, installed or not, so a tab's contents tell you whether a step has run, not its presence.

Once every required step is applied, the onboarding page itself becomes a summary of the configuration as it stands, and makes no changes. **Change configuration** reopens the wizard.

![Platform Onboarding showing Supervisor onboarding completed with a Change configuration button, and Source & Bootstrap marked Configured with Flux and the cluster agent Ready](https://mintcdn.com/celum-e0119be0/sA7S2Ajgv1l2CH1V/images/get-started/onboarding-summary.png?fit=max\&auto=format\&n=sA7S2Ajgv1l2CH1V\&q=85\&s=71bc6c32e90ba501c32b81e6dc65990e)

An onboarded supervisor: the page states its configuration

The honest end-state check is a workload: a PVC that binds proves Storage, an issued certificate proves Certificates, and pod-to-pod traffic proves Networking. A green HelmRelease proves that Helm succeeded.

## There is no undo

Registration was undone by deleting a row. This is not.

> [!WARNING]
>
> **`recover-rollback` is not a rollback.** Every step carries one — `POST .../certs/recover-rollback`, `.../storage/rook/recover-rollback`, and so on — and the name invites exactly the wrong reading. It detects a HelmRelease stuck in a Flux rollback loop and forces it *forward*. It is idempotent and safe to press on a healthy cluster, where it reports `matched: false` and does nothing. It will never take a component back off.

Three components can genuinely be removed through the product: Monitoring (`DELETE .../monitoring/uninstall`), Flow Telemetry (`POST .../security/uninstall`), and the BGP engine on its own (`POST .../frr-k8s/uninstall`). DNS Publishing has a `purge`, offered when you delete the supervisor in **Settings → Kubeconfigs**. It removes the PowerDNS records it created, or the whole zone. It is the inverse of publishing rather than of installing, and it does nothing on a supervisor that did not publish through PowerDNS.

Everything else — Cilium, cert-manager, storage drivers, KubeVirt, the Cluster API operator, ESO, Flux itself — is removed by deleting its HelmRelease by hand, in the order that does not strand the rest. The Cluster API step does remove the providers and the ClusterClass of a tenant cluster kind you stop offering. It keeps the KubeVirt, vSphere and vCluster providers while a tenant cluster still references them. Plan onboarding on the assumption that it is one-way.

## What commonly goes wrong

| Symptom | Cause |
| - | - |
| The page renders one sentence and no wizard | the supervisor's label is not exactly `talos` |
| The Storage step shows an empty disk table | usually Omni, not an absence of disks. Check the response's `source` field |
| A step is locked and names Cilium, but Cilium looks fine | the gate is on the HelmRelease reporting **Ready**, not on it existing |
| Cluster API is locked after Cilium is Ready | cert-manager. The operator requires it, and the wizard says so |
| Monitoring is locked, and you do not run Vault | the Secret Store gate opens on its own when the backend holds no Vault credential — if it has not, the backend does hold one |
| Monitoring is locked while storage is plainly working | the Storage gate. On a release predating the catalogue-wide check it only recognised Rook, NFS and the Hitachi HSPC driver, so any other backend left it shut |
| Flow Telemetry's Apply stays disabled | ClickHouse is not installed or not published. Run Monitoring with **Enable ClickHouse** on, on a supervisor with a domain |
| Next is disabled and the stepper will not move | a step is reconciling. Navigation is frozen until it settles |
| A step shows an error you cannot clear, with a notice about status | the *status read* was refused, not the install. The wizard refuses to vouch for a step it cannot read, but still lets you advance past it |
| Charts install from public upstreams despite a declared mirror | they were installed **before** the declaration. A source is written once and never revisited |

## Next

> [card] [Projects](https://docs.celum.io/concepts/projects.md)
>
> Carve the supervisor you just onboarded into tenant slices — a namespace plus its own address space.

> [card] [Create a cluster](https://docs.celum.io/clusters/create.md)
>
> Spawn a tenant cluster. Needs the Cluster API step.

> [card] [Storage overview](https://docs.celum.io/storage/overview.md)
>
> Choosing a backend from the catalogue, and the triage order for a Pending claim.

> [card] [Security overview](https://docs.celum.io/security/overview.md)
>
> What Flow Telemetry feeds, and how to tell an empty view from a quiet network.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.