Cert Manager Knowledge Patch

cert-manager Knowledge Patch

Use this skill when upgrading, configuring, operating, or integrating cert-manager. Check the deployed cert-manager patch release before applying version-dependent guidance, and prefer a corrected patch release where one is called out.

Reference index

Upgrade blockers and changed defaults

Make private-key rotation explicit before an upgrade

Certificate.spec.privateKey.rotationPolicy defaults to Always. Set it to Never before upgrading if a workload must retain its existing private key.

spec:
  privateKey:
    rotationPolicy: Never

The old default-changing feature gate is GA and no longer configurable. Use the per-Certificate field.

Account for the revision-history limit

Certificate.spec.revisionHistoryLimit defaults to 1. Certificates that omit it no longer have the earlier unlimited/nil behavior.

Treat HTTP-01 ingress selection as exclusive

Specify exactly one of class, ingressClassName, or name on an HTTP-01 solver. Generated solver Ingresses use PathType: Exact; if ingress-nginx strict path validation rejects them, use a corrected ingress-nginx release, disable its strict validation, or configure:

config:
  featureGates:
    ACMEHTTP01IngressPathTypeExact: false

Avoid known bad initial patch releases

• Use 1.17.1 or later for Cloudflare DNS-01, and 1.17.4 or later for URI name constraints.
• Use 1.18.1 or later when disabling exact HTTP-01 paths.
• Skip 1.19.0; use 1.19.1 or later to avoid issuer-reference default reissuance and trailing-dot SAN regressions.
• Use 1.19.2 or later for merged global.nodeSelector behavior.
• Use 1.20.1 or later on OpenShift and when combining inferred Gateway parentRefs with annotation overrides.
• Use 1.20.2 or later when setting both webhook.config and webhook.volumes.
• Use 1.21.1 or later with disabled renewal and for DNS-01 issuer recovery after a missing Secret is created.

Prepare chart-managed identity and monitoring changes

Containers default to UID and GID 65532. Update admission rules and volume permissions that assumed UID 1000 or GID 0.

The chart no longer creates token-creation RBAC for the controller ServiceAccount. Give issuer-referenced ServiceAccounts explicit token RBAC. Remove the deleted ServiceMonitor/PodMonitor path and port override values; metrics use /metrics and the http-metrics port name.

Removed and deprecated behavior

Remove obsolete feature-gate settings

• Stop enabling ValidateCAA; it was deprecated before removal.
• Do not configure DefaultPrivateKeyRotationPolicyAlways; the behavior is unconditional.
• Do not rely on disabling CAInjectorMerging; bundle merging is unconditional.
• ServerSideApply for cainjector is deprecated because cainjector always uses server-side apply.
• Replace controller fields enableGatewayAPI and enableGatewayAPIListenerSet with gatewayAPI.enabled and gatewayAPI.enableListenerSet.

gatewayAPI:
  enabled: true
  enableListenerSet: true

Remove unavailable API and chart settings

Migrate integrations away from the removed ObjectReference API type. Do not use global.rbac.disableHTTPChallengesRole; it was withdrawn after 1.18.0. Remove the deleted Prometheus monitor override values before Helm schema validation.

Revisit direct ACME resource tooling

The aggregate cert-manager-edit ClusterRole does not grant all direct Challenge and Order mutations. Certificate-driven issuance is unaffected; automation that manages these internal resources needs explicit RBAC.

Certificate and renewal quick reference

Configure renewal deliberately

Use renewBefore, renewBeforePercentage, or the expressive renewalPolicies field as appropriate. Long-duration percentage calculations are corrected, and failed CertificateRequests default to a maximum backoff of 32 hours:

config:
  certificateRequestMaximumBackoffDuration: 8h

When spec.renewal.policy: Disabled is in use, require the patch release that fixes the controller panic.

Choose keystore and output compatibility

JKS and PKCS#12 keystores may use a literal password, mutually exclusive with passwordSecretRef. The literal satisfies consumers that require a password; it does not add keystore security.

spec:
  keystores:
    jks:
      create: true
      password: changeit

Use the PKCS#12 Modern2026 profile for AES-256/SHA-256 KDFs and FIPS 140-3 compatibility. Additional certificate output formats are always available without a feature gate.

Validate issuer output and subject handling

Large RSA keys use SHA-384 at 3072 bits and SHA-512 at 4096 bits. IP common names become IP SANs, IPv6 subjects work with HTTP-01, large PEM chains are accepted, mismatched CSR keys fail with backoff, and already-expired issuer responses stop instead of reissuing forever.

ACME and DNS quick reference

Select profiles and renewal information

Select a CA-offered ACME certificate profile when needed. Experimental RFC 9773 renewal information is available with ACMEUseARI, allowing the CA to recommend renewal windows.

Use delayed validation only as an escape hatch

waitInsteadOfSelfCheck skips the local HTTP-01 or DNS-01 self-check, waits for the configured duration, and asks the ACME server to validate. Reserve it for environments such as split-horizon DNS or NAT hairpinning.

Configure newer DNS solver controls

RFC2136 supports explicit protocol; Azure DNS supports zoneType: AzurePrivateZone. DNS credentials are validated before issuer readiness. CloudDNS handles cleanup with large record sets, while DigitalOcean errors are retried and attached to Challenge events.

Gateway and ingress quick reference

Control generated Certificates

Use --extra-certificate-annotations to copy selected annotations from Ingresses or Gateways. Changes to Duration or RenewBefore annotations reconcile immediately. Cert-shim also maps cert-manager.io/alt-names and cert-manager.io/ip-sans.

Configure ListenerSet deliberately

ListenerSet certificate generation is alpha and requires its feature gate. For TLS-only ListenerSets, route HTTP-01 through the parent Gateway with:

metadata:
  annotations:
    acme.cert-manager.io/http01-parentreffallback: "true"

Use cert-manager.io/ignore-tls-listeners to exclude selected Gateway TLS listeners. Passthrough listeners are ignored.

Helm and operations quick reference

Apply chart-wide controls

global.nodeSelector, global.commonLabels, component and solver runtime classes, chart-managed NetworkPolicies, percentage PodDisruptionBudgets, and templated ServiceAccount annotation keys and values are available. global.hostUsers: false opts chart-managed Pods into Kubernetes user namespaces on Kubernetes 1.33 or later.

Scope and clean up workloads

--namespace=<namespace> restricts operation to that namespace and disables cluster-scoped controllers. Set startupapicheck.ttlSecondsAfterFinished to let Kubernetes remove the completed startup API check Job.

Observability and CA injection quick reference

Update metrics and log consumers

Use the certificate not-before/not-after timestamp metrics and certmanager_certificate_challenge_status. ACME request metrics use the bounded action label instead of path. Structured logging adds context, so exact full-line matches may fail. The Prometheus metrics label is consistently cert-manager.

Plan CA rotation around unconditional merging

Cainjector merges certificates into injected bundles to preserve trust overlap during rotation and always uses server-side apply. Use --ignore-namespaces to exclude namespaces from Secret watches.

Issuer and API quick reference

Prefer workload identity over long-lived credentials

Vault issuers support AWS IAM authentication through IRSA, EKS Pod Identity, and ambient EC2/ECS credentials. Their service-account token audiences include the Vault server address. Configure a TLS server name when Vault certificate validation requires one, and never put .. in Vault paths or auth mount paths.

Query and apply resources safely

Issuer-reference group, kind, and name are selectable fields. Generated apply-configuration types support type-safe server-side apply. Use iss and ciss as the short names for Issuer and ClusterIssuer.

Verification checklist

Before rollout:

1. Confirm the exact cert-manager patch release and Kubernetes/OpenShift compatibility.
2. Render the Helm chart with all production values and validate the resulting RBAC, security contexts, Service ports, and NetworkPolicies.
3. Inspect every Certificate for rotation and renewal assumptions.
4. Exercise HTTP-01/DNS-01 solvers against the deployed ingress and DNS providers.
5. Check alerts, dashboards, and log parsing for label and structured-log changes.
6. Test CA-bundle overlap and all relying clients during issuer rotation.
7. Prefer the latest patch release on a supported minor branch.