Skip to content

Upgrading cert-manager

This topic explains how to upgrade cert-manager by following a supported upgrade path for your current and target versions. It covers the changes each path introduces and explains how to upgrade using Helm or static manifests.

Before upgrading

Before you upgrade cert-manager, complete the following:

Upgrade between Long-Term Support releases

Use Long-Term Support (LTS) releases when you prioritize stability and don't need the latest features.

Palo Alto Networks supports direct upgrades between consecutive LTS releases, so you can move from one LTS release to the next without passing through regular releases. You can't skip an intermediate LTS release.

See the following table for supported upgrade paths.

Starting release Intermediate releases Target release
1.17 None 1.21
1.12 1.17 1.21

Note

If your cert-manager version is too old to follow a supported upgrade path one step at a time, do a full uninstall and reinstall instead. See Reinstalling cert-manager.

Upgrade from v1.17 to v1.21

cert-manager v1.21 is the LTS successor to v1.17. Support for v1.17 ends on 3 February, 2027, so complete this upgrade before then.

Upgrade directly from v1.17 to v1.21, moving from the latest v1.17 patch to the latest v1.21 patch as follows:

  1. Upgrade to the latest v1.17 patch release. Confirm that the cert-manager pods are healthy and your certificates still renew.
  2. Upgrade to the latest v1.21 patch release.

Using the latest version of each release ensures you don't carry in an already-fixed defect or adopt one that was fixed later.

Important

v1.21 requires Kubernetes 1.33 or later, or OpenShift 4.20 or later. v1.17 runs on older clusters than v1.21 does, so if your cluster is below these versions, upgrade the cluster before you upgrade cert-manager. For the full compatibility matrix, see Supported versions.

Upgrade considerations

When upgrading directly, you skip upgrades for v1.18, v1.19, and v1.20. The following sections cover breaking and potentially breaking changes from those releases; review them before upgrading.

Helm chart values

The following can cause your upgrade to fail:

  • Prometheus metrics values removed: From v1.21, the prometheus.servicemonitor.targetPort, prometheus.servicemonitor.path, and prometheus.podmonitor.path values no longer exist. Remove them from your values file. The controller metrics port is also renamed to http-metrics.
  • Token creation RBAC removed: From v1.21, the Helm chart no longer creates the default Role and RoleBinding that let the cert-manager controller create tokens for its own ServiceAccount. If you set serviceAccountRef.name to the controller ServiceAccount, create your own Role and RoleBinding granting serviceaccounts/token: create, or move to a dedicated ServiceAccount, before you upgrade.
  • Separate FIPS Helm charts: From v1.20, the FIPS distribution has its own Helm charts. If you run the FIPS build, add -fips to the chart name, for example oci://registry.ngts.paloaltonetworks.com/charts/cert-manager-fips. The FIPS image is no longer part of the standard chart.

Certificate behavior

The following default changes can alter how existing certificates behave after you upgrade:

  • Private key rotation policy: From v1.18, the default value of Certificate.spec.privateKey.rotationPolicy is Always instead of Never, so reissuing a certificate now generates a new private key. If you depend on the previous behavior, set rotationPolicy: Never on the affected Certificate resources before you upgrade. You can still set it after upgrading, but any certificate that renews in the meantime gets a new private key, and you can't recover the old one. You can't revert this with the DefaultPrivateKeyRotationPolicyAlways feature gate; setting --feature-gates=DefaultPrivateKeyRotationPolicyAlways=false no longer has any effect.
  • Revision history limit: From v1.18, the default value of Certificate.spec.revisionHistoryLimit is 1. When you upgrade, stale CertificateRequest resources are garbage collected unless you set a different value on Certificate resources.
  • CA injector merging: From v1.19, the CAInjectorMerging feature is enabled by default. The CA injector now merges new CA certificates with existing ones instead of replacing them.

ACME and Ingress changes

The following changes affect HTTP-01 solvers and Ingress configuration:

  • Ingress path type: From v1.18, the Kubernetes Ingress pathType for HTTP-01 solvers changed from ImplementationSpecific to Exact. This is incompatible with ingress-nginx when the strict-validate-path-type option is enabled, which is the default from ingress-nginx v1.12.0 onwards, because it disallows the dot in the /.well-known/acme-challenge/ path. To restore the previous behavior, turn off the ACMEHTTP01IngressPathTypeExact feature gate, which is enabled by default.
  • Stricter solver validation: From v1.19, an HTTP-01 solver may set only one of class, ingressClassName, or name. v1.17 rejected a solver only when it set all three, so a solver that sets two is accepted by v1.17 and rejected by v1.21. Before you upgrade, review your Issuer and ClusterIssuer resources and reduce each HTTP-01 solver to a single Ingress selection option.

RBAC changes

The following change reduces write permissions that custom tooling might rely on:

  • Challenge and Order write access reduced: From v1.17.8, the cert-manager-edit ClusterRole no longer grants create on challenges.acme.cert-manager.io or orders.acme.cert-manager.io, and no longer grants patch or update on orders.acme.cert-manager.io. Read access (get, list, watch) is unchanged, as is delete and deletecollection on both resources and patch and update on challenges. This closes GHSA-8rvj-mm4h-c258, where those permissions enabled a namespace editor to bypass Issuer solver selectors and abuse ClusterIssuer credentials.

    This shipped in a v1.17 patch, not in v1.21. If you follow step 1 above and move to the latest v1.17 patch first, you pick up this change before you upgrade to v1.21, and the v1.21 upgrade changes nothing here. Only clusters on v1.17.7 or earlier lose these permissions.

    You're not affected unless you have tooling that creates Challenge or Order resources directly, since these resources are normally created for you through the Certificate to CertificateRequest to Order to Challenge flow. If you do have such tooling, grant these permissions in your own ClusterRole before upgrading.

Metrics and dashboards

The following change can break dashboards and alerts that query cert-manager metrics:

  • ACME client metric labels: From v1.19, the high cardinality path label was removed from the certmanager_acme_client_request_count and certmanager_acme_client_request_duration_seconds metrics and replaced with a bounded action label. Update any dashboards and alerts that group or filter on path.

Upgrade from v1.12 to v1.17

When you upgrade from v1.12 to v1.17, upgrade to the latest v1.17 patch release, not to v1.17.0.

The following considerations cover breaking and potentially breaking changes introduced between v1.13 and v1.16. Review them before you upgrade:

  • ctl image replaced: From v1.16, the startupapicheck image replaces the ctl image. If your environment restricts image access or you have modified the ctl image, make sure your environment allows access to startupapicheck.
  • Helm schema validation: From v1.16, cert-manager validates Helm values and rejects invalid ones. Review your Helm chart configuration and correct any issues. For more information, see the Helm section in the v1.16 release notes.
  • In-tree Enterprise Issuer: From v1.16, if you use the in-tree Enterprise Issuer, verify your Palo Alto Networks configuration. Incorrect values can cause certificate renewal failures. For details, see the Enterprise Issuer section in the v1.16 release notes.
  • Stricter CertificateRequest validation: From v1.13, cert-manager enforces stricter validation for CertificateRequest resources. All KeyUsages and ExtendedKeyUsages must be explicitly defined, and the encoded certificate signing request (CSR) can't include usages beyond those defined in the Kubernetes resource. Most users aren't affected.
  • Webhook feature gates: The .featureGates Helm value no longer affects the webhook component. If you rely on a webhook feature gate in v1.12, verify the new behavior in later versions. Most users aren't affected.
  • GatewayAPI feature flag: GatewayAPI support is no longer enabled by default; it's now behind a feature flag. To continue using GatewayAPI, set the --enable-gateway-api flag.

Upgrade methods

The following sections outline the methods used to upgrade cert-manager. Choose a method based on how you installed cert-manager and how its CRDs are managed.

Upgrade cert-manager with Helm

If you installed cert-manager by using Helm, you can upgrade it with the Helm CLI.

Note

Before upgrading, review the relevant upgrade instructions for both your current version and your target version.

After you complete the required preparations, begin the upgrade process. Replace <release_name> with the name of your cert-manager Helm release (usually cert-manager), and replace <version> with the target version number.

  1. If you have not already configured access to the Next-Gen Trust Security (NGTS) registry, see Configuring Next-Gen Trust Security registry access.

    This configuration is required to access the cert-manager-components artifacts.

  2. Upgrade cert-manager by running the following command:

    helm upgrade --reset-then-reuse-values --version <version> <release_name> oci://registry.ngts.paloaltonetworks.com/charts/cert-manager

    This command upgrades cert-manager to the specified version using the values already set in your current release.

    Note

    To find your Helm release name, run the following command:

    helm list | grep cert-manager

Upgrade CRDs managed by Helm

If you installed cert-manager with the --set crds.enabled=true option, Helm manages the CRDs automatically. When you upgrade the Helm chart, the CRDs are upgraded along with it.

helm upgrade --reset-then-reuse-values --version <version> <release_name> oci://registry.ngts.paloaltonetworks.com/charts/cert-manager

This command upgrades both the cert-manager components and the CRDs, assuming the CRDs were initially installed via Helm.

Upgrade CRDs managed separately

If you installed the CRDs separately (without using the --set crds.enabled=true option), upgrade the CRDs manually before upgrading the Helm chart.

  1. Apply the updated CRDs:

    kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/<version>/cert-manager.crds.yaml

    This command updates the CRDs to match the target version of cert-manager.

  2. Upgrade the cert-manager Helm release:

    helm upgrade --reset-then-reuse-values --version <version> <release_name> oci://registry.ngts.paloaltonetworks.com/charts/cert-manager

    This command completes the upgrade of cert-manager to the specified version.

Upgrade with static manifests

If you installed cert-manager using static deployment manifests, you can upgrade by applying the updated manifest.

Note

Before upgrading, review the upgrade instructions for both your current version and your target version.

To perform the upgrade, replace <version> with the desired version number and run the following command:

kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/<version>/cert-manager.yaml

This command applies the updated manifest and upgrades cert-manager to the specified version.

Note

kubectl apply updates the objects in the new manifest, but doesn't delete objects that the new version no longer ships. Upgrading from v1.17 to v1.21 this way leaves behind the Role and RoleBinding that let the controller create tokens for its own ServiceAccount. Issuance is unaffected. If you want the tighter v1.21 permissions, delete the two objects after upgrading:

kubectl delete role cert-manager-tokenrequest -n cert-manager
kubectl delete rolebinding cert-manager-cert-manager-tokenrequest -n cert-manager

After the upgrade completes, verify that cert-manager is running as expected by checking the status of the pods and resources in your Kubernetes cluster.