Skip to content

ADR-006: Use cert-manager for TLS Certificate Automation

Status

Accepted

Date

2026-03-07

Context

TLS certificates are required for HTTPS ingress. In production, certificates are issued by public CAs (Let's Encrypt, AWS ACM). Locally, self-signed certificates or a private CA are used. The solution must automate certificate issuance and renewal.

Decision

Use cert-manager (CNCF Incubating) with a self-signed local CA (local-ca-issuer).

Certificate chain: 

selfsigned-issuer (cert-manager built-in)
    └── local-ca (self-signed CA cert, stored in Secret)
            └── local-ca-issuer (ClusterIssuer backed by local CA)
                    └── *.local certificates (issued on demand via Ingress annotation)

Usage in Ingress: 

annotations:
  cert-manager.io/cluster-issuer: "local-ca-issuer"

Alternatives Considered

Tool Reason Not Chosen
Manual certificates No automation; certificates expire silently; doesn't represent production patterns
Let's Encrypt (ACME) Requires a public domain and internet-accessible server; not feasible on local MacBook
Vault PKI Excellent learning target for Phase 3; adds significant complexity for Phase 1 basics
mkcert Simple local CA tool; not integrated with Kubernetes; no automatic renewal

Consequences

Positive

  • Fully automated certificate lifecycle (issuance, renewal)
  • Identical API to production (just swap local-ca-issuer for letsencrypt-prod)
  • cert-manager CRDs (Certificate, ClusterIssuer) are the industry standard
  • Compatible with any ingress controller via annotations

Negative

  • Browser will show "Not trusted" warning for self-signed certs
  • Fix: export the local CA cert and add to macOS Keychain as trusted
  • Certificate and ClusterIssuer CRDs add conceptual overhead for beginners

Trust the Local CA (Optional)

# Export CA cert
kubectl get secret local-ca-key-pair -n cert-manager \
  -o jsonpath='{.data.tls\.crt}' | base64 -d > local-ca.crt

# Add to macOS Keychain
sudo security add-trusted-cert -d -r trustRoot \
  -k /Library/Keychains/System.keychain local-ca.crt

Trade-offs

Production-fidelity automation is prioritised over simplicity. The complexity of a 2-tier CA is justified by the realistic certificate workflow it teaches.