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’sNuviraClusterConfig 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.
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.
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’sNuviraClusterConfig. 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. Thesiderolink 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
devicespattern 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.
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/25at/29(16 projects) - VM identity
198.51.100.128/26at/29(8 slices) - Egress
198.51.100.192/27 - Platform LB
198.51.100.224/27
198.51.100.192.
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-systemand moves it intofrr-k8s-systemwhen 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.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.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, invalues 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:
- Applies the Gateway API CRD bundle.
- Removes the
safe-upgrades.gateway.networking.k8s.ioValidatingAdmissionPolicy and its binding, because that policy blocks the experimental-channel CRDs that Envoy Gateway needs. - Creates the
envoy-gatewayGatewayClass.
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, useGET .../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.
- Celum applies Cilium at once. If Cilium is refused, the refusal comes back to the click and nothing else runs.
- 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.
- 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. - A second request for the same supervisor while a job runs gets
409. - Each stage writes its own audit entry,
networking-apply:followed by the stage name, under the identity of the person who clicked.
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 redactssecretId.
<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.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.
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.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.
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_ADDRis set on the backend.- The bootstrap credential is set:
VAULT_BOOTSTRAP_ROLE_IDandVAULT_BOOTSTRAP_SECRET_ID. VAULT_BOOTSTRAP_ALLOWcovers this supervisor.- The supervisor has a domain, or a zone declared in the DNS Publishing step.
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 theexternal-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)
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: theexternal-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 themonitoring 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.
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 intoclickhouse-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 theprometheus-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 HelmReleaseskubevirt/virt-kubevirt and cdi/virt-cdi. The step also does these things:
- labels the
kubevirtandcdinamespaces as privileged; - pins the KubeVirt and CDI control-plane pods (not the VMs) to control-plane nodes;
- adds two KubeVirt dashboards to Grafana.
Release panels
Components
Feature gates
This section is collapsed. Open it only to change a gate.
Two gates need care on Talos:
KubevirtSeccompProfileis a default gate. ThepasstVM network mode needs it on Talos. If you turn it on for an installed supervisor, restartvirt-handlerafterwards. Also set the node sysctluser.max_user_namespacesabove0(see Run a VM).PersistentReservationis marked Talos-incompatible. Leave it off on Talos: its sidecar needs a writable/etc/multipath, and without onevirt-handlercrash-loops.
KubeVirt controller
CDI configuration
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.
POST /api/supervisors/{name}/capi/installinstalls the operator release, waits for its CRDs and webhook, then applies the providers.POST .../capi/addonsinstalls the add-on engine. It is sent only when Enable guest add-on engine (CAAPH) is on.POST .../capi/clusterclasses/installrenders the ClusterClasses. It is sent when at least one kind is offered, or when the ClusterClass release already exists.
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’sfeatureGates (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:Createandvcenter:Useon the new name.
Tenants
Each vSphere tenant renders onetalos-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.ioandregistry.k8s.ioto 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.
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 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 theclickhouse-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.