cert-manager Codebase Overview
What is cert-manager?
cert-manager is an open-source X.509 certificate controller for Kubernetes and OpenShift workloads. It adds certificates and certificate issuers as first-class resource types in Kubernetes clusters using Custom Resource Definitions (CRDs), automating the process of obtaining, renewing, and using TLS certificates. cert-manager watches for certificate requests, interacts with configured certificate authorities (CAs), and ensures certificates remain valid by proactively renewing them before expiry.
Originally created by Jetstack, cert-manager was donated to the CNCF in 2020 and has since graduated to become a CNCF graduated project, reflecting its maturity and widespread adoption across the Kubernetes ecosystem.
Why Does It Exist?
Managing TLS certificates in Kubernetes is operationally complex. Without automation, teams must manually generate certificate signing requests, submit them to CAs, configure secrets, and track expiration dates across potentially hundreds of services. This manual process is error-prone and does not scale.
cert-manager solves this by providing a declarative, Kubernetes-native approach to certificate management. Users define what certificates they need, and cert-manager handles the entire lifecycle: requesting, issuing, storing, and renewing. This eliminates certificate-related outages caused by expired certificates and removes operational toil from platform teams. It integrates with popular CAs like Let’s Encrypt, HashiCorp Vault, and Venafi, making it the standard for certificate automation in Kubernetes environments.
Who Uses It?
cert-manager is one of the most widely deployed Kubernetes add-ons, used by organizations of all sizes running production Kubernetes clusters. Its primary users include:
- Platform engineers automating TLS for ingress traffic with Let’s Encrypt
- Security teams enforcing mTLS between microservices using internal CAs
- DevOps engineers managing certificate lifecycles across multi-cluster environments
- Enterprise organizations integrating with commercial CAs like Venafi and Vault for compliance
With over 13,000 GitHub stars and integration into major Kubernetes distributions, cert-manager has become the de facto standard for certificate management in the cloud-native ecosystem.
Key Concepts
Before exploring the cert-manager codebase, understanding these fundamental concepts is essential:
- Certificate: A Kubernetes custom resource that defines the desired properties of an X.509 certificate (DNS names, duration, issuer reference). cert-manager watches Certificates and ensures a matching signed certificate exists in a Kubernetes Secret.
- Issuer / ClusterIssuer: Resources that represent a certificate authority capable of signing certificates. An Issuer is namespace-scoped while a ClusterIssuer is cluster-scoped. Supported types include ACME (Let’s Encrypt), CA, SelfSigned, Vault, and Venafi.
- CertificateRequest: An immutable, one-shot resource representing a single CSR (Certificate Signing Request) sent to an issuer. Created automatically by cert-manager when a Certificate needs issuance or renewal.
- Order (ACME): Tracks the lifecycle of an ACME certificate order, including domain validation challenges. Created automatically for ACME issuers.
- Challenge (ACME): Represents a single ACME domain validation challenge (HTTP-01 or DNS-01) that must be solved to prove domain ownership.
- Reconciliation Loop: cert-manager controllers continuously watch resource state and reconcile toward the desired state, following the standard Kubernetes controller pattern.
Custom Resource Definitions
cert-manager introduces six CRDs that extend the Kubernetes API:
| CRD | Scope | Purpose |
|---|---|---|
Certificate | Namespaced | Declares desired certificate properties |
CertificateRequest | Namespaced | Represents a single CSR to an issuer |
Issuer | Namespaced | Configures a namespace-scoped CA |
ClusterIssuer | Cluster | Configures a cluster-wide CA |
Order | Namespaced | Tracks ACME certificate orders |
Challenge | Namespaced | Tracks individual ACME challenges |
Project Structure
The cert-manager codebase, written in Go, follows a well-organized structure within the cert-manager/cert-manager repository:
- /cmd/: Entry points for the main binaries:
controller,webhook,cainjector,acmesolver, and the CLI toolcmctl. - /pkg/: Core library code shared across components. Key subdirectories include
/pkg/controller(controller implementations),/pkg/issuer(issuer logic), and/pkg/apis(API type definitions). - /internal/: Internal packages not intended for external consumption, including API machinery and controller utilities.
- /deploy/: Helm chart and static manifest templates for deploying cert-manager.
- /test/: End-to-end and integration test suites for validating cert-manager functionality across different issuer types.
- /hack/: Build scripts, code generation tools, and development utilities.
- /design/: Design proposals documenting architectural decisions and feature designs.
The codebase is structured around the controller pattern, with each CRD having dedicated controllers that watch for changes and reconcile state. The clear separation between API definitions, business logic, and runtime components makes it approachable for contributors familiar with Kubernetes controller development.