cert-manager
cert-manager is a Kubernetes controller that requests, stores and renews TLS certificates. The Azure Web App Blueprint runs it in every cluster to issue the API's origin certificate, which Front Door validates, and the certificates of internal hosts such as ArgoCD.
What it does
An Issuer or cluster-wide ClusterIssuer says where certificates come from. An ACME issuer, such as Let's Encrypt, proves control of a name with a challenge: DNS-01 writes a TXT record under _acme-challenge in the name's zone. Before telling the authority to check, cert-manager runs a self-check that the record resolves. A CA issuer signs certificates with a key held in a Kubernetes Secret. A Certificate, or an Ingress annotation, asks an issuer for a certificate, which cert-manager stores in a Secret and renews before expiry.
How BuiltForProd uses it
The cert-manager unit installs the chart, version v1.21.2, into the cert-manager namespace on the system pool, with its CRDs kept if the release is removed, and creates the issuers:
| ClusterIssuer | Issues | How |
|---|---|---|
letsencrypt-prod | The API origin certificate for blueprint-api.<stage>.company.com | ACME DNS-01 in the stage's public zone, account mailbox from the unit's acme_email |
letsencrypt-staging | Untrusted test certificates without rate limits | The same, for testing issuance (letsencrypt_staging_issuer, on by default) |
internal-ca | *.<stage>.internal.company.com hosts such as ArgoCD | A CA issuer over internal-root-ca: ECDSA P-384, valid 10 years, renewed a year before expiry, signed by selfsigned-root |
The application chart's Ingress names letsencrypt-prod as its cluster issuer. Front Door validates the resulting certificate against the host name, which keeps TLS end to end; see Azure Front Door.
Identity. cert-manager answers DNS-01 challenges with a workload identity, not a secret. The identity id-<prefix>-cert-manager is federated with the controller's service account cert-manager/cert-manager and holds DNS Zone Contributor on the stage zone in acme-core-dns only; see Azure DNS.
Self-check path. The controller runs with --dns01-recursive-nameservers-only, so the self-check uses the pod's own resolver: CoreDNS, then the VNet's Azure-provided DNS at 168.63.129.16, which is outside every route table and firewall rule and resolves the public stage zone. cert-manager never queries a public resolver or the zone's authoritative name servers on port 53, which the hub firewall does not allow, so issuance works in both egress modes of the hub.
Trust. Workstations and the runners trust internal hosts by importing ca.crt from the Secret cert-manager/internal-root-ca of the stage's cluster. Let's Encrypt sends expiry and policy notices to the acme_email mailbox.
Terms you will see
| Term | Meaning |
|---|---|
| ClusterIssuer | A certificate source every namespace can use. |
| ACME | The protocol Let's Encrypt uses to prove control of a name. |
| DNS-01 | The challenge answered with a TXT record in the public zone. |
| Self-check | cert-manager's own lookup of the TXT record before validation starts. |
| Internal CA | The per-cluster certificate authority for *.<stage>.internal.company.com. |
Where to read more
- Azure Web App Blueprint overview for where the certificates are used.
- Azure DNS for the zones the challenges write to.
- AKS for the cluster's Workload ID.