Skip to main content
This page lists every option in Platform Onboarding, in stepper order. Platform onboarding explains why the steps come in this order and what gates each one. Read that page first. Each table gives the label you see in the dashboard and, in brackets, the field in the request body. Each section ends with the API routes and MCP tools that do the same thing. If no MCP tool exists, the section says so.
A route written as .../x means /api/supervisors/{name}/x. Several routes replace the whole configuration with the body you send, so a field you leave out goes back to its default. The sections say which routes do this. For those routes, read desired from the step’s status route, change what you need, and send the whole body back. Permissions lists every IAM action named below.

Source & Bootstrap

This step records where the supervisor pulls charts and images from. It then installs Flux and the cluster agent from that source. Registries covers registering a registry. Registry mirroring in depth shows where each declaration reaches. The three declarations below are written to the supervisor’s NuviraClusterConfig named default. To see them, run kubectl get nuviraclusterconfig default -o yaml. Writing any of them needs cilium:Apply on the supervisor, not supervisor:Onboard.

Container image registry mirror

This section makes the nodes’ containerd pull public registries through a local Harbor proxy cache. Celum writes the declaration into an Omni ConfigPatch that Celum owns. Talos then reloads containerd without a reboot.
The PUT replaces the whole declaration. A body without skipFallback turns strict air-gap off. A body without an upstream drops that upstream. Send every field you mean to keep.
To remove the mirror, send a PUT with an empty mirrorHost and no upstreams. The dashboard cannot do this, because Save & apply stays disabled while the host is empty. On a Celum appliance. When this section loads for a supervisor with no declaration, Celum declares the mirror from the appliance. The host is the appliance’s Harbor, and the rows are only the proxy projects that Harbor serves. Registering the supervisor triggers the same attempt. Celum does this once per supervisor and never overwrites a declaration you saved. After your first save, or after you clear the mirror, Celum does not declare it again. If the appliance runs with air-gap mode strict and your declaration is not strict, the section shows a warning and leaves your declaration unchanged. You set the appliance’s air-gap mode when you deploy it. See Deploy the appliance and Appliance configuration. API: PUT /api/supervisors/{name}/onboarding/image-registry (cilium:Apply). Read it with GET on the same path (cilium:GetDefaults). POST .../onboarding/image-registry/from-appliance (cilium:Apply) declares the mirror from the appliance. GET /api/appliance/posture (registry:List) reads the appliance’s posture. MCP: set_onboarding_image_registry, get_onboarding_image_registry, declare_onboarding_image_registry_from_appliance, get_appliance_posture.

Platform Registry Sources

This section chooses the registered registry that serves this supervisor’s platform charts. Only the registry’s name is stored on the cluster. Its credentials stay in Celum’s catalogue. With nothing declared, a supervisor uses its site’s default registry. Next it uses the estate-wide default, and then each chart’s public source. Charts & the mirror gives the full order. The cluster agent chart has no public source. If no registry resolves for Celum’s own charts, Celum uses a registry address built into Celum. So register the registry that holds Celum’s charts before you install this step. A saved choice changes where later installs pull from. It does not move a release that is already installed. To move one, use Re-point under Registry provenance (audit), below.

Additional registries

This section declares registries that your own workloads pull from, typically a private registry for application images. It does not change where the platform installs from. API: PUT /api/supervisors/{name}/onboarding/registry-sources (cilium:Apply) with charts, images and additional. Read it with GET on the same path (cilium:GetDefaults). MCP: set_onboarding_registry_sources, get_onboarding_registry_sources.
The PUT replaces all three fields. A body without additional removes every additional registry. An empty charts or images returns that role to the default. Always send all three fields together.

Where credentials will be stored

This is a read-only table. For each of the eight credentials that onboarding asks for, it compares two places: a central secret store, and this cluster only. See Secret Store.

Flux and the cluster agent

The step card is titled Platform Prerequisites. Its one action installs both components, in order. API: POST /api/supervisors/{name}/flux/install (supervisor:Onboard), then POST .../cluster-agent/install/helm (supervisor:Bootstrap) with an optional chartVersion. MCP: no tool installs Flux, so use the API. get_flux_version names the Flux release that Celum installs. For the agent, use install_cluster_agent_helm. upgrade_supervisor_cluster_agent (POST .../cluster-agent/upgrade) moves both the agent’s chart and its image.
POST .../cluster-agent/install (MCP install_cluster_agent) is a different route. It applies a bare agent without Flux, to diagnose a supervisor that has no Flux. The wizard does not use it.

Registry provenance (audit)

This panel reads what the nodes and the Flux objects actually use, not what you declared. It offers three repairs. To read the panel, use GET .../onboarding/registry-provenance (cilium:GetDefaults) or get_onboarding_registry_provenance.

Networking

The step has two halves. First you declare three things: what each node interface is for, how the supervisor’s address block splits into bands, and how the physical network reaches that block. Then one button installs Cilium, then FRR-K8s if you peer over BGP, then Envoy Gateway as the North-South gateway. The declarations are written to the supervisor’s NuviraClusterConfig. They work before Flux and Cilium exist. Install Networking stays disabled until all three are saved: the interface roles, an address plan with a block plus the Project LB, VM identity and Egress bands, and a routing plan. The footer names the ones still missing. Networking overview explains the engine model.

Declare interface roles

This table shows every L3 interface the nodes report, with one column per role. Detection fills in the table, but nothing is declared until you press Save interface roles. The siderolink row is the management tunnel to Omni and cannot take a role. If no interfaces are listed, install the cluster agent first (in Source & Bootstrap) or wait for topology discovery. One interface can carry several roles. Detection pre-ticks roles as follows:
  • The interface with the node InternalIP or the default route gets primary and BGP.
  • An interface already in Cilium’s devices pattern gets pod-overlay.
  • An interface with an MTU of 8000 or more, and no other role, gets storage.
The node-IP interface is always in Cilium’s devices set, whether you tag it or not. Saving an empty map clears the declaration, and later steps go back to inferring. API: PUT /api/supervisors/{name}/onboarding/interface-roles (cilium:Apply), with a body such as {"interfaceRoles": {"eth0": ["primary", "bgp"], "eth1": ["storage"]}}. Read it with GET on the same path (cilium:GetDefaults). MCP: set_onboarding_interface_roles. To read it, use get_onboarding_prerequisites with view=interface-roles.

Required networks

The panel shows two detected values that you cannot edit:
  • Cluster Pod CIDR comes from the Talos configuration through Omni, or from the pod CIDRs assigned to the nodes.
  • Service CIDR is the ClusterIP range, fixed when the cluster was created.
A warning appears when the running pod network differs from spec.pools.podSupercidr in the NuviraClusterConfig. The address plan does not set the pod network, because Cilium owns it. Under Product address plan, you declare one block and four bands inside it. The cluster checks three rules: every band sits inside the block, no two bands overlap, and the slice masks fit. It refuses a plan that breaks a rule. Projects explains how projects draw from these bands. Pools & IPAM shows what is allocated from them. When you type a block between /12 and /26, the panel proposes all four bands and both slice masks, always within the bounds above; the panel flags a mask you type outside them before you save. It stops proposing as soon as you edit a band, or when a saved plan loads. For example, for the block 198.51.100.0/24 the proposal is:
  • Project LB 198.51.100.0/25 at /29 (16 projects)
  • VM identity 198.51.100.128/26 at /29 (8 slices)
  • Egress 198.51.100.192/27
  • Platform LB 198.51.100.224/27
The honeypot then takes 198.51.100.192.
On a supervisor that already runs the pool, changing Platform LB moves the live service-pool. It also re-pins every LoadBalancer Service that was pinned to the old band, including the shared gateway VIP. Each address keeps its offset inside the band. After the move, a DNS record that points at the old VIP is wrong. Moving the band needs cilium:Apply, plus gateway:Create when a Service is re-pinned. Without cilium:Apply, the wizard saves the rest of the plan and tells you that the band did not move.
Under the plan, DNS records this platform will need lists the names that Grafana, Prometheus and ClickHouse answer on. Each name needs an A record that points at the shared gateway VIP. See Service DNS records. API: PUT /api/supervisors/{name}/projects/config (project:Configure). To move the band, send platformLb in the same body. Read the plan with GET on the same path (project:GetConfig). MCP: configure_project_networking. To read it, use get_project_networking_config. To see free space, use get_address_plan.

Routing

Declare how the physical network reaches the block. Nothing is pre-selected, and Save routing plan stays disabled until you choose a type. Route the whole block as one destination, with one equal-cost next hop per node. Project LB, Platform LB and VM identity addresses are advertised from every node. Each egress address is advertised from exactly one node, and its more specific route wins. Each node peers from its address on the interface tagged BGP. With no BGP tag, it uses the primary interface. Celum falls back to the node InternalIP only when no interface roles are declared. Where the MD5 password goes depends on the Secret Store step:
  • If this supervisor’s secret store is connected, the password goes to the store when you save. An ExternalSecret then creates the Secret when the BGP configuration is applied.
  • If not, Celum keeps the password in a Secret in kube-system and moves it into frr-k8s-system when it applies the configuration. The password then exists only on this cluster.
  • If a store becomes available later, the next BGP apply moves the password into it. Peering drops for a few seconds while the Secret is replaced.
  • If MD5 is on and there is neither a store nor a stored password, the apply answers 409.
The wizard creates onboarding-routing from the browser, while the Networking step is open. The backend’s Networking apply installs FRR-K8s but does not create this configuration. If you onboard a supervisor through the API, call POST /api/supervisors/{name}/networking/routing-plan/apply-bgp after FRR-K8s is Ready.
API: PUT /api/supervisors/{name}/networking/routing-plan (cilium:Apply) saves the plan to spec.bgp in the NuviraClusterConfig. GET on the same path (cilium:GetState) returns the plan with the device table. POST .../networking/routing-plan/apply-bgp (cilium:Apply) creates the FRRConfiguration. MCP: no tool for the routing plan, so use the API. update_frr_k8s_config writes an FRRConfiguration directly. That is the BGP & Egress path, not this declaration.

Cilium CNI

Under the table, the card shows the routing device. This is the one interface you declared primary, which Celum pins as Cilium’s direct-routing device. If no interface is declared primary, the install fails with unable to determine direct routing device. To fix this, change Declare interface roles above, not this card. Celum also derives Cilium’s devices set; you do not type it. The set holds every interface tagged primary or pod-overlay, plus every interface that carries a node IP. The install refuses a devices set that leaves out an interface carrying a node IP.
Celum does not join Cluster Mesh peers. No screen, API route or MCP tool writes a peer: the toggle leaves clustermesh.config.clusters empty. To connect this cluster to another one, you work outside Celum.
When Cilium reports Ready, Celum creates the platform LoadBalancer pool service-pool. Once a GatewayClass exists, it also creates the shared Gateway shared-gateway. It creates each one only if it is absent. See Gateways & Routes. API: POST /api/supervisors/{name}/cilium/install (cilium:Install) is the Cilium card’s own Re-apply chart button. Cluster Mesh is POST .../networking/cilium-feature with {"feature": "clusterMesh", "enabled": true} (cilium:Apply). MCP: no tool installs Cilium. set_cilium_feature turns Cluster Mesh on or off. To see what an install would use, use get_cilium_config with view=install-defaults, or get_cilium_install_preview.

Cilium values the form does not show

These values come from the platform defaults. You can change them only through the API, in values in the Cilium request body. A re-apply keeps the live egressGateway, clustermesh, hubble, localRedirectPolicies, gatewayAPI and ingressController blocks of the running release. So it does not undo a feature that was switched since. Every Cilium install also labels kube-system for privileged pods. POST .../cilium/install/validate (cilium:GetDefaults) checks a Cilium body without applying it. It checks the routing mode, the tunnel protocol, the LB mode, the IPAM mode, the API server host and port, and the pod CIDR. It does not check the Cluster ID. The wizard has no button for it, and no MCP tool calls it.

BGP engine

The install also turns on the cluster agent’s bridge, which writes the advertised prefixes into the FRRConfigurations. If you install FRR-K8s before the Monitoring step, Prometheus does not scrape it. Re-apply FRR-K8s after Monitoring to add the scrape. To add peers beyond the routing plan, see BGP & Egress. API: POST /api/supervisors/{name}/frr-k8s/install (cilium:Install), with the body {"chartVersion": "..."}. MCP: install_frr_k8s.

Gateway (North-South)

This section appears when Envoy Gateway is the North-South engine. It is hidden on a supervisor that runs Cilium’s built-in Gateway API. If both engines are active, the section reports a conflict. The Envoy Gateway install answers 409 while Cilium’s built-in Gateway API is on. Otherwise it runs these steps, in order:
  1. Applies the Gateway API CRD bundle.
  2. Removes the safe-upgrades.gateway.networking.k8s.io ValidatingAdmissionPolicy and its binding, because that policy blocks the experimental-channel CRDs that Envoy Gateway needs.
  3. Creates the envoy-gateway GatewayClass.
API: POST /api/supervisors/{name}/gateway/envoy/install (gateway:Create), with the body {"chartVersion": "...", "proxyMode": "daemonset"}. MCP: no tool installs Envoy Gateway on a supervisor, so use the API. install_guest_envoy_gateway installs it in a tenant cluster, not on the supervisor.

Service DNS records

After Cilium reports Ready, a read-only box, Service DNS records (read-only), lists the platform-service host names to publish as A records. Each name points at the shared gateway’s address. Until the gateway is programmed, that address is predicted from the platform LoadBalancer pool. After that, it is the live address. The box also says whether each name resolves from the Celum backend. The DNS Publishing step can create the records, or you can create them by hand. To read the box, use GET .../onboarding/required-dns (cilium:GetDefaults), or get_onboarding_prerequisites with view=required-dns.

What Install Networking does

Install Networking (or Re-apply Networking once the Cilium release exists) sends one request, POST /api/supervisors/{name}/onboarding/networking/apply. The request carries the body of each install it runs. An engine left out of the body is not installed.
  1. Celum applies Cilium at once. If Cilium is refused, the refusal comes back to the click and nothing else runs.
  2. The rest runs as a job on the backend. The job waits up to 15 minutes for the Cilium HelmRelease to be Ready for its latest generation. After 15 minutes it continues anyway, and Flux keeps reconciling. It then creates the platform pool and the shared gateway, installs FRR-K8s, and installs Envoy Gateway. It stops at the first failure and marks the later stages as not attempted.
  3. After every stage, the job writes its state to the ConfigMap kube-system/celum-networking-apply, so a page reload shows the same progress. After a backend restart, Celum resumes a job that was last updated within 30 minutes and marks an older one as abandoned.
  4. A second request for the same supervisor while a job runs gets 409.
  5. Each stage writes its own audit entry, networking-apply: followed by the stage name, under the identity of the person who clicked.
The request needs cilium:Install. If it carries envoy, it also needs gateway:Create on supervisor:{name}:gateway:*. Celum checks this before it applies anything. To read the job, use GET .../onboarding/networking/apply (cilium:GetState).

Secret Store

This step installs External Secrets Operator (ESO) and connects it to Vault. Credentials that later steps ask for are then stored once in Vault, not only on the cluster. The step is optional. Without it, every credential is written as a plain Secret on the cluster. If you connect a store later, Celum moves those credentials to Vault on its own. The step stays locked until Cilium reports Ready.

External Secrets Operator

After the release reports Ready, the panel shows CRDs served and admission webhook callable until ESO can accept a store. The webhook comes up some minutes after the release. API: POST /api/supervisors/{name}/external-secrets/install (secrets:Install). MCP: install_external_secrets.

Connect to Vault

You paste a bootstrap AppRole. Celum uses it for one call and never stores it. The audit log redacts secretId. <kv-mount> is VAULT_KV_MOUNT, which is celum by default. The backend must have VAULT_ADDR set, or Celum refuses the connection. Two checks then run on their own. Vault authentication checks that ESO logged in to Vault. Secret read checks that ESO read the canary under this supervisor’s prefix. The step is done when both checks pass.
If the backend holds no Vault credential, the step says The backend cannot write to Vault yet, and Secret read cannot pass. The step then stops blocking Monitoring. See Environment variables for SECRET_BACKEND, VAULT_ROLE_ID and VAULT_SECRET_ID.
API: POST /api/supervisors/{name}/external-secrets/vault-bootstrap-ephemeral with roleId and secretId, then POST .../external-secrets/configure (both secrets:Configure). The bootstrap body also takes vaultAddr, which the dashboard does not offer. POST .../external-secrets/vault-bootstrap makes the same Vault writes with a bootstrap credential kept on the backend (VAULT_BOOTSTRAP_ROLE_ID). The dashboard does not use it. MCP: bootstrap_vault_ephemeral, configure_external_secrets and bootstrap_vault. To run the checks again now, use reconcile_external_secrets. To read the runbook, use get_external_secrets with view=vault-setup or view=ca-cert.

Storage

The step installs one storage backend from a catalogue, plus the StorageClass that makes it usable. Storage overview explains how to choose a backend. Rook-Ceph, LINSTOR and NFS & Fibre Channel cover each backend in depth. This section lists only what those pages do not.

Storage backend

You can install these cards today: Every other card is Preview. To get the current catalogue, with preview and unavailable for each row, use GET .../storage/csi/backends or list_storage_backends.
Celum reads loaded kernel modules through Omni. If Omni is not configured, or a node does not answer, the card stays selectable and shows the requirement as a warning.

Catalogue backend form

These rules apply to every card except Rook-Ceph and NFS server. The two array cards ask for these parameters: Each card names its class after its catalogue key, for example hpe-csi-alletra-nimble. Both cards install the driver as one HelmRelease, hpe-csi-driver, so a supervisor can have both. On a supervisor with Talos nodes the install uses Celum’s Talos build of the driver and accepts only chart 3.3.0. A Hitachi VSP has no card: its LUNs go under LINSTOR or Ceph, as NFS & Fibre Channel describes. LINSTOR covers LINSTOR storage pool, Disks, Replicas, Shared array LUN and Default StorageClass. The form also asks for these parameters: Disks and Shared array LUN are pickers over the live disk inventory. The Shared array LUN picker lists only LUNs that every node can see. A LUN that some nodes cannot see appears, but you cannot select it.
LINSTOR does not erase disks when it installs. If a selected disk still has a filesystem or an old signature on it, press Erase now in the disk picker before Install. To erase every selected disk, turn on Also erase disks that look empty. Erasing cannot be undone. It needs storage:InstallDriver, the same permission as the install.
API: GET /api/supervisors/{name}/storage/csi/backends (storage:GetStatus) lists the catalogue. POST .../storage/csi/{backend}/install (storage:InstallDriver) installs a row, with the body {"params": {...}}. POST .../storage/disks/wipe (storage:InstallDriver) erases disks. MCP: list_storage_backends, install_storage_backend, get_storage_backend_status, get_storage_disks. No tool erases disks.

Rook-Ceph

Rook-Ceph covers the disk inventory, the wipe, the SAN device class and the cluster shape. The panel also has these options: The step’s apply stays disabled until you select at least one OSD disk. On a re-apply, Celum asks you to confirm any change that reduces capacity or redundancy. These changes are: turning off a pool, lowering Replica Count, changing Failure Domain, or changing a network. API: POST /api/supervisors/{name}/storage/rook/install (storage:InstallDriver). MCP: no tool installs Rook-Ceph, so use the API. get_storage_disks and get_ceph_discovery read the disk inventory.

NFS server

NFS & Fibre Channel covers the fields. These details differ from what that page says or implies:
The NFS server card does not install the CSI snapshot controller. Rook-Ceph and the catalogue backends do. On a supervisor whose only storage is NFS, install the controller with POST .../snapshot/install (virt:Install). No dashboard control or MCP tool does this.
API: POST /api/supervisors/{name}/storage/nfs/install (storage:InstallDriver) and POST .../storage/nfs/test-pvc (storage:Test). MCP: no tool installs the NFS driver, so use the API. test_storage_class tests any class.

Test a class from any backend

Only the NFS server card has a test button. For any other backend, use the test-PVC diagnostic: POST .../storage/test-pvc (storage:Test), or test_storage_class.

Certificates

The step installs cert-manager and one issuer with a single apply. Certificates explains which issuer signs a certificate and how to manage issuers later.

Issuer type

cert-manager controller

Let’s Encrypt

Self-signed

This tab has no fields. The apply creates three things:
  • a bootstrap ClusterIssuer, selfsigned-bootstrap;
  • a root CA certificate, valid for 10 years;
  • a CA ClusterIssuer that signs from that root.
The root’s common name is the supervisor domain. If the supervisor has no domain, it is k8s-gate self-signed root. The key pair is stored in the cert-manager-ca-keypair Secret.

CA (import)

The pair is stored as the cert-manager-ca-keypair TLS Secret.

AD CS

The apply installs the adcs-issuer chart and creates a ClusterAdcsIssuer.

Appliance CA

This tab has no input fields. It shows the names this supervisor may get certificates for: its domain and the zone declared in the DNS Publishing step, each with its subdomains. It also shows the chain that every certificate carries. cert-manager sends each request to the appliance’s OpenBao, which signs it. The CA key never enters the cluster. The apply needs all of the following. If one is missing, the apply fails with an error that names it.
  • The Secret Store step is done. cert-manager signs in through the auth mount that step creates.
  • VAULT_ADDR is set on the backend.
  • The bootstrap credential is set: VAULT_BOOTSTRAP_ROLE_ID and VAULT_BOOTSTRAP_SECRET_ID.
  • VAULT_BOOTSTRAP_ALLOW covers this supervisor.
  • The supervisor has a domain, or a zone declared in the DNS Publishing step.
In OpenBao, the apply writes a PKI role, a sign-only policy and a Kubernetes-auth role. Certificates are valid for at most 90 days. In the cluster, the apply creates the celum-pki-issuer ServiceAccount, the RBAC it needs, and the ClusterIssuer. The PKI mount is VAULT_PKI_CLUSTERS_MOUNT, which is pki-clusters by default. See Environment variables.

ClusterIssuer

If the Secret Store step is connected, Celum writes the DNS tokens, the imported CA and the AD CS credential to the secret store. If not, it writes them as Secrets in the cert-manager namespace. On a re-apply, Celum asks you to confirm some changes before it sends them: another issuer type, another ACME email, another ACME server, another DNS provider, or a new issuer name. Certificates that are already issued keep serving. Their renewal moves to the new issuer. With a new issuer name, renewal stops. API: POST /api/supervisors/{name}/certs/install (certs:Install) installs cert-manager and the selected issuer in one call. Later, POST .../certs/issuers (certs:Install) adds more issuers. MCP: no tool installs cert-manager or an issuer, so use the API. list_cluster_issuers and get_certificates read the result. reissue_certificates moves existing certificates to the default issuer.

DNS Publishing

The step installs external-dns into the external-dns namespace as a Flux HelmRelease. external-dns reads two fixed sources: the supervisor’s Gateway API HTTPRoutes, and Services that carry the external-dns host name annotation. Routes published from tenant clusters get their records through the second source. The step is optional. Publish it on a public name shows what a missing record looks like. Under Settings → Domains, you register a PowerDNS server once, for every supervisor.

DNS backend

When a zone already holds another owner’s records

With PowerDNS, the check lists each zone that holds external-dns records from a different owner, usually a deleted cluster. external-dns does not overwrite those records, so the names keep their old addresses. The first time the step finds such records, it stops and asks you to choose one of the options below. To continue with your choice, press the action again.

Zones (domain filters)

An empty list lets external-dns write into every zone it can reach. If the list does not cover the host names you publish, the release is Ready but writes no records.
The records carry an owner ID (txtOwnerId). The step shows it, but you cannot change it there. Over the API, an empty txtOwnerId takes the owner from the declared zone. If there is none, it takes the owner from the running release, and then the supervisor name. A new owner ID orphans every record written under the old one.

Advanced values (optional)

Run the step

Test connection checks a PowerDNS server: the URL rules, the key, and the zone conflicts. It changes nothing. For any other provider, it reports that there is nothing to probe. The step’s action runs the same check, then applies these objects in order: the external-dns namespace, the provider Secret, the CA ConfigMap (PowerDNS only), the HelmRepository, and the HelmRelease. Celum then creates any missing PowerDNS zones. Last, it writes the zone, owner and server it used back to the supervisor’s NuviraClusterConfig (spec.dns). API: POST /api/supervisors/{name}/external-dns/validate (dns:GetStatus), then POST .../external-dns/install (dns:Install). The install body replaces the release values. So read desired from GET .../external-dns/status, change it, and send it back. MCP: validate_external_dns, install_external_dns, get_external_dns_status. The MCP tool leaves out pdnsZoneMode, because reclaiming a zone is a decision for the dashboard.

Declare the zone without installing

Before the step runs, you can declare which zone a supervisor owns and which server is authoritative for it. An install fills every empty field from this declaration. The step shows the declared zone, but has no field to change it. API: PUT /api/supervisors/{name}/onboarding/dns-zone (dns:Install). MCP: set_onboarding_dns_zone. To read it, use get_onboarding_prerequisites with view=dns-zone. Dashboard: none.

Remove the records

When you delete a supervisor under Settings → Kubeconfigs, the dialog offers two choices. Remove PowerDNS records deletes the records owned by the supervisor’s name in each filtered zone. Delete zone deletes those zones. Neither one does anything on a supervisor that did not publish through PowerDNS. API: POST /api/supervisors/{name}/external-dns/purge?mode=records or ?mode=zone (dns:Install). MCP: none. This is deliberate: no MCP tool deletes data.

Monitoring

The step installs kube-prometheus-stack (Prometheus, Alertmanager and Grafana) as a Flux HelmRelease in the monitoring namespace. With it come the platform ServiceMonitors, the Celum Grafana dashboards, and routes for Grafana, ClickHouse and the Prometheus push path on the shared Gateway. The same step also installs Loki, Alloy and the ClickHouse flow store. Each one has its own toggle, and each is on by default. The step waits for Networking, Storage and Certificates, and for the Secret Store gate. Monitoring and Logs cover the running stack.

Storage and retention

Alerts

Alertmanager groups alerts by cluster, namespace and alert name. It waits 30 seconds before the first message, and repeats an unresolved group every 12 hours. A critical alert suppresses the warning and info alerts of the same name. A crash-looping pod suppresses its not-ready and container-waiting alerts.
Set ALERT_WEBHOOK_URL on only one Celum for each set of supervisors. If two Celum installations both set it, each one takes the other’s alerts. Celum posts through its Slack app, so you must configure Slack notifications. Without Slack, Celum accepts the alerts and drops them. See Environment variables.

Grafana SSO

With Platform client or Backend’s client, if a private CA signed the identity provider’s certificate, Celum gives Grafana that provider’s root CA, in the Secret grafana-oidc-ca.

Logs

Loki is always multi-tenant, with a tenant for each project and one for the supervisor; Logs lists where each writer’s logs land. The Loki install no longer takes auth. On a supervisor that still runs Loki’s retired NGINX auth, a Loki apply turns that gateway off, deletes the Secret monitoring/loki-credentials and each namespace’s alloy-loki-auth delivery of it, and points the Loki route at the loki Service. The route then requires each project’s push credential once every guest sends it; see The push credential.
The first Loki apply on a supervisor deletes, for good, the logs Loki kept from before it was multi-tenant (tenant fake). See Logs from before tenancy.

ClickHouse (flow observability storage)

This is the store that every Security view reads, and Flow Telemetry needs it. With Enable ClickHouse on, the Monitoring apply installs the Altinity clickhouse-operator into clickhouse-system. When the operator is Ready, the step applies the ClickHouseInstallation into the security namespace, without another click. The Monitoring apply also publishes ClickHouse on the shared gateway as clickhouse.<your domain>. It skips that route, with a note in the install log, if the supervisor has no domain, no shared gateway or no ClusterIssuer. The API also takes shards, from 1 to 8, default 1. The form does not show it.

Advanced (Prometheus and ServiceMonitors)

Components installed after this step (KubeVirt, Cluster API, Kamaji, Tetragon) apply their own ServiceMonitors.

Run the step

The step’s action applies kube-prometheus-stack only if one of its settings or the alert toggle changed. It then applies Loki, Alloy and ClickHouse together, each one only if it is on. If the kube-prometheus-stack apply fails, the rest does not run. The kube-prometheus-stack apply removes the prometheus-write NodePort Service (31090) that earlier releases wrote, and ends with the push-credential rows: every project’s telemetry push credential, the push routes’ requirement of it, the policy that leaves those routes the only way to Prometheus and Loki from outside monitoring, and the closing of the Loki port 8080 in project policies. When kube-prometheus-stack has nothing to change, the action runs the NodePort removal and those rows on their own, last. Monitoring describes them. API: POST /api/supervisors/{name}/monitoring/install, .../monitoring/loki/install, .../monitoring/alloy/install, .../clickhouse/install, then .../clickhouse/chi/apply when the operator is Ready. .../monitoring/telemetry-credentials runs only the Prometheus route, the NodePort removal and the push-credential rows. All of them need monitoring:Install. Each install body replaces that release’s values. Read desired from the matching status first, change it, and send it back. alertRouting is the exception: leave it out to keep the current routing. MCP: install_monitoring, install_loki, install_alloy, install_service_monitors, install_exporter, and get_component_status to read the state. No tool installs ClickHouse, so use the API. No tool runs the push-credential rows alone: install_monitoring runs them at the end of its apply. get_component_status with component=clickhouse reads its state, and get_flow_store_instance describes the installation.

Virtualization

This step installs KubeVirt and, if you keep it on, CDI. On a new supervisor, both come from the platform’s own charts, as the HelmReleases kubevirt/virt-kubevirt and cdi/virt-cdi. The step also does these things:
  • labels the kubevirt and cdi namespaces as privileged;
  • pins the KubeVirt and CDI control-plane pods (not the VMs) to control-plane nodes;
  • adds two KubeVirt dashboards to Grafana.
The step unlocks when Cilium is Ready. For what you do with it afterwards, see Image library and Create a VM.

Release panels

Components

Feature gates

This section is collapsed. Open it only to change a gate. Two gates need care on Talos:
  • KubevirtSeccompProfile is a default gate. The passt VM network mode needs it on Talos. If you turn it on for an installed supervisor, restart virt-handler afterwards. Also set the node sysctl user.max_user_namespaces above 0 (see Run a VM).
  • PersistentReservation is marked Talos-incompatible. Leave it off on Talos: its sidecar needs a writable /etc/multipath, and without one virt-handler crash-loops.

KubeVirt controller

CDI configuration

A supervisor whose KubeVirt was installed from GitHub release manifests stays on that delivery path, and the step says so above the panels. On that path, the apply fetches the manifests from github.com, so it needs internet access. It also ignores Host device passthrough and Upload proxy URL. Moving such a supervisor to the charts replaces what owns the KubeVirt operator. That is a migration, not a re-apply.
If the KubeVirt or CDI resource stays in a phase other than Deployed or Deploying, the step shows Operator stuck with Restart operator + capture logs. This action restarts the operator pod and shows its last log lines. It calls POST .../virt/recover-rollback (virt:Install). API: POST /api/supervisors/{name}/virt/install (virt:Install), with the body fields named above. Send "viaCharts": true. If you leave the field out it is false, which selects the GitHub-manifest path. An empty featureGates list installs the default gates. MCP: no tool installs Virtualization, so use the API. get_component_status with component=virt reads the step’s state. get_kubevirt_platform lists versions (view=versions, source=kubevirt or cdi) and the gate catalogue (view=feature-gates). get_chart_versions lists the chart versions that the panels offer.

Cluster API

This step installs four things: cluster-api-operator; the Cluster API providers that your tenant cluster kinds need; the ClusterClasses those kinds create clusters from; and the CAAPH engine, which delivers add-ons into guest clusters. It also holds the DNS and NTP servers that guest nodes inherit. It stays locked until Certificates is done, because cluster-api-operator needs cert-manager. Clusters overview describes the engine that this step installs. Create a cluster describes what you build with it. The step is done when all of these are true:
  • the operator release and the core provider are Ready;
  • at least one tenant cluster kind is offered;
  • every offered kind can create a cluster;
  • the add-on engine is Ready, if it is installed.
One button applies the whole step: Install Cluster API on a new supervisor, Re-apply Cluster API after that. It sends up to three requests, in this order:
  1. POST /api/supervisors/{name}/capi/install installs the operator release, waits for its CRDs and webhook, then applies the providers.
  2. POST .../capi/addons installs the add-on engine. It is sent only when Enable guest add-on engine (CAAPH) is on.
  3. POST .../capi/clusterclasses/install renders the ClusterClasses. It is sent when at least one kind is offered, or when the ClusterClass release already exists.
If the operator is not up in time, the first request answers 202, and the step log tells you to apply again when the operator reports Ready. The add-on and ClusterClass requests then wait for that next apply. The button stays disabled until the step has read what is installed. Otherwise an apply would send the defaults over a configured supervisor. If a change removes a provider or a ClusterClass, a confirmation lists what will be removed before anything is applied.

Core providers

These four are always installed, whichever kinds you offer. Each panel’s own button applies the whole step with the version you picked, through the same request as the step’s button.
On a new supervisor, the step installs every provider from Celum’s own capi-provider-* charts, so nothing is fetched from GitHub at install time. A supervisor whose providers were installed as direct Provider CRs stays on that delivery path. Its panels then show operator state, and a line under Core providers says so. Moving such a supervisor to the charts is a migration, not a re-apply.

Cluster API feature gates

The step writes these gates to the core provider’s featureGates (coreFeatureGates). If the core provider does not recognise a gate, its controller does not start, even when the gate is set to off. That is why the step hides a gate from an older core instead of sending it as off.

Operator runtime

Tenant cluster kinds

Each card is a kind of tenant cluster that this supervisor offers. When you select a card, the next apply installs everything that kind needs: its providers and its ClusterClass. As soon as the step is done, the create form offers that kind. Each offered kind shows a ready or incomplete badge. Under the cards, the step lists what each incomplete kind still needs, for example a provider that is still installing, or a missing ClusterClass. When you clear a card, the next apply removes the kind’s ClusterClass and every provider that no remaining kind needs. Tenant clusters keep running. Celum keeps the KubeVirt, vSphere and vCluster providers while a tenant cluster still references them. Cluster API refuses to delete a ClusterClass that clusters use, and the ClusterClass release then reports the error. When a kind is selected, its provider panel appears under the cards:

vCenter credentials

These fields appear when Talos on vSphere is selected. If the Secret Store step is connected, typed credentials go to the secret store. If not, they go straight into the capv-system/vsphere-credentials Secret. After a successful apply, the step clears the typed user, password and thumbprint from the form. When typed credentials are installed, two more actions appear:
  • If Settings → vCenters already holds that vCenter, Use <name> and apply moves Cluster API to it, and the copy kept for this supervisor is cleared.
  • If not, Register for the platform registers it under a Name and an optional Description, from the credentials the supervisor already holds. It then moves Cluster API to it. The button is disabled until a thumbprint is pinned. It needs vcenter:Create and vcenter:Use on the new name.
While vSphere guest clusters run on the current vCenter, Celum refuses to point Cluster API at a registered vCenter with a different address. Under the credentials, a panel compares the certificate that vCenter serves now with the pinned thumbprint. If they differ and the credentials are typed, Pin this certificate moves the pin. If the supervisor takes its credentials from a registered vCenter, you re-pin under Settings → vCenters instead. See Settings.

Tenants

Each vSphere tenant renders one talos-vsphere-<name> ClusterClass with fixed placement. When you create a cluster, picking that class picks the tenant, so the create form does not ask for a datacenter or a network. The pickers list what the vCenter holds. If the inventory cannot be read, each picker becomes a text field. The apply refuses a row that has some fields filled and others empty, so Celum never drops a half-written tenant without telling you. When you remove a complete tenant, the next apply removes its ClusterClass, after a confirmation.

ClusterClasses

What guest nodes inherit

Celum writes these values into each guest node’s Talos machine config when it provisions the node. They apply to guest nodes, not to guest workloads. You declare them once per supervisor, so the same ClusterClass works at every site. Save stores them by themselves, without the step’s button. The step warns in two cases:
  • With only one nameserver, that resolver is a single point of failure for every image pull, because guests send docker.io, quay.io and registry.k8s.io to the supervisor’s registry mirror.
  • When every time server is a host name, NTP depends on DNS, so a resolver outage stops nodes from joining.
Only clusters created after the save get the new values. Existing guests keep the values they were built with. After you change the values, run the step’s apply. It renders the ClusterClasses again, and their defaults then carry the nameservers and search domains. Values that you set on the create form override these. See Create a cluster. Under the fields, Registry mirror and trust shows what guests inherit from Source & Bootstrap. It shows the mirror host, and compares how many redirected and trusted registries are declared with how many the ClusterClasses carry. It is read-only here. If the classes carry fewer, a guest created now pulls from the public internet. Run the step’s apply to write them into the classes. A declared Strict air-gap reaches guests the same way, from capi-clusterclasses 0.6.14. With an older chart, the apply log says that guests still fall back to the internet.

Cluster add-ons (CAAPH)

CAAPH, the Cluster API Add-on Provider for Helm, installs add-ons into guest clusters. Each guest cluster then opts in to each add-on on the create form. See Create a cluster. The vSphere add-ons (CPI, CSI and the CSR approver) have no toggle. They follow the Talos on vSphere card. While cluster-api-operator is not installed, the engine request is refused with 409.

Recovery

When the operator release is stuck in a failed rollback, or a provider stays not Ready and gives a reason, an Operator or provider stuck banner appears. It offers Force reconcile + restart operator. This action force-reconciles the operator HelmRelease, restarts the operator pod, and shows its last log lines. On a healthy supervisor, it does nothing.

Fields only the API sets

The install routes treat a field you leave out differently. POST .../capi/install takes the whole provider set. If you leave out a kind’s kubevirtEnabled, kamajiEnabled, vclusterEnabled or vsphereEnabled, it counts as false, and that provider is removed. POST .../capi/clusterclasses/install and POST .../capi/addons keep the installed value of any field you leave out, so {} renders again what is there.
The ClusterClass request answers 400 in these cases: an enabled vSphere family without at least one tenant, a tenant with an empty field, or two tenants with the same name. It answers 409 for a vsphere.thumbprint that differs from the one the installed classes pin, because CAPV does not allow changes to those templates. If only the stored credentials carry a new thumbprint, it keeps the installed one and says so in the step log. Over MCP, an assistant can declare guest DNS and NTP and manage the vCenter certificate. It cannot install the operator, the providers, the add-on engine or the ClusterClasses. After the step has installed a ClusterClass, clusters can be created over MCP with create_capi_cluster.

Flow Telemetry

This step connects the cluster to ClickHouse as a flow pipeline. It applies the clickhouse-schema chart, sets the cluster agent’s dispatchers, and applies the DNS visibility policy. Pipeline & runtime lists everything the apply does. Flow telemetry describes the dispatchers and their tables. The step unlocks when Cilium is Ready.
The apply button stays disabled until ClickHouse is installed and published. To get there, run the Monitoring step with Enable ClickHouse on, on a supervisor with a domain. Then wait for the clickhouse.<your domain> route and its certificate to be Ready. Until then, the API answers 412. The button is also disabled while every dispatcher is off, or while Cluster name is empty.

Dispatchers

Envoy applies the two filters before it sends anything, so a filtered request is never stored. With both filters on, Envoy logs only failed requests that are not probes. The first apply that turns on Gateway access log usually warns that the Service kube-system/cluster-agent-gwlog does not exist yet, because the agent is still rolling out. The gateway connects when the Service appears. If a warning says that the sink stays off, apply again after cert-manager has issued the certificate. If the cluster agent is older than the TLS listener, the log travels in cleartext until you upgrade the agent, and the apply warns about it. The step has no control for the Tetragon dispatcher. It sends back the stored enableTetragon value, so a supervisor that has Tetragon on keeps it. You install Tetragon itself through the API: see Pipeline & runtime.

Cluster identification

ClickHouse target

Celum keeps the DSN in the Secret kube-system/cluster-agent-clickhouse when the agent’s chart can read it from a Secret. Otherwise it keeps it in the HelmRelease values.

Schema chart

The API also takes clusterAgentChartVersion and clusterAgentImageTag, which move the cluster agent to that version. Empty keeps the version that the agent’s release declares. API: POST /api/supervisors/{name}/flow-pipeline/configure (monitoring:Install). Every dispatcher flag is false if you leave it out, so send all of them. MCP: no tool runs the apply, so use the API. get_component_status with component=flow-pipeline reads the step’s state. get_flow_freshness shows whether rows are arriving. get_clickhouse_schema shows the live schema.

ClickHouse passwords

Under its status, the step has a ClickHouse passwords section with a Rotate password button for each of the two users Celum manages, k8sgate_admin and flows. A rotation is not part of the apply and needs monitoring:Install. Flow store passwords describes what each rotation does and costs, and its API route and MCP tool.