cert-manager: TLS certificate automation inside Kubernetes

The gap cert-manager fills in a Kubernetes cluster

Kubernetes has no built-in notion of a TLS certificate. A Secret of type kubernetes.io/tls is just a pair of base64 blobs; nothing in the control plane creates it, rotates it, or notices when it expires. Before cert-manager, teams handled that gap with scripts, a cron job calling an ACME client, or a human calendar reminder. Each of those fails in a different way: the script has no cluster state to reason about, the cron job runs on one node, and the calendar reminder depends on someone still working at the company.

cert-manager closes the gap by extending the Kubernetes API. The README states that it "adds certificates and certificate issuers as resource types in Kubernetes clusters, and simplifies the process of obtaining, renewing and using those certificates." That sentence is the whole design: certificates become declarative objects, and the lifecycle becomes a reconciliation loop rather than a scheduled task.

The audience is narrow and specific. You need a Kubernetes cluster you control, permission to install cluster-scoped resources, and a workload that terminates TLS. If any of those is missing, cert-manager has nothing to attach to. The project's own getting started guide is aimed at this reader, and the README points at a separate nginx-ingress quick start for the common case of certificates behind an Ingress.

Issuers, Certificates and the reconciliation loop

Two custom resource types carry most of the weight. An Issuer is namespaced; a ClusterIssuer is cluster-scoped. Both declare where a certificate should come from and what credentials to use. A Certificate declares what you want: a common name, DNS names, a secret name, and an issuer reference. The controller watches Certificate objects, asks the referenced issuer for a signed certificate, and writes the result into the named Secret.

The README lists the sources it supports: Let's Encrypt over ACME, HashiCorp Vault, CyberArk Certificate Manager, and local in-cluster issuance. The go.mod file corroborates the breadth of that surface, pulling in SDKs for AWS Route 53, Azure DNS, DigitalOcean, Akamai, Google Cloud and the HashiCorp Vault API. Those dependencies exist because ACME and several other flows need to prove domain control by writing a DNS record, which means cert-manager has to speak each provider's API. That is a large amount of third-party code inside a security-sensitive component, and it is the main reason the dependency tree is heavy.

Renewal is the part that earns its place. The README says cert-manager "ensures certificates remain valid and up to date, attempting to renew certificates at an appropriate time before expiry." The scheduling logic lives in the controller, not in your manifests, so you do not set a renewal date. If you want to know the exact renewal window for the version you run, the release notes and the website documentation are where that is specified; the README does not give the threshold.

Installing cert-manager and issuing a first certificate

The README does not embed install commands. It states that installation is documented on the website "with a variety of supported methods" and links to cert-manager.io/docs/installation/. The README's badge section links to Artifact Hub under the cert-manager repository, which is where the chart is published. Because the README does not print the exact repository URL or chart name, check the installation page for the current values rather than copying a command from an older tutorial.

The README sends readers to the website for the getting started guide and the nginx-ingress quick start. So the first real object you create comes from those pages, not from this repository.

The README directs troubleshooting questions to the website's troubleshooting guide, the Kubernetes Slack channels #cert-manager and #cert-manager-dev, and the GitHub issue tracker.

Where cert-manager is the wrong tool

The most common mistake is treating cert-manager as a certificate authority. It is not one. It obtains certificates from the sources the README lists: Let's Encrypt (ACME), HashiCorp Vault, CyberArk Certificate Manager, and local in-cluster issuance. If you need to run your own root and intermediate hierarchy with your own policies, cert-manager can consume that hierarchy through an issuer, but the hierarchy itself comes from elsewhere.

A second boundary is scope. cert-manager is a Kubernetes controller. Certificates for machines outside the cluster, for a legacy VM fleet, or for a service mesh with its own identity system are not its problem. The README frames the project entirely in terms of cluster resource types, and nothing in the repository layout suggests an out-of-cluster mode.

A third constraint is the Go module surface. The README carries an explicit warning: cert-manager "does not currently provide a Go module compatibility guarantee," and most code under pkg/ is "subject to change in a breaking way, even between minor or patch releases and even if the code is currently publicly exported." Anyone planning to import cert-manager as a library rather than run it as a controller should read that sentence twice. The README notes the import path changed with 1.8, from github.com/jetstack/cert-manager to github.com/cert-manager/cert-manager, which is exactly the kind of breakage the warning describes.

Alternatives and the difference in approach

The closest alternative in spirit is a sidecar or ingress-level ACME client that fetches and rotates its own certificate. The difference is architectural: an ingress-level client holds certificate state inside the proxy process and typically has no cluster-wide view, so two ingresses requesting the same name can duplicate work or race. cert-manager centralises that state in the Kubernetes API, which is why a Certificate object can be inspected, labelled, and referenced by other resources.

For organisations that already run HashiCorp Vault, using Vault's PKI secrets engine directly with an agent injector is a legitimate alternative. The trade-off is that the certificate lifecycle then belongs to Vault's policy model, and the Kubernetes objects are a consumer rather than the source of truth. cert-manager's Vault issuer exists precisely to bridge those two worlds, which is worth knowing before deciding the systems are mutually exclusive.

There is also the older generation of tools the README acknowledges: cert-manager is "loosely based upon the work of kube-lego" and borrowed from kube-cert-manager. Those projects are the historical answer to the same problem. Anyone comparing them today should treat the comparison as a migration question rather than a feature question, since the README mentions them only in its history section.

Maintenance, releases and licence

The repository is not archived, and the last push was on 2026-11-01. Recent releases include v1.20.5 on 2026-10-28 and v1.21.3 on 2026-10-23, with v1.20.4 on 2026-09-16. That pattern, a patch line on an older minor alongside a newer minor, is the upgrade cost in practice: you are expected to track two branches if you want security fixes without jumping minor versions. The README states that every release on GitHub has a changelog and that release notes are also published on the website, so the upgrade path is documented rather than implicit.

The licence is Apache-2.0, and the repository carries a LICENSE file plus a LICENSES directory, which is the pattern projects use when bundled third-party components have their own terms. The go.mod dependency list includes vendor SDKs under their own licences. If you redistribute cert-manager inside a product, that LICENSES directory is the place to start; this is a description of what is in the repository, not legal advice.

Development tooling is worth a note for contributors. The Makefile states it is automatically generated and warns that shared logic lives in make/_shared/, with the source of truth in the cert-manager/makefile-modules repository. Repository-specific targets belong in make/00_mod.mk and make/02_mod.mk. Editing the Makefile directly will be overwritten.

Editorial conclusion

Adopt cert-manager if your workloads live in Kubernetes and you want certificate issuance and renewal expressed as cluster resources rather than as a cron job and a shell script. Do not adopt it if you have no cluster to run it in, or if you need a certificate authority you administer yourself outside Kubernetes, since cert-manager consumes issuers rather than replaces them. Before rollout, verify three things on the target cluster: which installation method the website documents for your Kubernetes version, whether your chosen issuer type needs credentials that must be created before the first Certificate is reconciled, and how your ingress controller consumes the resulting Secret. The version you pin matters more than the release cadence, because the README states that most code under pkg/ can change in a breaking way even between patch releases.

Frequently asked questions

Official sources

1. cert-manager/cert-manager on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases