cert-manager is a Kubernetes operator that automates the issuance, storage and renewal of X.509 TLS certificates. It adds a set of CRDs so certificates become ordinary declarative cluster resources: you describe which certificate you want and who should sign it, and controllers keep the resulting Kubernetes Secret valid forever — including renewal well before expiry.

It is the de-facto standard way to get Let's Encrypt certificates into a cluster, but it is equally used to run a private internal PKI (self-signed root → intermediate → workload certs for mTLS), or to front a corporate CA such as HashiCorp Vault or Venafi.

Two objects carry the whole model:

cert-manager reconciles the Certificate: it generates a private key, builds a CSR, drives whatever protocol the issuer needs, writes the result into a kubernetes.io/tls Secret, and re-runs the whole loop before expiry. Your workload only ever consumes the Secret and never knows a CA exists.

That chain is also the debugging path — see Troubleshooting.

Installing cert-manager deploys three Deployments into the cert-manager namespace:

Two short-lived helpers also exist: acmesolver (a tiny pod spawned to serve HTTP-01 challenge tokens) and startupapicheck (a Job that verifies the webhook is reachable before declaring the install healthy).

The CRDs must exist before any Certificate is applied. With Helm (recommended, works well with GitOps tools):

Or the static manifest (CRDs included):

Useful chart values:

The --dns01-recursive-nameservers-only flag is almost always needed in split-horizon / internal-DNS setups, where CoreDNS would otherwise answer the propagation self-check from the cluster's internal view.

All in API group cert-manager.io/v1 unless noted.

Order and Challenge are internal machinery — you never create them, you only read them when something is stuck.

Signs a certificate with its own key. Useless on its own for serving traffic, but it is the bootstrap step for an internal PKI: it is what signs your root CA certificate.

Signs certificates with a CA keypair you supply as a Secret. This is the workhorse for internal/mTLS certificates — no ACME, no rate limits, instant issuance.

The Secret must be of type kubernetes.io/tls and contain tls.crt + tls.key (optionally ca.crt for a chain).

Talks the ACME protocol to Let's Encrypt, ZeroSSL, Buypass, an internal step-ca, etc. Requires an account key (created automatically into privateKeySecretRef) and at least one solver that proves domain control.

Always develop against the staging directory first — production has hard rate limits (50 certs/registered domain/week):

cert-manager spins up a temporary acmesolver Pod, Service and Ingress serving /.well-known/acme-challenge/<token> on port 80, then asks the CA to fetch it.

cert-manager writes a _acme-challenge.<domain> TXT record via a DNS provider API, waits for propagation (self-check), then asks the CA to resolve it.

With several solvers, the most specific matching selector wins, evaluated per DNS name:

An empty selector: {} (or none) is the catch-all.

CAs like ZeroSSL or Google Trust Services require binding the ACME account to an existing account:

spec.vault issues from a Vault PKI mount (auth via AppRole, Kubernetes SA token or a static token); spec.venafi targets Venafi TPP/Cloud. Beyond that, cert-manager has an external issuer interface: third-party controllers (AWS Private CA, step-issuer, Google CAS, Origin CA…) register their own CRDs and cert-manager hands the CertificateRequest over. Reference them with issuerRef.group/issuerRef.kind:

duration/renewBefore are requests: a public ACME CA ignores duration (Let's Encrypt always issues 90 days), while a CA or Vault issuer honours it. renewBefore may not exceed duration.

Type kubernetes.io/tls — directly consumable by every Ingress controller, and mountable as a volume for any workload doing its own TLS.

(See OpenSSL for inspecting certificates; cmctl inspect secret does the same natively.)

You usually don't write Certificate objects at all. The ingress-shim watches Ingress resources and generates a Certificate from the annotation plus spec.tls:

The generated Certificate takes its dnsNames from tls[].hosts and its secretName from tls[].secretName. Delete the annotation and the Certificate is garbage-collected with the Ingress.

Common annotations (all cert-manager.io/… unless noted):

The same shim exists for Gateway API: annotate a Gateway with cert-manager.io/cluster-issuer and cert-manager fills the listener's certificateRefs. HTTP-01 can also solve via an HTTPRoute (solvers[].http01.gatewayHTTPRoute) instead of an Ingress. Gateway support requires the feature gate (--enable-gateway-api, chart value config.enableGatewayAPI).

A self-contained CA hierarchy in three objects — this is the standard pattern for mTLS between services, signing webhook certs, or handing out certificates to non-public internal hosts.

Workloads then simply issuerRef: {name: internal-ca, kind: ClusterIssuer}. The remaining problem is distributing the root CA to clients — that is what the sibling project trust-manager does: a Bundle resource collects CA certificates (your root, plus optionally the public trust store) and syncs them into a ConfigMap/Secret in every selected namespace.

The cainjector solves the same problem for the API server: annotate a webhook/APIService with cert-manager.io/inject-ca-from: <namespace>/<certificate> and it keeps the caBundle field in sync.

Renewal is fully automatic: at notAfter - renewBefore (default ⅔ of the lifetime if unset) the controller creates a new CertificateRequest and rewrites the Secret in place. Consumers must pick the new cert up:

Force an early renewal:

Walk the chain downwards; kubectl describe events say more than the controller log.

cmctl (the cert-manager CLI) collapses most of this:

Frequent failure modes: