From e948b95d1dbdfe5f53e59e81104b281bb5369bed Mon Sep 17 00:00:00 2001 From: Flynn Date: Tue, 7 May 2024 17:00:37 -0400 Subject: [PATCH] Update edge-release info with guidance info and better stable pointers Signed-off-by: Flynn --- .../content/2.15/getting-started/_index.md | 42 ++++--- linkerd.io/content/2.15/tasks/install-helm.md | 20 +++- linkerd.io/content/2.15/tasks/install.md | 20 +++- linkerd.io/content/2.15/tasks/upgrade.md | 111 +++++++++++++----- linkerd.io/content/releases/_index.md | 92 +++++++++++---- 5 files changed, 219 insertions(+), 66 deletions(-) diff --git a/linkerd.io/content/2.15/getting-started/_index.md b/linkerd.io/content/2.15/getting-started/_index.md index 3adedd5f40..7a57abab4c 100644 --- a/linkerd.io/content/2.15/getting-started/_index.md +++ b/linkerd.io/content/2.15/getting-started/_index.md @@ -14,16 +14,29 @@ weight = 2 Welcome to Linkerd! 🎈 -In this guide, we'll walk you through how to install Linkerd into your -Kubernetes cluster. Then we'll deploy a sample application to show off what -Linkerd can do. - -This guide is designed to walk you through the basics of Linkerd. First, you'll -install the *CLI* (command-line interface) onto your local machine. Using this -CLI, you'll then install the *control plane* onto your Kubernetes cluster. -Finally, you'll "mesh" an application by adding Linkerd's *data plane* to it. - -{{< releases >}} +In this guide, we'll walk you through how to install the latest _edge release_ +of Linkerd into your Kubernetes cluster. New edge releases usually appear +weekly, and always represent the latest and greatest development work being +done on Linkerd. This means that edge releases always have the latest new +features and fixes, but of course they may also have bugs, work that's later +backed out, or breaking changes (though we try to avoid these things!). + +As of February 2024, the Linkerd project only produces edge releases. Using +them and [reporting +bugs](https://github.com/linkerd/linkerd2/issues/new/choose) is a great way to +help Linkerd! But if that isn't for you, no problem -- check out [Linkerd +releases](/releases/) for more about _stable releases_ from the vendor +community. + +## Overview + +First you'll install the Linkerd *CLI* (command-line interface) onto your +local machine. Using this CLI, you'll then install the Linkerd *control plane* +onto your Kubernetes cluster. Finally, you'll install a sample application and +"mesh" it by adding Linkerd's *data plane* to it, so that you can put Linkerd +through its paces. + +This may sound complex, but in practice it's pretty simple -- let's get to it! ## Step 0: Setup @@ -56,11 +69,13 @@ the next step. ## Step 1: Install the CLI +{{< releases >}} + If this is your first time running Linkerd, you will need to download the `linkerd` CLI onto your local machine. The CLI will allow you to interact with your Linkerd deployment. -To install the CLI manually, run: +To install the CLI for the latest edge release manually, run: ```bash curl --proto '=https' --tlsv1.2 -sSfL https://run.linkerd.io/install-edge | sh @@ -72,9 +87,8 @@ Be sure to follow the instructions to add it to your path: export PATH=$HOME/.linkerd2/bin:$PATH ``` -This will install the CLI for the latest _edge release_ of Linkerd. (For more -information about what edge releases are, see our [Releases and -Versions](../../releases/) page.) +Again, this will install the CLI for the latest edge release of Linkerd. For +more information, see [Linkerd Releases](../../releases/). Once installed, verify the CLI is running correctly with: diff --git a/linkerd.io/content/2.15/tasks/install-helm.md b/linkerd.io/content/2.15/tasks/install-helm.md index 0628274ef2..cd8d0b9992 100644 --- a/linkerd.io/content/2.15/tasks/install-helm.md +++ b/linkerd.io/content/2.15/tasks/install-helm.md @@ -6,7 +6,19 @@ description = "Install Linkerd onto your Kubernetes cluster using Helm." Linkerd can be installed via Helm rather than with the `linkerd install` command. This is recommended for production, since it allows for repeatability. -{{< releases >}} +{{< warning >}} + +As of February 2024, the Linkerd project is no longer producing open source +stable release artifacts. As such, this page contains instructions for using +Helm to install the latest edge release of Linkerd, and `helm.linkerd.io` does +not contain Helm charts for stable releases after `stable-2.14`. If you have +installed a [stable distribution](/releases/#stable) of Linkerd, the vendor +should provide additional guidance on how to use Helm. + +You can find more information about the different kinds of Linkerd releases on +the [Releases and Versions](/releases/) page. + +{{< /warning >}} ## Prerequisite: generate mTLS certificates @@ -21,6 +33,12 @@ generate these. ## Helm install procedure +As noted in the warning above, **this page contains instructions for using +Helm to install the latest edge release of Linkerd** and `helm.linkerd.io` +does not contain charts for stable releases after `stable-2.15`. You can find +more information about the different kinds of Linkerd releases on the +[Releases and Versions](/releases/) page. + ```bash # Add the Helm repo for Linkerd edge releases: helm repo add linkerd-edge https://helm.linkerd.io/edge diff --git a/linkerd.io/content/2.15/tasks/install.md b/linkerd.io/content/2.15/tasks/install.md index da26967ce9..7a24401df7 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. +{{< warning >}} + +As of February 2024, the Linkerd project is no longer producing open source +stable release artifacts. As such, this page contains instructions for +installing the latest edge release of Linkerd. If you have installed a [stable +distribution](/releases/#stable) of Linkerd, the vendor should provide +additional guidance on installing Linkerd. + +You can find more information about the different kinds of Linkerd releases on +the [Releases and Versions](/releases/) page. + +{{< /warning >}} + 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 @@ -63,6 +74,11 @@ install --crds`, which installs the Linkerd CRDs, followed by `linkerd install`, which installs the Linkerd control plane. Both of these commands generate Kubernetes manifests, which can be applied to your cluster to install Linkerd. +As noted in the warning above, **this page contains instructions for +installing the latest edge release of Linkerd**. You can find more information +about the different kinds of Linkerd releases on the [Releases and +Versions](/releases/) page. + For example: ```bash diff --git a/linkerd.io/content/2.15/tasks/upgrade.md b/linkerd.io/content/2.15/tasks/upgrade.md index 336b464456..33610a19ed 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 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. 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). Before installing an edge +release, always consult the guidance for that release! + +{{< warning >}} + +Edge releases are **not** semantically versioned; the edge release number +itself does not give you any assurance about breaking changes, +incompatibilities, etc. **Always** read the guidance for a given edge release +before installing it! + +{{< /warning >}} + ## Upgrade paths The following upgrade paths are generally safe. However, before starting a @@ -44,32 +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*. + +**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*. + +**Stable to a later major version**. Upgrades that skip one or more major +versions are not supported. Instead, you should upgrade major versions +incrementally. -**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*. +**Edge release to a RECOMMENDED edge release**. This is generally safe unless +the `Cautions` for the later edge release indicate otherwise. -**To later major versions**. Upgrades that skip one or more major versions -are not supported. Instead, you should upgrade major versions incrementally. +{{< warning >}} -Again, please check the upgrade notes for the specific version you are upgrading -*to* for any version-specific caveats. +It is possible for a **RECOMMENDED** edge release to still contain breaking +changes. These will be called out in the `Cautions` for that release. + +{{< /warning >}} + +**Edge release to a NOT RECOMMENDED edge release**. As the guidance implies, +this is **not recommended**. The `Cautions` for the later release should have +more information. + +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*. +### Stable releases + +For stable releases, 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*. Please check the version-specific upgrade notes before proceeding. + +### Edge releases -Please check the version-specific upgrade notes before proceeding. +At present, edge releases support control planes of version stable-2.14.0 or +later. Edge release guidance will have more information as it becomes +necessary. Note that new features introduced by the release may not be available for workloads with older data planes. @@ -100,10 +143,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 +175,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 - @@ -243,11 +296,15 @@ 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. +stable release artifacts. The [Releases and Versions](/releases/) page +contains more information about the different kinds of Linkerd releases. + +Known distributions of Linkerd with stable release artifacts include: -See [the full list of Linkerd releases](/releases/) for ways to get Linkerd. +- [Buoyant Enterprise for + Linkerd](https://docs.buoyant.io/buoyant-enterprise-linkerd) from Buoyant, + creators of Linkerd ([upgrade + instructions](https://docs.buoyant.io/buoyant-enterprise-linkerd/latest/upgrade/)) ### Upgrade notice: stable-2.14.0 diff --git a/linkerd.io/content/releases/_index.md b/linkerd.io/content/releases/_index.md index d88cf58b3d..162e58a656 100644 --- a/linkerd.io/content/releases/_index.md +++ b/linkerd.io/content/releases/_index.md @@ -1,21 +1,26 @@ +++ -title = "Releases and Versions" +title = "Releases" aliases = [ "edge" ] weight = 18 +++ -Releases of Linkerd are available in several different forms. +Releases and packages of Linkerd are available in several different forms. ## Stable releases -Stable release artifacts of Linkerd follow semantic versioning, whereby changes -in major version denote large feature additions and possible breaking changes -and changes in minor versions denote safe upgrades without breaking changes. +Stable release artifacts of Linkerd follow semantic versioning, with version +numbers of the form `2.major.minor` (in other words, `2` is a static prefix, +followed by the major version, then the minor). Changes in major version +denote large feature additions and possible breaking changes; changes in minor +versions denote safe upgrades without breaking changes. -As of February 2024, Linkerd no longer provides stable release artifacts in the -open source project itself. Instead, the vendor community around Linkerd is -responsible for creating stable release artifacts. Known distributions of -Linkerd with stable release artifacts include: +As of February 2024, the the vendor community around Linkerd is responsible +for supported, stable release artifacts, with the Linkerd project itself only +producing edge release artifacts. Please read the [Linkerd 2.15.0 +announcement](/2024/02/21/announcing-linkerd-2.15/#a-new-model-for-stable-releases) +for more details. + +Known distributions of Linkerd with stable release artifacts include: - [Buoyant Enterprise for Linkerd](https://docs.buoyant.io/buoyant-enterprise-linkerd) from Buoyant, creators of Linkerd. @@ -24,17 +29,19 @@ Linkerd with stable release artifacts include: ## Edge releases -Edge release artifacts are published on a weekly or near-weekly basis as part of -the open source project. The full list of edge release artifacts can be found on -[the Linkerd GitHub releases +Edge release artifacts are published on a weekly or near-weekly basis as part +of the open source project. The full list of edge release artifacts can be +found on [the Linkerd GitHub releases page](https://github.com/linkerd/linkerd2/releases). -Edge release artifacts contain the code in from the _main_ branch at the point -in time when they were cut. This means they always have the latest features and -fixes, and have undergone automated testing as well as maintianer code review. -Edge releases may involve partial features that are later modified or backed -out. They may also involve breaking changes—of course, we do our best to avoid -this. +Edge release artifacts contain the code in from the `main` branch at the point +in time when they were cut. Since all Linkerd development happens on `main` - +meaning that all changes land on the `main` branch, whether security patches, +features, bugfixes, or whatever else - this means they always have the latest +features and fixes, and have undergone automated testing as well as maintainer +code review. Edge releases may involve partial features that are later +modified or backed out. They may also involve breaking changes—of course, we +do our best to avoid this. Edge release versioning follows the form `edge-y.m.n`, where `y` is the last two digits of the year, `m` is the numeric month, and `n` is numeric edge release @@ -43,10 +50,51 @@ count for that month. For example: - `edge-23.9.1`: the first edge release shipped in September 2023 - `edge-24.1.3`: the third edge release shipped in January 2024 -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 -artifacts. +Using edge release artifacts and [reporting +bugs](https://github.com/linkerd/linkerd2/issues/new/choose) helps us ensure a rapid +pace of development and is a great way to help Linkerd. + +### Edge Release Guidance + +While we strive to always provide production-ready artifacts, we also publish +guidance for each edge release as part of its release notes, reflecting the +latest experience from the field. **This guidance can change over time**: as +we get new feedback from the field about a particular release, we will update +its guidance. + +Release notes show an `Overall Status`, `Cautions`, and `Changes`. + +#### Overall Status + +The `Overall Status` will be one of the following: + +[badge-recommended]: https://img.shields.io/badge/release_status-RECOMMENDED-lightgreen?logo=Linkerd +[badge-not-recommended]: https://img.shields.io/badge/release_status-NOT_RECOMMENDED-red?logo=Linkerd + +![RECOMMENDED][badge-recommended] + +**RECOMMENDED**: This release should be fine for general use. Note that a +Recommended release may still describe `Cautions`: if any are listed, read +them carefully to make sure they won't affect you. + +![NOT RECOMMENDED][badge-not-recommended] + +**NOT RECOMMENDED**: This release may work in some cases, but in general it is +not a good candidate for general use; the `Cautions` should explain why. Any +release marked with **NOT RECOMMENDED** will also recommend a release to +consider instead. + +#### `Cautions` + +The `Cautions` section will list any particular things that warrant special +attention before installing the release. In many cases, no `Cautions` will be +listed. + +#### `Changes` + +The `Changes` section will start with a short summary of significant changes, +then continue with the full changelog for the release. You should **always** +read at least the summary section before installing a release.