Merge pull request #1622 from SgtCoDFish/versions

Rework upgrade docs for v1.12
cert-manager · Jan 31, 2025 · 62ea937 · 62ea937
2 parents 1663b95 + 94e9967
commit 62ea937
Show file tree

Hide file tree

Showing 5 changed files with 88 additions and 43 deletions.
diff --git a/.spelling b/.spelling
@@ -113,6 +113,8 @@ BundleTarget
 BundleCondition
 NamespaceSelector
 CamelCase
+Cyberark
+CyberArk
 CAs
 CNAME
 CNAMEs
@@ -530,8 +532,13 @@ v1.12.1
 v1.12.2
 v1.12.3
 v1.12.4
+v1.12.
 v1.13
+v1.14
+v1.15
+v1.15.
 v1.16
+v1.16.
 v1.19
 v1.5
 v1.5.0

diff --git a/content/docs/manifest.json b/content/docs/manifest.json
@@ -33,33 +33,13 @@
               "path": "/docs/releases/release-notes/release-notes-1.15.md"
             },
             {
-              "title": "Upgrade 1.14 to 1.15",
-              "path": "/docs/releases/upgrading/upgrading-1.14-1.15.md"
-            },
-            {
-              "title": "1.14",
-              "path": "/docs/releases/release-notes/release-notes-1.14.md"
-            },
-            {
-              "title": "Upgrade 1.13 to 1.14",
-              "path": "/docs/releases/upgrading/upgrading-1.13-1.14.md"
-            },
-            {
-              "title": "1.13",
-              "path": "/docs/releases/release-notes/release-notes-1.13.md"
-            },
-            {
-              "title": "Upgrade 1.12 to 1.13",
-              "path": "/docs/releases/upgrading/upgrading-1.12-1.13.md"
+              "title": "Upgrading from 1.12",
+              "path": "/docs/releases/upgrading/upgrading-1.12.md"
             },
             {
               "title": "1.12",
               "path": "/docs/releases/release-notes/release-notes-1.12.md"
             },
-            {
-              "title": "Upgrade 1.11 to 1.12",
-              "path": "/docs/releases/upgrading/upgrading-1.11-1.12.md"
-            },
             {
               "title": "Older releases",
               "routes": [
@@ -71,6 +51,26 @@
                   "title": "Migrating Deprecated API Resources",
                   "path": "/docs/releases/upgrading/remove-deprecated-apis.md"
                 },
+                {
+                  "title": "Upgrade 1.14 to 1.15",
+                  "path": "/docs/releases/upgrading/upgrading-1.14-1.15.md"
+                },
+                {
+                  "title": "1.14",
+                  "path": "/docs/releases/release-notes/release-notes-1.14.md"
+                },
+                {
+                  "title": "Upgrade 1.13 to 1.14",
+                  "path": "/docs/releases/upgrading/upgrading-1.13-1.14.md"
+                },
+                {
+                  "title": "1.13",
+                  "path": "/docs/releases/release-notes/release-notes-1.13.md"
+                },
+                {
+                  "title": "Upgrade 1.11 to 1.12",
+                  "path": "/docs/releases/upgrading/upgrading-1.11-1.12.md"
+                },
                 {
                   "title": "1.11",
                   "path": "/docs/releases/release-notes/release-notes-1.11.md"

diff --git a/content/docs/releases/upgrading/upgrading-1.12-1.13.md b/content/docs/releases/upgrading/upgrading-1.12-1.13.md
diff --git a/content/docs/releases/upgrading/upgrading-1.12.md b/content/docs/releases/upgrading/upgrading-1.12.md
@@ -0,0 +1,56 @@
+---
+title: Upgrading from v1.12
+description: 'cert-manager installation: Upgrading v1.12'
+---
+
+cert-manager v1.12 is a Long Term Support (LTS) release sponsored by [Venafi, a CyberArk company](https://venafi.com/). As an LTS release, v1.12 will be supported past the end-of-life
+of cert-manager v1.13, v1.14 and v1.15.
+
+To support users upgrading from v1.12 to a more modern version, this guide includes three sections:
+
+1. An initial section which must be read and followed before any kind of upgrade.
+
+1. Details on how to upgrade to a more modern version - cert-manager v1.16. This allows users to skip the usual cert-manager advice of "upgrading through the versions" and go directly from `v1.12.x` to `v1.16.y`. Further upgrades beyond cert-manager v1.16 should use the usual "upgrade through the versions" advice.
+
+2. Details on a more traditional upgrade path, to upgrade from v1.12 to v1.13. Since v1.13 is already at end-of-life, users should not stay on cert-manager v1.13 and should proceed to continue upgrading until they reach a supported version.
+
+## Before any upgrades
+
+### Run the latest release of cert-manager v1.12
+
+**IMPORTANT:** Before upgrading to any newer version, ensure you're running the latest v1.12 release. Otherwise, some certificates may be unexpectedly re-issued (see [this comment](https://github.com/cert-manager/cert-manager/issues/6494#issuecomment-1816112309)).
+
+### Other Upgrade Information
+
+Whether upgrading to v1.13 or to v1.16, you can follow the [regular upgrade process](../../installation/upgrade.md) once you've checked the notes in the relevant section below.
+
+## Upgrading from v1.12 to v1.16
+
+You should read all of the below information and check your environment. Most upgrades from v1.12 to v1.16 are simple but in some scenarios you may need to make some changes.
+
+You should upgrade directly to the latest available v1.16 patch release since earlier versions of v1.16 had bugs.
+
+1. If you run in an environment which tightly restricts which images can be pulled or if you've made manual changes to the `ctl` image in your deployment, be aware that the `ctl` image has changed a `startupapicheck` image. Ensure that the new image can be pulled in your environment. There is no `ctl` image for cert-manager v1.16 or newer.
+
+2. cert-manager v1.16 adds Helm schema validation, which will reject invalid Helm values. Be prepared to fix any invalid Helm values during the upgrade. For more information, check the [Helm](../release-notes/release-notes-1.16.md#helm) section of the v1.16 release notes.
+
+3. If you set the `.featureGates` Helm value, be aware that this field no longer affects the webhook in newer versions. This could be an issue if you're relying on a webhook feature gate in cert-manager v1.12. Most users will be unaffected by this change; if you're concerned, check the note in the "Upgrading from v1.12 to v1.13" section below.
+
+4. If you rely on GatewayAPI support in v1.12, note that it was promoted to Beta and as a side effect was put behind a flag. You'll need to pass the `--enable-gateway-api` flag to enable it.
+
+5. Upgrades to the in-tree Venafi issuer mean that some certificate renewals may fail if Venafi configuration values are incorrect. If you use the Venafi issuer, check the [Venafi Issuer](../release-notes/release-notes-1.16.md#venafi-issuer) section of the v1.16 release notes.
+
+6. In cert-manager v1.13, webhook validation of CertificateRequest resources became stricter: all `KeyUsages` and `ExtendedKeyUsages` must be defined directly in the CertificateRequest resource and the encoded CSR can never contain more usages than defined in the Kubernetes resource. See [`#6182`](https://github.com/cert-manager/cert-manager/pull/6182) for more information. Most users are unaffected by this change.
+
+## Upgrading from v1.12 to v1.13
+
+When upgrading cert-manager from 1.12 to 1.13, in few cases you might need to take additional steps to ensure a smooth upgrade:
+
+1. If you deploy cert-manager using helm and have `.featureGates` value set, the features defined
+there will no longer be passed to cert-manager webhook, only to cert-manager controller. Use `webhook.featureGates` field
+instead to define features to be enabled on webhook. (https://github.com/cert-manager/cert-manager/pull/6093, https://github.com/irbekrm)
+
+2. If you were, for some reason, passing cert-manager controller's features to webhook's --feature-gates flag,
+this will now break (unless the webhook actually has a feature by that name). (https://github.com/cert-manager/cert-manager/pull/6093, https://github.com/irbekrm)
+
+3. Webhook validation of CertificateRequest resources is stricter now: all `KeyUsages` and `ExtendedKeyUsages` must be defined directly in the CertificateRequest resource, the encoded CSR can never contain more usages than defined in the Kubernetes resource. See [`#6182`](https://github.com/cert-manager/cert-manager/pull/6182) for more information.
diff --git a/public/_redirects b/public/_redirects
@@ -8,6 +8,9 @@ https://trust-manager.dev/* https://cert-manager.io/:splat 301!
 # Redirect all next-docs on the main site to the release-next preview
 https://cert-manager.io/next-docs/* https://release-next--cert-manager.netlify.app/docs/:splat 301!
 
+# Redirect the 1.12 -> 1.13 update page to a page which captures all methods of upgrading 1.12
+/docs/releases/upgrading/upgrading-1.12-1.13 /docs/releases/upgrading/upgrading-1.12
+
 # Various older renamed pages
 /docs/configuration/externalloadbalancer/ /docs/configuration/acme/http01/externalloadbalancer/ 301!