diff --git a/linkerd.io/content/2.15/reference/k8s-versions.md b/linkerd.io/content/2.15/reference/k8s-versions.md index 3069dda13f..88f17260ff 100644 --- a/linkerd.io/content/2.15/reference/k8s-versions.md +++ b/linkerd.io/content/2.15/reference/k8s-versions.md @@ -4,30 +4,28 @@ description = "Reference documentation for which Linkerd version supports which +++ Linkerd supports all versions of Kubernetes that were supported at the time -that a given Linkerd version ships. For example, at the time that Linkerd -stable-2.14.0 shipped, Kubernetes versions 1.26, 1.27, and 1.28 were -supported, so Linkerd stable-2.14.0 supports all of those Kubernetes versions. -(In many cases, as you'll see below, Linkerd versions will also support older -Kubernetes versions.) +that a given Linkerd version ships. For example, at the time that Linkerd 2.14 +shipped, Kubernetes versions 1.26, 1.27, and 1.28 were supported, so Linkerd +2.14 supports all of those Kubernetes versions. (In many cases, as you'll see +below, Linkerd versions will also support older Kubernetes versions.) -Obviously, Linkerd stable-2.14.0 has no knowledge of what changes will come -_after_ Kubernetes 1.28. In some cases, later versions of Kubernetes end up -making changes that cause older versions of Linkerd to not work: we will -update the chart below as these situations arise. +Obviously, Linkerd 2.14 has no knowledge of what changes will come _after_ +Kubernetes 1.28. In some cases, later versions of Kubernetes end up making +changes that cause older versions of Linkerd to not work: we will update the +chart below as these situations arise. {{< table >}} | Linkerd Version | Minimum Kubernetes Version | Maximum Kubernetes Version | |-----------------|----------------------------|----------------------------| -| `stable-2.10` | `1.16` | `1.23` | -| `stable-2.11` | `1.17` | `1.23` | -| `stable-2.12` | `1.21` | `1.24` | -| `stable-2.13` | `1.21` | `1.28` | -| `stable-2.14` | `1.21` | `1.28` | +| `2.10` | `1.16` | `1.23` | +| `2.11` | `1.17` | `1.23` | +| `2.12` | `1.21` | `1.24` | +| `2.13` | `1.21` | `1.28` | +| `2.14` | `1.21` | `1.28` | +| `2.15` | `1.22` | `1.30` | {{< /table >}} -Notes: - -1. Linkerd will almost never change the supported Kubernetes version in a - minor release, which is why the table above only lists major versions. One - known exception: Linkerd 2.11.0 supported Kubernetes 1.16, but 2.11.1 and - later required Kubernetes 1.17 as shown in the table above. +Note that Linkerd will almost never change the supported Kubernetes version in +a minor release, which is why the table above only lists major versions. One +known exception: Linkerd 2.11.0 supported Kubernetes 1.16, but 2.11.1 and +later required Kubernetes 1.17 as shown in the table above. diff --git a/linkerd.io/content/2.15/tasks/install.md b/linkerd.io/content/2.15/tasks/install.md index da26967ce9..143255c109 100644 --- a/linkerd.io/content/2.15/tasks/install.md +++ b/linkerd.io/content/2.15/tasks/install.md @@ -12,6 +12,19 @@ Before you can use Linkerd, you'll need to install the [control plane](../../reference/architecture/#control-plane). This page covers how to accomplish that. +{{< note >}} + +The Linkerd project itself only produces [edge release](/releases/) artifacts. +(For more information about the different kinds of Linkerd releases, see the +[Releases and Versions](/releases/) page.) + +As such, this page contains instructions for installing the latest edge +release of Linkerd. If you are using a [stable +distribution](/releases/#stable) of Linkerd, the vendor should provide +additional guidance on installing Linkerd. + +{{< /note >}} + Linkerd's control plane can be installed in two ways: with the CLI and with Helm. The CLI is convenient and easy, but for production use cases we recommend Helm which allows for repeatability. @@ -21,8 +34,6 @@ the success of the installation. See the [Getting Started Guide](../../getting-started/) for how to install the CLI if you haven't done this already. -{{< releases >}} - ## Requirements Linkerd requires a Kubernetes cluster on which to run. Where this cluster lives diff --git a/linkerd.io/content/2.15/tasks/troubleshooting.md b/linkerd.io/content/2.15/tasks/troubleshooting.md index 202921f18d..25a93b4793 100644 --- a/linkerd.io/content/2.15/tasks/troubleshooting.md +++ b/linkerd.io/content/2.15/tasks/troubleshooting.md @@ -881,12 +881,9 @@ Example failures: unsupported version channel: stable-2.14.10 ``` -As of February 2024, the Linkerd project is no longer producing open source -stable release artifacts. Please read the -[2.15 announcement](/2024/02/21/announcing-linkerd-2.15/#a-new-model-for-stable-releases) -for details. - -See [the full list of Linkerd releases](/releases/) for ways to get Linkerd. +As of February 2024, the Linkerd project itself only produces [edge +release](/releases/) artifacts. For more details, read the [Releases and +Versions](/releases/) page. @@ -919,12 +916,9 @@ Example failures: unsupported version channel: stable-2.14.10 ``` -As of February 2024, the Linkerd project is no longer producing open source -stable release artifacts. Please read the -[2.15 announcement](/2024/02/21/announcing-linkerd-2.15/#a-new-model-for-stable-releases) -for details. - -See [the full list of Linkerd releases](/releases/) for ways to get Linkerd. +As of February 2024, the Linkerd project itself only produces [edge +release](/releases/) artifacts. For more details, read the [Releases and +Versions](/releases/) page. diff --git a/linkerd.io/content/2.15/tasks/upgrade.md b/linkerd.io/content/2.15/tasks/upgrade.md index 336b464456..dec5d3e1de 100644 --- a/linkerd.io/content/2.15/tasks/upgrade.md +++ b/linkerd.io/content/2.15/tasks/upgrade.md @@ -11,9 +11,13 @@ In this guide, we'll walk you through how to perform zero-downtime upgrades for Linkerd. {{< note >}} -This page contains instructions for the latest edge release of Linkerd. If -you have installed a [stable distribution](/releases/#stable) of Linkerd, the -vendor may have additional guidance on how to upgrade. + +This page contains instructions for upgrading to the latest edge release of +Linkerd. If you have installed a [stable distribution](/releases/#stable) of +Linkerd, the vendor may have alternative guidance on how to upgrade. You can +find more information about the different kinds of Linkerd releases on the +[Releases and Versions](/releases/) page. + {{< /note >}} Read through this guide carefully. Additionally, before starting a specific @@ -29,6 +33,8 @@ may contain important information about your version. ## Version numbering +### Stable releases + For stable releases, Linkerd follows a version numbering scheme of the form `2..`. In other words, "2" is a static prefix, followed by the major version, then the minor. @@ -37,6 +43,21 @@ Changes in minor versions are intended to be backwards compatible with the previous version. Changes in major version *may* introduce breaking changes, although we try to avoid that whenever possible. +### Edge releases + +For edge releases, Linkerd issues explicit [guidance about each +release](../../../releases/#edge-release-guidance). Be sure to consult this +guidance before installing any release artifact. + +{{< note >}} + +Edge releases are **not** semantically versioned; the edge release number +itself does not give you any assurance about breaking changes, +incompatibilities, etc. Instead, this information is available in the [release +notes](https://github.com/linkerd/linkerd2/releases). + +{{< /note >}} + ## Upgrade paths The following upgrade paths are generally safe. However, before starting a @@ -44,35 +65,54 @@ deploy, it is important to check the upgrade notes before proceeding—occasionally, specific minor releases may have additional restrictions. -**Within the same major version**. It is usually safe to upgrade to the latest -minor version within the same major version. In other words, if you are -currently running version *2.x.y*, upgrading to *2.x.z*, where *z* is the latest -minor version for major version *x*, is safe. This is true even if you would -skip intermediate intermediate minor versions, i.e. it is still safe even if -*z* > *y + 1*. +**Stable within the same major version**. It is usually safe to upgrade to the +latest minor version within the same major version. In other words, if you are +currently running version *2.x.y*, upgrading to *2.x.z*, where *z* is the +latest minor version for major version *x*, is safe. This is true even if you +would skip intermediate intermediate minor versions, i.e. it is still safe +even if *z* > *y + 1*. -**To the next major version**. It is usually safe to upgrade to the latest minor -version of the *next* major version. In other words, if you are currently -running version *2.x.y*, upgrading to *2.x + 1.w* will be safe, where *w* is the -latest minor version available for major version *x + 1*. +**Stable to the next major version**. It is usually safe to upgrade to the +latest minor version of the *next* major version. In other words, if you are +currently running version *2.x.y*, upgrading to *2.x + 1.w* will be safe, +where *w* is the latest minor version available for major version *x + 1*. -**To later major versions**. Upgrades that skip one or more major versions -are not supported. Instead, you should upgrade major versions incrementally. +**Stable to a later major version**. Upgrades that skip one or more major +versions are not supported. Instead, you should upgrade major versions +incrementally. -Again, please check the upgrade notes for the specific version you are upgrading -*to* for any version-specific caveats. +**Edge release to a later edge release**. This is generally safe unless +the `Cautions` for the later edge release indicate otherwise. + +Again, please check the upgrade notes or release guidance for the specific +version you are upgrading *to* for any version-specific caveats. ## Data plane vs control plane version skew -It is usually safe to run Linkerd's control plane with the data plane from one -major version earlier. (This skew is a natural consequence of upgrading.) This -is independent of minor version, i.e. a *2.x.y* data plane and a *2.x + 1.z* -control plane will work regardless of *y* and *z*. +Since a Linkerd upgrade always starts by upgrading the control plane, there is +a period during which the control plane is running the new version, but the +data plane is still running the older version. The extent to which this skew +can be supported depends on what kind of release you're running. Note that new +features introduced by the release may not be available for workloads with +older data planes. + +### Stable releases + +For stable releases, it is usually safe to upgrade one major version at a +time. This is independent of minor version, i.e. a *2.x.y* data plane and a +*2.x + 1.z* control plane will work regardless of *y* and *z*. Please check +the version-specific upgrade notes before proceeding. -Please check the version-specific upgrade notes before proceeding. +### Edge releases -Note that new features introduced by the release may not be available for -workloads with older data planes. +For edge releases, it is also usually safe to upgrade one major version at a +time. The major version of an edge release is included in the release notes +for each edge release: for example, `edge-24.4.1` is part of Linkerd 2.15, so +it should be safe to upgrade from `edge-24.4.1` to any edge release within +Linkerd 2.15 or Linkerd 2.16. + +For any situation where this is not the case, the edge release guidance will +have more information. ## Overall upgrade process @@ -100,10 +140,17 @@ versions](../../reference/k8s-versions/). The CLI can be used to validate whether Linkerd was installed correctly. +### Stable releases + +Consult the upgrade instructions from the vendor supplying your stable release +for information about how to upgrade the CLI. + +### Edge releases + To upgrade the CLI, run: ```bash -curl --proto '=https' --tlsv1.2 -sSfL https://run.linkerd.io/install | sh +curl --proto '=https' --tlsv1.2 -sSfL https://run.linkerd.io/install-edge | sh ``` Alternatively, you can download the CLI directly via the [Linkerd releases @@ -125,6 +172,9 @@ plane's existing configuration and TLS secrets are retained. Linkerd's CRDs should be upgraded first, using the `--crds` flag, followed by upgrading the control plane. +(If you are using a stable release, your vendor's upgrade instructions may +have more information.) + ```bash linkerd upgrade --crds | kubectl apply -f - linkerd upgrade | kubectl apply -f - @@ -242,12 +292,9 @@ This section contains release-specific information about upgrading. ### Upgrade notice: stable-2.15 and beyond -As of February 2024, the Linkerd project is no longer producing open source -stable release artifacts. Please read the [2.15 -announcement](/2024/02/21/announcing-linkerd-2.15/#a-new-model-for-stable-releases) -for details. - -See [the full list of Linkerd releases](/releases/) for ways to get Linkerd. +As of February 2024, the Linkerd project itself only produces [edge +release](/releases/) artifacts. The [Releases and Versions](/releases/) page +contains more information about the different kinds of Linkerd releases. ### Upgrade notice: stable-2.14.0 diff --git a/linkerd.io/content/releases/_index.md b/linkerd.io/content/releases/_index.md index 864010c01c..2487923272 100644 --- a/linkerd.io/content/releases/_index.md +++ b/linkerd.io/content/releases/_index.md @@ -54,6 +54,12 @@ digits of the year, `m` is the numeric month, and `n` is numeric edge release count for that month. For example, `edge-24.1.3` is the third edge release shipped in January 2024. +Each major version has a corresponding edge release, indicated by +`version-2.X` tags: for example, there is a +[`version-2.15`](https://github.com/linkerd/linkerd2/releases/tag/version-2.15) +tag that corresponds to `edge-24.2.4`. Of course, you may choose to run later +edge releases, which will include further bugfixes and enhancements. + Using edge release artifacts and reporting bugs helps us ensure a rapid pace of development and is a great way to help Linkerd. We publish edge release guidance as part of the release notes and strive to always provide production-ready