Update edge-release info with guidance info and better stable pointers

Signed-off-by: Flynn <[email protected]>

linkerd.io/content/2.15/getting-started/_index.md

@@ -14,16 +14,28 @@ 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.
+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!).
 
-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.
+As of February 2024, the Linkerd project only produces edge releases. Using
+them and [reporting bugs](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.
 
-{{< releases >}}
+## 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 +68,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 +86,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:
 

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

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

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.<major>.<minor>`. In other words, "2" is a static prefix, followed by the
 major version, then the minor.
@@ -37,39 +43,76 @@ 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
 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