cert-manager

cert-manager automates certificate issuance and renewal inside Kubernetes. You declare the certificate you want. Controllers obtain it from a configured issuer, store it in a Kubernetes Secret, and keep it renewed.

The central mental model is a certificate control loop.

Certificate -> CertificateRequest -> Issuer -> certificate authority
      ^                                      |
      |                                      v
      +----------- TLS Secret <--- signed certificate

This model replaces a manual sequence with declared intent and observed status. It does not replace public key infrastructure, choose trust policy, or make every workload reload renewed certificates.

Why cert-manager exists

TLS certificates expire. Issuing them by hand creates recurring work and failure risk. Kubernetes also encourages short-lived, declarative workloads, while traditional certificate processes often depend on tickets, copied files, and long-lived credentials.

cert-manager connects these worlds. It adds custom resource definitions to the Kubernetes API. Its controllers watch those resources and reconcile them with certificate authorities.

A platform team can define approved issuers. An application team can request a certificate through a Kubernetes resource or an annotated Ingress. cert-manager then tracks issuance, writes the result to a Secret, and renews it before expiry.

This makes the certificate lifecycle visible through familiar Kubernetes tools. It also places certificate operations in the cluster control plane. Permissions, network paths, upgrades, and Secret handling therefore matter.

The core resources

Four resource types explain most cert-manager behavior.

Resource	Role
`Certificate`	Declares names, lifetime, key settings, destination Secret, and issuer reference
`CertificateRequest`	Represents one request for a signed certificate
`Issuer`	Defines a certificate authority available within one namespace
`ClusterIssuer`	Defines a certificate authority available across namespaces

A Certificate is durable intent. During issuance, cert-manager generates a private key and creates a CertificateRequest. The referenced issuer signs or forwards the request. cert-manager stores the signed certificate and private key in the Secret named by spec.secretName.

The Secret is the workload-facing result. The Certificate remains the management object. Deleting or editing one without understanding the other can trigger reissuance or leave a workload using stale data.

Issuer scope is a policy boundary

An Issuer is namespaced. A Certificate can reference it only from the same namespace. This scope lets a team manage a certificate authority configuration for its own area.

A ClusterIssuer is cluster-scoped. Certificates in any namespace can reference it. That convenience creates a wider policy surface. Cluster-wide availability does not mean every namespace should receive every name or certificate profile.

Issuer type determines how signing happens. Built-in choices include ACME, CA, SelfSigned, and Vault. External issuers can add other certificate authorities while following the same resource pattern.

The ready condition on an issuer tells you whether cert-manager considers its configuration usable. It does not prove that every future request will succeed. A request can still fail because of name policy, credentials, network access, rate limits, or challenge validation.

ACME turns domain control into issuance

The Automated Certificate Management Environment, or ACME, lets a certificate authority validate control of a domain before issuing a certificate. A common public use case connects cert-manager to an ACME service.

For ACME issuance, cert-manager creates two additional resources:

CertificateRequest -> Order -> Challenge -> validation path

An Order tracks the ACME order. A Challenge tracks one authorization challenge. These resources are valuable debugging evidence, not configuration you normally create by hand.

The two common challenge types are:

HTTP-01 serves a token over HTTP for the requested name. cert-manager can create temporary solver Pods, Services, and Ingress or Gateway resources.
DNS-01 publishes a TXT record under the domain. cert-manager uses a configured DNS provider or external webhook.

HTTP-01 fits names that route publicly through a compatible ingress path. DNS-01 supports wildcard certificates and works without routing application traffic to the cluster. DNS-01 also requires permission to change DNS data.

Use an ACME staging endpoint while testing. Repeated production failures can consume certificate-authority rate limits. Move to production only after the challenge path works.

Ingress and Gateway automation

You can create Certificate resources directly. This keeps certificate intent explicit and gives you access to the full resource API.

cert-manager also includes ingress-shim. It watches annotated Ingress resources and ensures that matching Certificate resources exist. The Ingress TLS section supplies the requested hosts and destination Secret name.

This path is convenient when one Ingress owns one certificate. It can obscure ownership when several systems edit the same resource. Inspect the generated Certificate instead of treating the annotation as proof of successful issuance.

Gateway integration provides a similar route for Gateway API resources. In both cases, the generated certificate still follows the normal issuer, request, status, and Secret lifecycle.

Renewal is reconciliation, not deployment

cert-manager renews managed certificates before they expire. It updates the Secret after successful issuance. Modern cert-manager releases default to rotating the private key during reissuance.

That does not guarantee that an application serves the new material. Some workloads watch mounted Secret volumes. Others read the certificate only at startup. Test the complete path from Secret update to the endpoint a client reaches.

Also monitor the future, not only the present. A currently valid certificate can hide a broken renewal path until its renewal window begins. Certificate expiration metrics, failed request alerts, and periodic staging tests reveal that risk earlier.

The installed components

Three long-running components form the normal installation:

the controller reconciles certificates, requests, issuers, and ACME resources;
the webhook validates and defaults cert-manager custom resources;
cainjector injects certificate authority data into supported Kubernetes resources.

The Kubernetes API server must reach the webhook. The components must reach the API server. Issuer configurations can add paths to ACME servers, DNS APIs, Vault, or other external systems.

The controller and cainjector use leader election. Extra replicas provide standby availability, not horizontal work sharing. The webhook can serve traffic across multiple ready replicas.

Treat cert-manager as part of the platform control plane. It creates and reads Secrets containing private keys. Restrict its permissions, network access, scheduling environment, and administrative surface accordingly.

A practical troubleshooting path

Start from declared intent and follow the generated resources.

Certificate conditions and events
  -> CertificateRequest conditions and events
    -> Issuer readiness and controller events
      -> Order and Challenge for ACME
        -> solver resource, DNS, and external service

A Kubernetes API write only proves that the object was accepted. The Ready condition and events explain what the controller observed.

For ACME failures, inspect the Order and Challenge. HTTP-01 failures often involve public routing, ingress selection, firewall rules, or reachability from the cluster. DNS-01 failures often involve provider credentials, zone selection, propagation, or resolver behavior.

Check controller logs after resource status and events narrow the problem. Logs without resource context produce noise and can send you toward unrelated reconciliation attempts.

Where cert-manager fits

cert-manager is a good fit when:

Kubernetes resources should declare certificate intent;
supported or external issuers can reach your certificate authority;
renewal should be reconciled in the cluster;
certificates belong in Kubernetes Secrets or supported volume integrations;
platform teams can operate the controller as a trusted cluster service.

It is not the whole trust system. It does not distribute trust bundles by itself; trust-manager addresses that separate problem. It does not automatically copy a Secret across namespaces. It does not define who should be allowed to request which identities unless you add approval and policy controls.

It may be the wrong boundary when certificate consumers live outside Kubernetes, private keys must never enter the Kubernetes Secret model, or an existing certificate platform already owns issuance and renewal end to end.

A path to competence

First, understand Certificate, issuer scope, status conditions, and the destination Secret. Then issue a test certificate from a non-production issuer.

Next, trace one complete ACME flow. Inspect the CertificateRequest, Order, Challenge, solver resources, and final Secret. Break the validation path in a test environment and learn the resulting status.

Then design production boundaries. Choose namespaced or cluster-scoped issuers, restrict credentials, define approval policy, monitor expiration, and test application reload behavior.

Finally, rehearse backup and restore, supported-version upgrades, and controller failure. Certificate automation becomes dependable when you can explain every handoff from declared name to the certificate clients actually receive.