Upgrading and Installing cert-manager with Tanzu: Best Practices and Step-by-Step Guide

Products

• VMware vSphere with Tanzu

Issue/Introduction

When managing certificates in Kubernetes environments, cert-manager is an essential component that automates the issuance and renewal of TLS certificates. However, upgrading or installing cert-manager—especially in a TKGS environment requires careful planning to avoid service disruptions or configuration issues.

In this guide, we'll walk through recommended upgrade path, compatibility considerations, and step-by-step process to upgrade or install cert-manager using Tanzu CLI commands.

Environment

VMware vSphere with Tanzu

 

vSphere with Tanzu

Cause

If you attempt to skip versions (e.g., 1.5.3 → 1.10.2), you may see following error:

CustomResourceDefinition.apiextensions.k8s.io "certificaterequests.cert-manager.io" is invalid:
- spec.conversion.strategy: Required value
- spec.conversion.webhookClientConfig: Forbidden: should not be set when strategy is not set to Webhook

Resolution

Step:1: Check Compatibility with Kubernetes

Before upgrading cert-manager, it's critical to verify its compatibility with current Kubernetes version.

Refer to compatibility matrix here:
https://cert-manager.io/docs/releases/#old-cert-manager-releases

Step:2: Upgrade Incrementally

cert-manager upgrades must be incremental, meaning one minor version at a time. Skipping versions (e.g., from v1.5.3 directly to v1.10.2) may lead to errors due to breaking changes in CRDs.

If not all minor versions are available in Tanzu package repository, we recommend upgrading with the adjacent version. Incremental upgrade path is necessary.

https://cert-manager.io/docs/installation/upgrade/

Step:3(optional):You can refer to official backup guide here:

https://cert-manager.io/docs/devops-tips/backup/

NOTE: Tanzu provides commands to install and upgrade cert-manager, but it does not currently support backup operations natively.

Step:4 cert-manager Upgrade Using Tanzu CLI

>Check Installed Packages

kubectl get packages -A | grep cert

>Create Namespace for cert-manager

kubectl create ns cert-manager

> Update Tanzu Package Repository

tanzu package repository update tanzu-standard --url projects.registry.vmware.com/tkg/packages/standard/repo:v2.2.0_update.2 -n kapp-controller-packaging-global

>Perform Incremental Upgrade (Adjacent Version Only:e.g., from v1.5.3 to v1.7.2)

tanzu package installed update cert-manager -p cert-manager.tanzu.vmware.com -n cert-manager -v 1.7.2+vmware.3-tkg-3

>(Optional) Fresh Installation (Not Recommended for Existing Deployments)

tanzu package install cert-manager -p cert-manager.tanzu.vmware.com -n cert-manager -v 1.5.3

>Validate Package Installation

kubectl get pkgi -A