Upgrading cert-manager¶

This article provides guidance for upgrading cert-manager to a regular or Long-Term Support (LTS) release.

Before you upgrade¶

Before you upgrade cert-manager, review the general component upgrade instructions and best practices. For more information, see Venafi Kubernetes component upgrades.

Review the cert-manager releases page to understand release notes, breaking changes, and key considerations for each version.

Before you begin the upgrade, back up all cert-manager resources. For backup instructions, see the backup guide.

It's recommended to upgrade cert-manager to the latest patch release of your current version.

Upgrade to a Long-Term Support (LTS) release¶

Venafi supports direct upgrades between LTS releases. This means you can upgrade from one LTS release to the next without passing through regular releases. However, you can't skip an intermediate LTS release between your current and target versions.

Organizations that prioritize stability and don't require the latest features are encouraged to use LTS releases.

Upgrade between Long-Term Support (LTS) releases¶

You can upgrade directly between consecutive LTS releases. You can't skip any intermediate LTS versions.

Supported upgrade paths¶

Upgrade from v1.12 to v1.17¶

Before upgrading from v1.12 to v1.17, review the following considerations to ensure compatibility with your environment.

It's recommended to upgrade to the latest available v1.17 patch release:

• If your environment restricts image access or if you have modified the ctl image, note that it has been replaced by the startupapicheck image in cert-manager v1.16 and later. Ensure that your environment allows access to this image.
• cert-manager v1.16 introduces Helm schema validation, which rejects invalid Helm values. Review your Helm chart configuration and correct any issues. For more information, see the Helm section in the v1.16 release notes.
• 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 are unaffected by this change. .
• GatewayAPI support, previously enabled by default, is now behind a feature flag. To continue using GatewayAPI, set the --enable-gateway-api flag.
• If you use the in-tree Venafi issuer, verify your Venafi configuration. Incorrect values can result in certificate renewal failures. For details, see the Venafi issuer section in the v1.16 release notes.
• cert-manager v1.13 introduces stricter validation for CertificateRequest resources. All KeyUsages and ExtendedKeyUsages must be explicitly defined. The encoded certificate signing request (CSR) can't include usages beyond those defined in the Kubernetes resource. Most users wwon'tbe affected.

Upgrade cert-manager by using Helm¶

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

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 Venafi OCI registry, follow the instructions in Configuring access to the Venafi OCI Registry.

   This configuration is required to access the cert-manager-components artifacts. Use venafi as the namespace.

2. Add the Venafi Helm repository and update it:

   helm repo add jetstack https://charts.jetstack.io --force-update
   

   This command adds or updates the Jetstack Helm repository, which hosts the cert-manager Helm chart.

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

   helm upgrade --reset-then-reuse-values --version <version> <release_name> oci://registry.venafi.cloud/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.venafi.cloud/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.venafi.cloud/charts/cert-manager
   

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

Upgrade by using static manifests¶

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

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.

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.

Reinstalling cert-manager¶

In some cases there may be a need to do a full uninstall and re-install of cert-manager. An example could be when a very old cert-manager version needs to be brought up to date and it isn't feasible to upgrade one minor version at a time, which is our default recommended upgrade strategy.

For more information on how to do this without any issues, see Reinstalling cert-manager.