Skip to main content
Every TLS story on this platform ends at one question: which ClusterIssuer signs it. A published route, a Gateway listener, a promoted VM, Grafana behind the shared Gateway — each asks cert-manager for a certificate and names an issuer in the request. Get that name wrong and nothing errors: the Certificate simply waits, forever, for an issuer that does not exist. cert-manager arrives with the Certificates step of platform onboarding, which installs it and creates the supervisor’s first issuer. The per-supervisor Certificates page manages the rest.

​
Before an issuer can work

The supervisor needs a domain. Certificate names are derived from it, so a supervisor with no domain attached issues nothing and says nothing about why — see Register a supervisor. This is the most common cause of a certificate that never appears.

​
Five issuer types

The step asks what kind of trust you have, not which fields to fill: The last two are why the rest of this page exists: they produce issuers with different names and even a different kind (ClusterAdcsIssuer rather than ClusterIssuer), and everything downstream has to name the right one.

​
Which issuer actually signs — three rules

When something asks for a certificate without naming an issuer, Celum resolves one in this order:
1

A pinned default, if you set one

An annotation on the issuer itself — k8s-gate.nuvira.dev/default-cluster-issuer — set from the star on the Certificates page. It survives restarts and travels with the cluster, because it lives on the resource it governs rather than in Celum’s database. Pinning one clears the flag from every other issuer: there is exactly one default.
2

Otherwise, whatever is deployed

Detected from the issuer resources actually present — AD CS, then ACME, then self-signed or imported CA.
3

Otherwise, nothing

No issuer is deployed, so there is no answer, and the resolution says so rather than offering a name.
The status shows which rule answered — pinned or auto — deliberately. Telling an operator an issuer was detected when they pinned it sends them to the wrong page to change it.
That third rule used to return a guess, and the guess was permanent.Every request path used to fall back to the name letsencrypt-prod. On any supervisor that later chose a CA, self-signed or AD CS issuer, that name referred to an issuer which would never exist — and the requests went out anyway.Measured on one supervisor: the shared Gateway was stamped with the guess before the Certificates step ran, the operator then installed a CA issuer, and all four platform hostnames sat on Referenced "ClusterIssuer" not found for a day. Every HTTPS listener showed InvalidCertificateRef while HTTP redirected into a port that answered nothing.It was permanent because the Gateway’s issuer annotation is written once, when the listener is created, and never re-derived. Install the Certificates step before you publish anything, and if you have a Gateway that predates your issuer, re-apply it so the annotation is rewritten.

​
Managing issuers day-2

The Certificates page lists every issuer with its Ready condition, the default badge, and a star to pin or unpin it. Add, edit and delete issuers of any of the five types. The wizard creates the first issuer, and this page manages all the others.
The supervisor’s Certificates page.

​
Editing an issuer

The pencil on an issuer’s row opens Edit issuer. Save changes applies the issuer again with the values you changed and keeps everything else. What you cannot change. The name and the type are locked. To change either one, delete the issuer and add it again. Only the dashboard enforces this. The API checks neither: a POST applies whatever issuerType you send under that name. What you can change, per type: If you paste only half of a pair, Celum keeps the stored pair. This applies to the CA key pair and to the AD CS username and password. An AD CS issuer’s CA bundle is not a secret: the form opens with the bundle the issuer holds, and saving with the field cleared removes it. An issuer edited before Celum 1.296 may have lost its bundle that way; if it stopped issuing, paste the bundle again. If you switch the DNS-01 provider, paste the token for the new provider. The form does not require it when you edit, and without it the issuer works only if a token for that provider is already stored.
Credentials belong to the supervisor, not to one issuer. On one supervisor, all Let’s Encrypt issuers that use GoDaddy share one token Secret, and all that use Cloudflare share another. All AD CS issuers share one credential. Every CA-import and self-signed issuer signs with the same key pair, cert-manager-ca-keypair. If you rotate a credential on one issuer, you rotate it for all of them.
On a Celum appliance, saving an issuer of any other type deletes the Appliance CA issuer. This applies to new and to edited issuers. Celum removes celum-appliance, because issuer detection would otherwise keep choosing it over the type you just saved.
Edit only the issuers that Celum created. The form reads only the types above. An issuer of any other kind opens as Let’s Encrypt, and saving it applies a Let’s Encrypt issuer under that name.

​
Certificates that outlive their cluster

A published guest route mints its certificate on the supervisor, because guest clusters carry no cert-manager of their own. When the guest is deleted, the certificate is not: on one supervisor that left dozens behind, several wedged mid-issuance and all of them indistinguishable in the list from the platform’s own. A background sweep finds them, and the page offers a purge. It is a sweep rather than a step in the delete path because a guest can vanish five ways — topology delete, flat delete, a GitOps prune that happens later in Flux, a project teardown, or someone’s kubectl — and only a sweep covers all five. Kubernetes owner references cannot do it for free: an owner may not cross namespaces, and these certificates live in cert-manager’s.

​
What commonly goes wrong

Platform onboarding

The step that installs cert-manager and creates the first issuer.

Publish it on a public name

Where an issuer is consumed — routes, listeners and TLS.

Gateways & Routes

Listener TLS and the annotation this page is about.

Register a supervisor

Where the domain comes from.