Release Notes

cert-manager is the easiest way to automatically manage certificates in Kubernetes and OpenShift clusters.

cert-manager 1.21 brings ACME Renewal Information (ARI) support, AWS IAM authentication for the Vault issuer, several security hardening changes, and continued improvements to Gateway API integration and cainjector. There are three breaking changes related to Helm chart RBAC and metrics values — review them carefully before upgrading.

Known Issues

  • Controller crash-loops when a Certificate sets renewal.policy: Disabled: the new Certificate renewal policies feature (#8258) causes a nil pointer dereference panic in the trigger controller whenever a Certificate's spec.renewal.policy is set to Disabled — pki.RenewalTime() returns (nil, nil) for that policy, but the caller unconditionally dereferences the result. This crashes the controller process (crash-loop) for any cluster with such a Certificate. Workaround: do not set renewal.policy: Disabled on any Certificate until this is fixed; remove the field (or set a different policy) from any Certificate that already has it, and restart the controller if it is currently crash-looping. See #9031 for details.
  • Log spam for non-cert-manager-labelled Secret events: the typed predicates refactoring (#8407) causes filteredEventHandler type assertion failures ("OnAdd missing Object", "OnUpdate missing ObjectOld", "OnDelete missing Object") for every non-cert-manager-labelled Secret event, multiplied by 7 certificate sub-controllers. This is cosmetic only — the affected controllers only need events from cert-manager-labelled Secrets (which arrive via the typed informer); the metadata informer events were always filtered out by predicates in previous versions. Issuer and ClusterIssuer controllers are not affected. See #8994 for details.
  • Issuer/ClusterIssuer can get stuck at Ready: False, Reason: InvalidSolver and never self-correct: new eager validation of ACME solver Secrets (#8255) means an Issuer/ClusterIssuer referencing a solver Secret (e.g. a DNS01 provider credential) that doesn't exist yet will correctly report Ready: False, but creating the missing Secret afterwards does not trigger re-reconciliation — the controller's Secret-watch logic was never updated to recognise solver Secrets. It will only recover on the next 10-hour informer resync, a change to the Issuer/ClusterIssuer's own spec, or a controller restart. Workaround: after creating the missing Secret, make a trivial edit to the Issuer/ClusterIssuer spec (or delete and recreate it) to force reconciliation. See cert-manager/cert-manager#9036 for details and a fix proposal.

Major Themes

Default tokenrequest RBAC removed from Helm chart

⚠️ Breaking change

The Helm chart no longer creates a default Role and RoleBinding granting the cert-manager controller permission to create tokens for its own ServiceAccount (serviceaccounts/token: create). No documented workflow requires this RBAC — the Route53 docs section that motivated it was removed in 2024.

If you use serviceAccountRef.name pointing at the controller ServiceAccount, you must now either create your own Role/RoleBinding granting serviceaccounts/token: create, or migrate to a dedicated ServiceAccount (recommended — see the Vault or Route53 documentation).

Restrict Challenge and Order RBAC in cert-manager-edit ClusterRole

⚠️ Potentially breaking change

The cert-manager-edit aggregate ClusterRole no longer grants create for challenges.acme.cert-manager.io or create, patch, update for orders.acme.cert-manager.io (GHSA-8rvj-mm4h-c258). These resources are internal to cert-manager's ACME workflow. Challenge patch and update are retained because users may need them to remove stuck finalizers.

This change was already shipped in v1.20.3 and v1.19.6, so if you are running one of those versions this will not be a breaking change. If you have tooling that creates Challenge or Order resources directly, you will need to grant those permissions explicitly.

Metrics port name and path Helm values removed

⚠️ Breaking change

The Helm values prometheus.servicemonitor.targetPort, prometheus.servicemonitor.path, and prometheus.podmonitor.path have been removed. The controller Service metrics port has been renamed from tcp-prometheus-servicemonitor to http-metrics. Because the Helm values schema uses additionalProperties: false, users who still have any of the removed keys in their values overrides will see a schema validation error on upgrade — remove them before upgrading. (#8952)

ACME and Certificate Management

  • ACME Renewal Information (ARI): experimental support for RFC 9773 behind the ACMEUseARI feature gate. When enabled, cert-manager queries the ACME server's renewalInfo endpoint for the recommended renewal window, allowing servers like Let's Encrypt to proactively prompt renewal during mass revocations or CA key rollovers. (#8798)
  • waitInsteadOfSelfCheck solver option: skip cert-manager's own self-check and instead wait a configured duration before asking the ACME server to validate. An escape hatch for split-horizon DNS and NAT hairpin environments. See configuration details. (#8858)
  • AWS IAM authentication for Vault: the Vault issuer now supports IRSA, EKS Pod Identity, and ambient EC2/ECS credentials, removing the need for long-lived AWS Secrets. (#8422)
  • Certificate renewal policies: a new renewalPolicies field on the Certificate API provides more expressive control over renewal scheduling, complementing renewBefore and `rene

[truncated]