From d66d4f8c373abe4f95b47ee851d945b03ec77b65 Mon Sep 17 00:00:00 2001 From: Travis Beckham Date: Mon, 8 Apr 2024 15:52:01 -0500 Subject: [PATCH] Improved install and upgrade guidance (#1756) * Improved install and upgrade guidance Signed-off-by: Travis Beckham * wordsmithing Signed-off-by: William Morgan * attempt to disable invalid markdown lint rule Signed-off-by: William Morgan --------- Signed-off-by: Travis Beckham Signed-off-by: William Morgan Co-authored-by: William Morgan --- .../content/2.15/getting-started/_index.md | 6 +- .../reference/helm-chart-version-matrix.md | 13 ++++ linkerd.io/content/2.15/tasks/install-helm.md | 2 +- linkerd.io/content/2.15/tasks/install.md | 4 +- linkerd.io/content/2.15/tasks/upgrade.md | 6 ++ linkerd.io/content/releases/_index.md | 70 +++++++------------ linkerd.io/layouts/partials/admonition.html | 5 +- linkerd.io/layouts/partials/sidebar-2.html | 2 +- .../shortcodes/release-data-table.html | 16 ++--- linkerd.io/layouts/shortcodes/releases.html | 2 + 10 files changed, 60 insertions(+), 66 deletions(-) create mode 100644 linkerd.io/content/2.15/reference/helm-chart-version-matrix.md create mode 100644 linkerd.io/layouts/shortcodes/releases.html diff --git a/linkerd.io/content/2.15/getting-started/_index.md b/linkerd.io/content/2.15/getting-started/_index.md index cba8805f0d..4083e74f3a 100644 --- a/linkerd.io/content/2.15/getting-started/_index.md +++ b/linkerd.io/content/2.15/getting-started/_index.md @@ -23,11 +23,7 @@ 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. -{{< note >}} -This page contains quick start instructions intended for non-production -installations. For production-oriented configurations, we suggest reviewing -resources in [Going to Production](/going-to-production/). -{{< /note >}} +{{< releases >}} ## Step 0: Setup diff --git a/linkerd.io/content/2.15/reference/helm-chart-version-matrix.md b/linkerd.io/content/2.15/reference/helm-chart-version-matrix.md new file mode 100644 index 0000000000..5785c30ab3 --- /dev/null +++ b/linkerd.io/content/2.15/reference/helm-chart-version-matrix.md @@ -0,0 +1,13 @@ ++++ +title = "Helm Chart Version Matrix" ++++ + +The following version matrices include only the latest versions of the stable +releases along with corresponding app and Helm versions for Linkerd and +extensions. Use these to guide you to the right Helm chart version or to +automate workflows you might have. + +* [YAML matrix](/releases/release_matrix.yaml) +* [JSON matrix](/releases/release_matrix.json) + +{{< release-data-table />}} diff --git a/linkerd.io/content/2.15/tasks/install-helm.md b/linkerd.io/content/2.15/tasks/install-helm.md index b604602aea..4f300fb372 100644 --- a/linkerd.io/content/2.15/tasks/install-helm.md +++ b/linkerd.io/content/2.15/tasks/install-helm.md @@ -6,7 +6,7 @@ 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. -{{< trylpt >}} +{{< releases >}} ## Prerequisite: generate identity certificates diff --git a/linkerd.io/content/2.15/tasks/install.md b/linkerd.io/content/2.15/tasks/install.md index db824e4c14..da26967ce9 100644 --- a/linkerd.io/content/2.15/tasks/install.md +++ b/linkerd.io/content/2.15/tasks/install.md @@ -16,13 +16,13 @@ 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. -{{< trylpt >}} - In either case, we recommend installing the CLI itself so that you can validate 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/upgrade.md b/linkerd.io/content/2.15/tasks/upgrade.md index c34c8fe026..8926347bee 100644 --- a/linkerd.io/content/2.15/tasks/upgrade.md +++ b/linkerd.io/content/2.15/tasks/upgrade.md @@ -10,6 +10,12 @@ aliases = [ 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. +{{< /note >}} + Read through this guide carefully. Additionally, before starting a specific upgrade, please read through the version-specific upgrade notices below, which may contain important information about your version. diff --git a/linkerd.io/content/releases/_index.md b/linkerd.io/content/releases/_index.md index 97b4db01b3..64bb52543e 100644 --- a/linkerd.io/content/releases/_index.md +++ b/linkerd.io/content/releases/_index.md @@ -1,62 +1,40 @@ +++ -title = "Releases and Versions" +title = "Releases" aliases = [ "edge" ] weight = 18 +++ -Linkerd is developed in the [Linkerd GitHub -repository](https://github.com/linkerd/linkerd2). Releases and packages of -Linkerd are available in several different forms. +Releases and packages of Linkerd are available in several different forms. -## Edge (latest version: {{% latestedge %}}) +## Edge releases (latest version: {{% latestedge %}}) -All Linkerd development happens "on main": all changes, whether in support of -upcoming new features, refactors, bug fixes, or something else, land on the main -branch where they are merged together. +All Linkerd development happens "on main": all changes, whether security +patches, new features, refactors, bug fixes, or something else, land on the main +branch. -Edge releases contain the latest code in from the main branch at the point in -time when they were cut. This means they have the latest features and fixes, but -it also means they don't have stability guarantees. Upgrading between edge -releases may involve breaking changes, and may involve partial features that are -later modified or backed out. +Edge release artifacts contain the latest code in from the main branch, at the +point in time when they were cut. This means they have the latest features and +fixes, but it also means may involve partial features that are later modified or +backed out. They may involve breaking changes—of course, we do our best to avoid +this. -**Note:** Edge releases may introduce breaking changes. +Using edge release artifacts and reporting bugs is a great way to help Linkerd. - -Edge releases follow a version numbering scheme of the form `..`. For example, `edge-24.1.2` is the -second edge release of January 2024. - +The full list of edge release artifacts can be found on +[the Linkerd GitHub releases page](https://github.com/linkerd/linkerd2/releases). -To install the latest edge release via the CLI, you can run: + +Latest version: **{{% latestedge %}}** [[release +notes](https://github.com/linkerd/linkerd2/releases/tag/{{% latestedge %}})]. -```bash -curl --proto '=https' --tlsv1.2 -sSfL https://run.linkerd.io/install-edge | sh -``` +## Stable releases -The full list of edge releases can be found on -[GitHub](https://github.com/linkerd/linkerd2/releases). - -## Stable - -As of Linkerd 2.15.0, the open source project no longer publishes stable -releases. Instead, the vendor community around Linkerd is responsible for -supported, stable releases. - -Known stable distributions of Linkerd include: +As of February 2024, the vendor community around Linkerd is responsible for +supported, stable release artifacts. Known distributions of Linkerd with stable +release artifacts are: * [Buoyant Enterprise for Linkerd](https://docs.buoyant.io/buoyant-enterprise-linkerd) from Buoyant, - creators of Linkerd. - -## Helm Chart Version Matrix - -The following version matrices include only the latest versions of the stable -releases along with corresponding app and Helm versions for Linkerd and -extensions. Use these to guide you to the right Helm chart version or to -automate workflows you might have. - -* [YAML matrix](./release_matrix.yaml) -* [JSON matrix](./release_matrix.json) - -{{< release-data-table />}} + creators of Linkerd. Latest version: + **enterprise-2.15.2** [[release + notes](https://docs.buoyant.io/release-notes/buoyant-enterprise-linkerd/enterprise-2.15.2/)]. diff --git a/linkerd.io/layouts/partials/admonition.html b/linkerd.io/layouts/partials/admonition.html index c207d5913c..0f68e51ce7 100644 --- a/linkerd.io/layouts/partials/admonition.html +++ b/linkerd.io/layouts/partials/admonition.html @@ -4,10 +4,11 @@ {{end}} role="alert">
-

+ {{ if .title }} +

 {{ .title }}

- + {{ end }} {{ .content | markdownify }}
\ No newline at end of file diff --git a/linkerd.io/layouts/partials/sidebar-2.html b/linkerd.io/layouts/partials/sidebar-2.html index ec30e39c16..3907a2e991 100644 --- a/linkerd.io/layouts/partials/sidebar-2.html +++ b/linkerd.io/layouts/partials/sidebar-2.html @@ -98,7 +98,7 @@
  • - Releases and Versions + Releases
  • diff --git a/linkerd.io/layouts/shortcodes/release-data-table.html b/linkerd.io/layouts/shortcodes/release-data-table.html index 5c83adee91..5d0b7d7e83 100644 --- a/linkerd.io/layouts/shortcodes/release-data-table.html +++ b/linkerd.io/layouts/shortcodes/release-data-table.html @@ -5,17 +5,17 @@ table{ border-collapse:collapse; - border:1px solid #000000; + border:1px solid #DBDBDB; } th, td { padding: 5px; } table td{ - border:1px solid #000000; + border:1px solid #DBDBDB; } table th{ - border:1px solid #000000; + border:1px solid #DBDBDB; } @@ -23,6 +23,7 @@ + @@ -40,17 +41,14 @@ {{ range $chart_name, $chart_data := $charts }} - - - - - + + + {{ end }}
    Release Name
    {{ $chart_name }} {{ $chart_data.chart_version }} {{ $release_version }} {{ $chart_name }}{{ $chart_data.chart_version }}{{ $release_version }}
    - {{ end }} diff --git a/linkerd.io/layouts/shortcodes/releases.html b/linkerd.io/layouts/shortcodes/releases.html new file mode 100644 index 0000000000..2fc4ff420c --- /dev/null +++ b/linkerd.io/layouts/shortcodes/releases.html @@ -0,0 +1,2 @@ +{{ $content := "This page contains instructions using the latest edge release of Linkerd. For other types of releases, including stable releases, please see [Linkerd Releases](/releases/)." | markdownify -}} +{{ partial "admonition.html" (dict "type" "info" "icon" "info-circle" "id" (.Get "id") "title" "Edge release content" "content" $content) }}