From 94e996791792f57f98c32b1c5c1896cad1891ac7 Mon Sep 17 00:00:00 2001 From: Ashley Davis Date: Thu, 16 Jan 2025 17:32:50 +0000 Subject: [PATCH] rework upgrade docs for cert-manager v1.12 Since 1.13-1.15 are going to reach EOL before v1.12, the usual upgrade process isn't very helpful (and will take a lot of time). This change adds docs on how to skip directly from v1.12 to v1.16, saving time and simplifying our instructions. Signed-off-by: Ashley Davis --- .spelling | 7 +++ content/docs/manifest.json | 44 +++++++-------- .../releases/upgrading/upgrading-1.12-1.13.md | 21 ------- .../docs/releases/upgrading/upgrading-1.12.md | 56 +++++++++++++++++++ public/_redirects | 3 + 5 files changed, 88 insertions(+), 43 deletions(-) delete mode 100644 content/docs/releases/upgrading/upgrading-1.12-1.13.md create mode 100644 content/docs/releases/upgrading/upgrading-1.12.md diff --git a/.spelling b/.spelling index 848f0bec77a..e5ee9f0b7ff 100644 --- 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 index 58442bb795d..63ab6be9bbf 100644 --- 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 deleted file mode 100644 index 6cd4d4e5038..00000000000 --- a/content/docs/releases/upgrading/upgrading-1.12-1.13.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: Upgrading from v1.12 to v1.13 -description: 'cert-manager installation: Upgrading 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. **IMPORTANT NOTE**: If upgrading from a version below v1.12, upgrade to the latest v1.12 release before upgrading to v1.13. Otherwise, some certificates may be unexpectedly re-issued (see https://github.com/cert-manager/cert-manager/issues/6494#issuecomment-1816112309) - -2. 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) - -3. 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) - -4. 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 that defined there. (https://github.com/cert-manager/cert-manager/pull/6182, https://github.com/inteon) - -## Next Steps - -From here on you can follow the [regular upgrade process](../../installation/upgrade.md). diff --git a/content/docs/releases/upgrading/upgrading-1.12.md b/content/docs/releases/upgrading/upgrading-1.12.md new file mode 100644 index 00000000000..ca65e3702e7 --- /dev/null +++ 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 index 12c247b2754..d314c95246c 100644 --- 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!