📋 Recommended Actions

⚠️ Action Required
⚠️ Action Required Review your IssuerRef configurations and any external tooling that interacts with cert-manager APIs. The Kubernetes API server no longer injects default kind (‘Issuer’) and group (‘cert-manager.io’) for IssuerRef fields in CRDs. While cert-manager itself handles these internally, external clients might need updates to handle potentially empty kind or group fields.

📝 Summary

This release for cert-manager v1.19.1 delivers crucial API consistency and stability improvements, primarily revolving around IssuerReference defaulting. We’ve reverted the behavior where the Kubernetes API server would automatically inject default kind and group values for IssuerRef in CRDs. This means that if you omit these fields, the API server will now store them as empty. While this is an important change for external tooling relying on API server-side defaulting, cert-manager’s internal controllers have been enhanced to seamlessly handle these empty fields at runtime, maintaining expected behavior. We’ve also updated the RequestMatchesSpec logic to prevent unnecessary certificate re-issuances when only default IssuerRef values change. Key dependency updates include sigs.k8s.io/controller-runtime to v0.22.3, github.com/Venafi/vcert/v5 to v5.12.2, and Go to 1.25.3. This update ensures better API predictability and internal stability. Review your workflows, especially if external tools process cert-manager resources and expect API-injected defaults. Immediate action isn’t required for core functionality, but client-side adjustments might be.

⚠️ Issuer Reference API Defaulting Reverted & Runtime Consistency Enhanced

To ensure greater predictability and to align with a more explicit API contract, cert-manager v1.19.1 reverts the Kubernetes API server’s automatic injection of default kind and group values for IssuerReference fields in CRDs. Previously, if you omitted issuerRef.kind or issuerRef.group in your Certificate, CertificateRequest, Challenge, or Order resources, the Kubernetes API server might have automatically populated them with Issuer and cert-manager.io respectively. Now, these fields will remain empty if not explicitly set in your manifest. While this change impacts how the Kubernetes API server processes these resources, cert-manager’s internal controllers have been robustly updated to apply these defaults at runtime, ensuring no change in core functionality for your certificate issuance workflows. This provides a more consistent behavior, especially when external tooling or direct API interactions are involved.

The default keywords have been removed from the OpenAPI schemas within the CRD definitions for issuerRef.kind and issuerRef.group. This means the API server will no longer mutate your submitted objects to add these defaults. However, cert-manager’s internal logic has been updated to consistently apply these defaults when processing resources. Specifically, new defaulting functions like SetObjectDefaults_Certificate and SetObjectDefaults_Challenge have been added. Moreover, the critical RequestMatchesSpec function, which determines if a CertificateRequest matches a CertificateSpec (and thus if re-issuance is needed), has been refined. It now intelligently compares IssuerRef fields by normalizing empty kind to ‘Issuer’ and empty group to ‘cert-manager.io’ before comparison. This ensures that a certificate won’t be unnecessarily re-issued just because the kind or group fields transition between being explicitly set to defaults and being empty (and thus defaulted internally).

For example, an IssuerRef now behaves like this:

apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: my-certificate
spec:
  secretName: my-certificate-tls
  commonName: example.com
  issuerRef:
    name: my-issuer
    # kind: Issuer (defaults internally by cert-manager if omitted)
    # group: cert-manager.io (defaults internally by cert-manager if omitted)

External tools should be aware that IssuerRef.Kind and IssuerRef.Group may now be empty when reading resources from the Kubernetes API if they were not explicitly defined in the original YAML.

Source:

  • deploy/charts/cert-manager/templates/crd-acme.cert-manager.io_challenges.yaml (80-89)
  • deploy/crds/cert-manager.io_certificates.yaml (160-169)
  • pkg/apis/meta/v1/types.go (53-61)
  • internal/apis/acme/v1/defaults.go (18-47)
  • internal/apis/certmanager/v1/defaults.go (25-69)
  • pkg/util/pki/match.go (27-259)
  • pkg/util/pki/match_test.go (290-486)
  • pkg/controller/certificaterequests/sync.go (43-43)
  • pkg/issuer/helper.go (56-56)
  • pkg/api/util/issuers.go (52-58)

Minor Updates & Housekeeping

This release also includes dependency updates, bumping sigs.k8s.io/controller-runtime to v0.22.3, github.com/Venafi/vcert/v5 to v5.12.2, and the Go runtime to 1.25.3. Additionally, internal Renovate bot configuration was adjusted for release branch management, and klone module generation was temporarily disabled on the release branch to allow for manual Go version updates.