Skip to content

Commit

Permalink
Merge branch 'main' into feature-ambassador
Browse files Browse the repository at this point in the history
  • Loading branch information
@kflynn
kflynn committed Jun 24, 2024
2 parents f43786e + a2fca37 commit 3b50083
Show file tree
Hide file tree
Showing 5 changed files with 121 additions and 65 deletions.
38 changes: 18 additions & 20 deletions linkerd.io/content/2.15/reference/k8s-versions.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
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
109 changes: 78 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,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). 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.

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

Expand Down Expand Up @@ -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
Expand All @@ -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 -
Expand Down Expand Up @@ -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

Expand Down
6 changes: 6 additions & 0 deletions linkerd.io/content/releases/_index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down

0 comments on commit 3b50083

Please sign in to comment.