From 0a208a2ff82dd719b7c664d188b86b9e36a1337f Mon Sep 17 00:00:00 2001 From: Jared Kirschner Date: Fri, 7 Apr 2023 10:28:05 -0700 Subject: [PATCH 1/3] docs: improve upgrade path guidance --- .../docs/upgrading/instructions/index.mdx | 80 +++++++++---------- .../docs/upgrading/upgrade-specific.mdx | 5 ++ 2 files changed, 43 insertions(+), 42 deletions(-) diff --git a/website/content/docs/upgrading/instructions/index.mdx b/website/content/docs/upgrading/instructions/index.mdx index 8c2b3c08050..6dafa507033 100644 --- a/website/content/docs/upgrading/instructions/index.mdx +++ b/website/content/docs/upgrading/instructions/index.mdx @@ -10,45 +10,41 @@ description: >- This document is intended to help users who find themselves many versions behind to upgrade safely. -## Upgrade Path - -Our recommended upgrade path is to move through the following sequence of versions: - -- 0.8.5 (final 0.8.x) -- 1.2.4 (final 1.2.x) -- 1.6.10 (final 1.6.x) -- 1.8.19 (final 1.8.x) -- 1.10.12 (final 1.10.x) -- Latest 1.12.x -- Latest 1.13.x ([at least 1.13.1](/consul/docs/upgrading/upgrade-specific#service-mesh-compatibility)) -- Latest 1.14.x - -## Getting Started - -To get instructions for your upgrade, follow the instructions given below for -your _currently installed_ release series until you are on the latest current version. -The upgrade guides will mention notable changes and link to relevant changelogs – -we recommend reviewing the changelog for versions between the one you are on and the -one you are upgrading to at each step to familiarize yourself with changes. - -Select your _currently installed_ release series: -- 1.13.x: work upwards from [1.14 upgrade notes](/consul/docs/upgrading/upgrade-specific#consul-1-14-x) -- 1.12.x: work upwards from [1.13 upgrade notes](/consul/docs/upgrading/upgrade-specific#consul-1-13-x) -- 1.11.x: work upwards from [1.12 upgrade notes](/consul/docs/upgrading/upgrade-specific#consul-1-12-0) -- 1.10.x: work upwards from [1.11 upgrade notes](/consul/docs/upgrading/upgrade-specific#consul-1-11-0) -- [1.9.x](/consul/docs/upgrading/instructions/upgrade-to-1-10-x) -- [1.8.x](/consul/docs/upgrading/instructions/upgrade-to-1-10-x) -- [1.7.x](/consul/docs/upgrading/instructions/upgrade-to-1-8-x) -- [1.6.x](/consul/docs/upgrading/instructions/upgrade-to-1-8-x) -- [1.5.x](/consul/docs/upgrading/instructions/upgrade-to-1-6-x) -- [1.4.x](/consul/docs/upgrading/instructions/upgrade-to-1-6-x) -- [1.3.x](/consul/docs/upgrading/instructions/upgrade-to-1-6-x) -- [1.2.x](/consul/docs/upgrading/instructions/upgrade-to-1-6-x) -- [1.1.x](/consul/docs/upgrading/instructions/upgrade-to-1-2-x) -- [1.0.x](/consul/docs/upgrading/instructions/upgrade-to-1-2-x) -- [0.9.x](/consul/docs/upgrading/instructions/upgrade-to-1-2-x) -- [0.8.x](/consul/docs/upgrading/instructions/upgrade-to-1-2-x) - -If you are using <= 0.7.x, please contact support for assistance: -- OSS users without paid support plans can request help in our [Community Forum](https://discuss.hashicorp.com/c/consul/29) -- Enterprise and OSS users with paid support plans can contact [HashiCorp Support](https://support.hashicorp.com/) +## General Upgrade Path + +Each upgrade should jump at most 2 major versions, +except where dedicated instructions are provided for a larger jump between specific versions. +If your upgrade path has no applicable dedicated instructions, +review the [version-specific upgrade details](/consul/docs/upgrading/upgrade-specific) +to plan your upgrade, starting from the next version and working +upwards to your target version. + +For example, to upgrade from Consul 1.12 to Consul 1.15: +1. Upgrade to Consul 1.14 as an intermediate step. + To plan, review the upgrade details for + [1.13](/consul/docs/upgrading/upgrade-specific#consul-1-13-x) and + [1.14](/consul/docs/upgrading/upgrade-specific#consul-1-14-x). +2. Upgrade to Consul 1.15. + To plan, review the upgrade details for + [1.15](/consul/docs/upgrading/upgrade-specific#consul-1-15-x). + +## Dedicated Instructions for Specific Upgrade Paths + +The following table provides links to dedicated instructions +for directly upgrading from a version in the starting range +to a destination version. + +| Starting Version Range | Destination Version | Upgrade Instructions | +| ---------------------- | ------------------- | -------------------- | +| 1.8.0 - 1.9.17 | 1.10.12 | Follow the [instructions for upgrading to final 1.10.x](/consul/docs/upgrading/instructions/upgrade-to-1-10-x) | +| 1.6.9 - 1.8.18 | 1.8.19 | Follow the [instructions for upgrading to final 1.8.x](/consul/docs/upgrading/instructions/upgrade-to-1-8-x) | +| 1.2.4 - 1.6.9 | 1.6.10 | Follow the [instructions for upgrading to final 1.6.x](/consul/docs/upgrading/instructions/upgrade-to-1-6-x) | +| 0.8.5 - 1.2.3 | 1.2.4 | Follow the [instructions for upgrading to final 1.2.x](/consul/docs/upgrading/instructions/upgrade-to-1-2-x) | + +For example, to upgrade from Consul 1.3.1 to latest 1.12: +1. Upgrade to Consul 1.6.10 using the dedicated instructions +1. Upgrade to Consul 1.8.19 using the dedicated instructions +1. Upgrade to Consul 1.10.12 using the dedicated instructions +1. Upgrade to latest Consul 1.12.x after consulting the + [version-specific upgrade details](/consul/docs/upgrading/upgrade-specific) + for 1.11 and 1.12. \ No newline at end of file diff --git a/website/content/docs/upgrading/upgrade-specific.mdx b/website/content/docs/upgrading/upgrade-specific.mdx index 936a4cec491..d0d07b62849 100644 --- a/website/content/docs/upgrading/upgrade-specific.mdx +++ b/website/content/docs/upgrading/upgrade-specific.mdx @@ -515,6 +515,11 @@ to Consul 1.11.11 or later to avoid the breaking nature of that change. ### Licensing Changes +You can only upgrade to Consul Enterprise 1.10 from a version of +Consul Enterprise 1.8 >= 1.8.13 or 1.9 >= 1.9.7. Other versions of +Consul Enterprise are not forward compatible with v1.10 and will +cause issues during the upgrade that could result in agents failing to start due to [changes in the way we manage licenses](/consul/docs/enterprise/license/faq). + Consul Enterprise 1.10 has removed temporary licensing capabilities from the binaries found on https://releases.hashicorp.com. Servers will no longer load a license previously set through the CLI or API. Instead the license must be present in the server's configuration From 8b549ffb7571eb8252e27105414f282b4e419b86 Mon Sep 17 00:00:00 2001 From: Jared Kirschner Date: Fri, 7 Apr 2023 12:50:31 -0700 Subject: [PATCH 2/3] fixup --- .../content/docs/upgrading/instructions/index.mdx | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/website/content/docs/upgrading/instructions/index.mdx b/website/content/docs/upgrading/instructions/index.mdx index 6dafa507033..fefea709be1 100644 --- a/website/content/docs/upgrading/instructions/index.mdx +++ b/website/content/docs/upgrading/instructions/index.mdx @@ -12,9 +12,10 @@ This document is intended to help users who find themselves many versions behind ## General Upgrade Path -Each upgrade should jump at most 2 major versions, -except where dedicated instructions are provided for a larger jump between specific versions. -If your upgrade path has no applicable dedicated instructions, +Each upgrade should jump at most 2 major versions, except where +[dedicated instructions](#dedicated-instructions-for-specific-upgrade-paths) +are provided for a larger jump between specific versions. +If your upgrade path has no applicable [dedicated instructions](#dedicated-instructions-for-specific-upgrade-paths), review the [version-specific upgrade details](/consul/docs/upgrading/upgrade-specific) to plan your upgrade, starting from the next version and working upwards to your target version. @@ -42,9 +43,9 @@ to a destination version. | 0.8.5 - 1.2.3 | 1.2.4 | Follow the [instructions for upgrading to final 1.2.x](/consul/docs/upgrading/instructions/upgrade-to-1-2-x) | For example, to upgrade from Consul 1.3.1 to latest 1.12: -1. Upgrade to Consul 1.6.10 using the dedicated instructions -1. Upgrade to Consul 1.8.19 using the dedicated instructions -1. Upgrade to Consul 1.10.12 using the dedicated instructions +1. Upgrade to Consul 1.6.10 using the dedicated instructions. +1. Upgrade to Consul 1.8.19 using the dedicated instructions. +1. Upgrade to Consul 1.10.12 using the dedicated instructions. 1. Upgrade to latest Consul 1.12.x after consulting the [version-specific upgrade details](/consul/docs/upgrading/upgrade-specific) for 1.11 and 1.12. \ No newline at end of file From 88e60ebe3cc898b2c0817e4872eabfdbf87105b9 Mon Sep 17 00:00:00 2001 From: Jared Kirschner Date: Fri, 7 Apr 2023 13:35:01 -0700 Subject: [PATCH 3/3] fixup --- website/content/docs/upgrading/instructions/index.mdx | 11 ++++++----- website/content/docs/upgrading/upgrade-specific.mdx | 11 +++++++---- 2 files changed, 13 insertions(+), 9 deletions(-) diff --git a/website/content/docs/upgrading/instructions/index.mdx b/website/content/docs/upgrading/instructions/index.mdx index fefea709be1..1ea7effb735 100644 --- a/website/content/docs/upgrading/instructions/index.mdx +++ b/website/content/docs/upgrading/instructions/index.mdx @@ -21,11 +21,12 @@ to plan your upgrade, starting from the next version and working upwards to your target version. For example, to upgrade from Consul 1.12 to Consul 1.15: + 1. Upgrade to Consul 1.14 as an intermediate step. To plan, review the upgrade details for [1.13](/consul/docs/upgrading/upgrade-specific#consul-1-13-x) and [1.14](/consul/docs/upgrading/upgrade-specific#consul-1-14-x). -2. Upgrade to Consul 1.15. +1. Upgrade to Consul 1.15. To plan, review the upgrade details for [1.15](/consul/docs/upgrading/upgrade-specific#consul-1-15-x). @@ -37,10 +38,10 @@ to a destination version. | Starting Version Range | Destination Version | Upgrade Instructions | | ---------------------- | ------------------- | -------------------- | -| 1.8.0 - 1.9.17 | 1.10.12 | Follow the [instructions for upgrading to final 1.10.x](/consul/docs/upgrading/instructions/upgrade-to-1-10-x) | -| 1.6.9 - 1.8.18 | 1.8.19 | Follow the [instructions for upgrading to final 1.8.x](/consul/docs/upgrading/instructions/upgrade-to-1-8-x) | -| 1.2.4 - 1.6.9 | 1.6.10 | Follow the [instructions for upgrading to final 1.6.x](/consul/docs/upgrading/instructions/upgrade-to-1-6-x) | -| 0.8.5 - 1.2.3 | 1.2.4 | Follow the [instructions for upgrading to final 1.2.x](/consul/docs/upgrading/instructions/upgrade-to-1-2-x) | +| 1.8.0 - 1.9.17 | 1.10.12 | Refer to [upgrading to latest 1.10.x](/consul/docs/upgrading/instructions/upgrade-to-1-10-x) | +| 1.6.9 - 1.8.18 | 1.8.19 | Refer to [upgrading to latest 1.8.x](/consul/docs/upgrading/instructions/upgrade-to-1-8-x) | +| 1.2.4 - 1.6.9 | 1.6.10 | Refer to [upgrading to latest 1.6.x](/consul/docs/upgrading/instructions/upgrade-to-1-6-x) | +| 0.8.5 - 1.2.3 | 1.2.4 | Refer to [upgrading to latest 1.2.x](/consul/docs/upgrading/instructions/upgrade-to-1-2-x) | For example, to upgrade from Consul 1.3.1 to latest 1.12: 1. Upgrade to Consul 1.6.10 using the dedicated instructions. diff --git a/website/content/docs/upgrading/upgrade-specific.mdx b/website/content/docs/upgrading/upgrade-specific.mdx index d0d07b62849..1c9a7384910 100644 --- a/website/content/docs/upgrading/upgrade-specific.mdx +++ b/website/content/docs/upgrading/upgrade-specific.mdx @@ -515,10 +515,13 @@ to Consul 1.11.11 or later to avoid the breaking nature of that change. ### Licensing Changes -You can only upgrade to Consul Enterprise 1.10 from a version of -Consul Enterprise 1.8 >= 1.8.13 or 1.9 >= 1.9.7. Other versions of -Consul Enterprise are not forward compatible with v1.10 and will -cause issues during the upgrade that could result in agents failing to start due to [changes in the way we manage licenses](/consul/docs/enterprise/license/faq). +You can only upgrade to Consul Enterprise 1.10 from the following Enterprise versions: +- 1.8 release series: 1.8.13+ +- 1.9 release series: 1.9.7+ + +Other versions of Consul Enterprise are not forward compatible with v1.10 and will +cause issues during the upgrade that could result in agents failing to start due to +[changes in the way we manage licenses](/consul/docs/enterprise/license/faq). Consul Enterprise 1.10 has removed temporary licensing capabilities from the binaries found on https://releases.hashicorp.com. Servers will no longer load a license previously