WIP: reworking upgrade docs

Signed-off-by: Ashley Davis <ashley.davis@cyberark.com>
cert-manager · Jan 16, 2025 · c4902ef · c4902ef
1 parent d46bde3
commit c4902ef
Show file tree

Hide file tree

Showing 5 changed files with 81 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,12 @@ v1.12.1
 v1.12.2
 v1.12.3
 v1.12.4
+v1.12.
 v1.13
+v1.14
+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
@@ -32,33 +32,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": [
@@ -70,6 +50,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,50 @@
+---
+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. 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 two sections:
+
+1. The first section shows 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".
+
+2. The second section provides more traditional upgrade instructions if you want to upgrade from v1.12 to v1.13.
+
+## Before Upgrading to Any Version
+
+**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)).
+
+## After Upgrading
+
+Whether upgrading v1.12 to v1.13 or to v1.16, you can follow the [regular upgrade process](../../installation/upgrade.md) once you've check the notes in the relevant section.
+
+## Upgrading from v1.12 to v1.16
+
+You should read all of the below information and check your environment. Most upgrades from 1.12 to 1.16 are simple and smooth, but in some scenarios you may need to make some changes.
+
+1. If you run in an environment which tightly restricts which images can be pulled, be aware that cert-manager v1.15 changed the `ctl` image to a `startupapicheck` image. Ensure that the new image can be pulled in your environment. There is no `ctl` image for cert-manager v1.16.
+
+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. BREAKING: 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. Potentially breaking: 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. Potentially breaking: 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!