Skip to content

Commit

Permalink
Update edge-release info
Browse files Browse the repository at this point in the history 
Signed-off-by: Flynn <[email protected]>
  • Loading branch information
@kflynn
kflynn committed Jun 6, 2024
1 parent 6f62d5d commit c3056d6
Show file tree
Hide file tree
Showing 3 changed files with 103 additions and 45 deletions.
15 changes: 13 additions & 2 deletions linkerd.io/content/2.15/tasks/install.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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
Expand Down
18 changes: 6 additions & 12 deletions linkerd.io/content/2.15/tasks/troubleshooting.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
<!-- markdownlint-disable MD036 -->
Expand Down Expand Up @@ -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.
<!-- markdownlint-disable MD036 -->
Expand Down
115 changes: 84 additions & 31 deletions linkerd.io/content/2.15/tasks/upgrade.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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.
Expand All @@ -37,42 +43,82 @@ 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
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.

### Edge releases

For edge releases, it is also usually safe to upgrade one major version at a
time. The "major version" of an edge release is indicated by the most recent
`version-2.X` tag before the edge release tag in question; this is also
included in the release notes for each edge release.

Please check the version-specific upgrade notes before proceeding.
For example, `edge-24.4.1` is within major version 2.15: the most recent
`version-2.X` tag before `edge-24.4.1` is
[`version-2.15`](https://github.com/linkerd/linkerd2/releases/tag/version-2.15),
which corresponds to `edge-24.2.4`. Therefore, it should be safe to upgrade
from `edge-24.2.4` to any edge release within 2.15 or 2.16, but not to any
edge release produced after `version-2.17` is tagged.

Note that new features introduced by the release may not be available for
workloads with older data planes.
For any situation where this is not the case, the edge release guidance will
have more information.

## Overall upgrade process

Expand Down Expand Up @@ -100,10 +146,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
Expand All @@ -125,6 +178,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 -
Expand Down Expand Up @@ -242,12 +298,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

Expand Down

0 comments on commit c3056d6

Please sign in to comment.