Improved install and upgrade guidance (#1756)

* Improved install and upgrade guidance Signed-off-by: Travis Beckham <[email protected]> * wordsmithing Signed-off-by: William Morgan <[email protected]> * attempt to disable invalid markdown lint rule Signed-off-by: William Morgan <[email protected]> --------- Signed-off-by: Travis Beckham <[email protected]> Signed-off-by: William Morgan <[email protected]> Co-authored-by: William Morgan <[email protected]>
linkerd · Apr 8, 2024 · d66d4f8 · d66d4f8
1 parent 7d9d0d4
commit d66d4f8
Show file tree

Hide file tree

Showing 10 changed files with 60 additions and 66 deletions.
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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.
 
-<!-- markdownlint-disable MD033 -->
-Edge releases follow a version numbering scheme of the form `<two digit
-year>.<month>.<number within the month>`. For example, `edge-24.1.2` is the
-second edge release of January 2024.
-<!-- markdownlint-enable MD033 -->
+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:
+<!-- markdownlint-disable MD034 -->
+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
@@ -4,10 +4,11 @@
     {{end}}
     role="alert">
   <div class="message-body">
-    <p>
+    {{ if .title }}
+    <p class="mt-0">
       <i class="fa fa-{{ .icon }}"></i>&nbsp;<strong>{{ .title }}</strong>
     </p>
-
+    {{ end }}
     {{ .content | markdownify }}
   </div>
 </div>
diff --git a/linkerd.io/layouts/partials/sidebar-2.html b/linkerd.io/layouts/partials/sidebar-2.html
@@ -98,7 +98,7 @@
       </li>
       <li class="menu-list-item {{ if eq $currentPage.RelPermalink "/releases/" }}is-active{{ end }}">
         <a href="/releases/">
-          Releases and Versions
+          Releases
         </a>
       </li>
       <li class="menu-list-item {{ if eq $currentPage.RelPermalink "/design-principles/" }}is-active{{ end }}">

diff --git a/linkerd.io/layouts/shortcodes/release-data-table.html b/linkerd.io/layouts/shortcodes/release-data-table.html
@@ -5,24 +5,25 @@
 
   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;
   }
   </style>
 <table>
   <caption>Helm to App version matrix</caption>
   <thead>
     <tr>
        <th class="text-center">Release Name</th>
+       <th></th>
     </tr>
   </thead>
   <tbody>
@@ -40,17 +41,14 @@
             </thead>
             <tbody>
               {{ range $chart_name, $chart_data := $charts }}
-
                 <tr>
-                  <td> <a target="_blank" href="{{ $chart_data.chart_url }}">{{ $chart_name }}</a></td>
-                  <td> {{ $chart_data.chart_version }} </td>
-                  <td> {{ $release_version }} </td>
-
+                  <td><a target="_blank" href="{{ $chart_data.chart_url }}">{{ $chart_name }}</a></td>
+                  <td>{{ $chart_data.chart_version }}</td>
+                  <td>{{ $release_version }}</td>
                 </tr>
               {{ end }}
             </tbody>
           </table>
-
         </td>
       </tr>
     {{ end }}

diff --git a/linkerd.io/layouts/shortcodes/releases.html 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) }}