Venafi Kubernetes component upgrades¶
Kubernetes Server-Side Apply (SSA) Requirement
There is an important compatibility requirement that must be considered when installing the Venafi components for Kubernetes: Kubernetes Server-Side Apply (SSA) support. For most Venafi components, SSA support is a hard requirement. This feature was promoted to GA in Kubernetes version 1.22. For more information, see the Kubernetes documentation.
For this reason, Venafi requires all enterprise components to be installed on Kubernetes version 1.22 or later.
v1 Version Requirement
Before cert-manager 1.6, it was possible to use cert-manager API versions
v1beta1. These API versions can't be used in any newer version of cert-manager. Additionally, most Venafi components for Kubernetes only support the v1 version of the cert-manager API.
For this reason, Venafi requires all organizations to use the cert-manager v1 APIs.
For more information on migrating to the cert-manager v1 APIs, see this guide.
Venafi uses semantic versioning in the format of MAJOR.MINOR.PATCH for its enterprise components. Venafi guarantees that critical bugs and vulnerabilities will be fixed in patch versions of releases that are supported.
Organizations can upgrade to the latest patch version without worrying about breaking changes or changed behavior. Minor versions introduce new features in a manner compatible with previous versions, while major versions may include changes that are not backward-compatible, clearly indicated.
How to upgrade components¶
Perform upgrades one minor release at a time, for example, from 1.11.0 to 1.12.0 to 1.13.0.
Venafi advises to always upgrade to the latest patch version of each release directly.
Venafi do not support skip-upgrades because intermediate versions might contain migration logic that is removed in later versions.
Make sure you have a fast-paced process to upgrade to the latest patch version of the release that you are using as soon as possible.
It's important to stay up to date with patches, otherwise you might be susceptible to outages owing to vulnerabilities, or bugs.
DO NOT remove CRDs before upgrading. Removing CRDs will result in CRs being garbage collected. Instead patch or replace the CRD resources.
For example, if you remove the
certificates.cert-manager.io CRD, all certificate resources will be irreversibly removed by the Kubernetes garbage collector.
Before you upgrade, make sure you have a way to restore the cluster to its state before the upgrade (see Component backups). It's not strictly necessary to do this for patch upgrades (but it's recommended if you want to be extra careful).
Before upgrading to the next release of a component, read the release notes/ upgrade notes. These notes will list breaking changes or extra actions that must be taken before upgrading. For example:
Use Venafi Kubernetes manifests, Helm, or GitOps tools to upgrade to the latest version.
Make sure that the CRDs are also upgraded. If you installed the CRDs separately, you must upgrade them separately.
To test your upgraded installation, you can re-issuance a certificate. Without causing downtime, the
cmctl renew -n namespace certificate-namemust be used. For more information on this, see the cert-manager documentation.
DO NOT remove the TLS secret resource, as this can cause downtime.
If you experience any issues with the newly upgraded version, you can easily revert to the previous version of your installation using
helm rollback. For more information, see the Helm documentation.
If the rollback also fails, you can recover from the backup created in step 1.