From 6a52c6bef98975015933003ce836d0d6dff09dfd Mon Sep 17 00:00:00 2001 From: Travis Beckham Date: Wed, 3 Apr 2024 08:19:12 -0500 Subject: [PATCH 01/18] Updated runbook link in Going to Production page (#1755) Signed-off-by: Travis Beckham --- linkerd.io/content/going-to-production/_index.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/linkerd.io/content/going-to-production/_index.md b/linkerd.io/content/going-to-production/_index.md index 5476e729bb..561e3092a3 100644 --- a/linkerd.io/content/going-to-production/_index.md +++ b/linkerd.io/content/going-to-production/_index.md @@ -3,9 +3,9 @@ title = "Going to Production" weight = 20 +++ -The Linkerd project itself doesn't provide a formal guide for deploying Linkerd to -a production environment. Below are some external resources that might prove +The Linkerd project itself doesn't provide a formal guide for deploying Linkerd +to a production environment. Below are some external resources that might prove helpful: -- [Buoyant's Linkerd Production Runbook](https://docs.buoyant.io/runbook/), +- [Buoyant's production-grade installation](https://docs.buoyant.io/buoyant-enterprise-linkerd/latest/installation/production/), from the creators of Linkerd. From 7d9d0d468d3bf1aff003fda7e2c1fdb648cbe11e Mon Sep 17 00:00:00 2001 From: Flynn Date: Thu, 4 Apr 2024 09:46:40 -0400 Subject: [PATCH 02/18] Have a "common errors" page. (#1752) * Have a "common errors" page. Signed-off-by: Flynn * Put "Common Errors" last in the TOC Signed-off-by: Flynn * Revert unneeded sidebar-2 change Signed-off-by: Flynn * Grr lint Signed-off-by: Flynn --------- Signed-off-by: Flynn --- .../content/2.15/common-errors/_index.md | 21 +++++++++++ .../content/2.15/common-errors/failfast.md | 18 ++++++++++ .../content/2.15/common-errors/http-502.md | 11 ++++++ .../2.15/common-errors/http-503-504.md | 27 ++++++++++++++ .../2.15/common-errors/protocol-detection.md | 35 +++++++++++++++++++ 5 files changed, 112 insertions(+) create mode 100644 linkerd.io/content/2.15/common-errors/_index.md create mode 100644 linkerd.io/content/2.15/common-errors/failfast.md create mode 100644 linkerd.io/content/2.15/common-errors/http-502.md create mode 100644 linkerd.io/content/2.15/common-errors/http-503-504.md create mode 100644 linkerd.io/content/2.15/common-errors/protocol-detection.md diff --git a/linkerd.io/content/2.15/common-errors/_index.md b/linkerd.io/content/2.15/common-errors/_index.md new file mode 100644 index 0000000000..d635b5ef95 --- /dev/null +++ b/linkerd.io/content/2.15/common-errors/_index.md @@ -0,0 +1,21 @@ ++++ +title = "Common Errors" +weight = 10 +[sitemap] + priority = 1.0 ++++ + +Linkerd is generally robust, but things can always go wrong! You'll find +information here about the most common things that cause people trouble. + +## When in Doubt, Start With `linkerd check` + +Whenever you see anything that looks unusual about your mesh, **always** start +with `linkerd check`. It will check a long series of things that have caused +trouble for others and make sure that your configuration is sane, and it will +point you to help for any problems it finds. It's hard to overstate how useful +this command is. + +## Common Errors + +{{% sectiontoc "common-errors" %}} diff --git a/linkerd.io/content/2.15/common-errors/failfast.md b/linkerd.io/content/2.15/common-errors/failfast.md new file mode 100644 index 0000000000..5cd78c354e --- /dev/null +++ b/linkerd.io/content/2.15/common-errors/failfast.md @@ -0,0 +1,18 @@ ++++ +title = "Failfast" +description = "Failfast means that no endpoints are available." ++++ + +If Linkerd reports that a given service is in the _failfast_ state, it +means that the proxy has determined that there are no available endpoints +for that service. In this situation there's no point in the proxy trying +to actually make a connection to the service - it already knows that it +can't talk to it - so it reports that the service is in failfast and +immediately returns an error from the proxy. + +The error will be either a 503 or a 504; see below for more information, +but if you already know that the service is in failfast because you saw +it in the logs, that's the important part. + +To get out of failfast, some endpoints for the service have to +become available. diff --git a/linkerd.io/content/2.15/common-errors/http-502.md b/linkerd.io/content/2.15/common-errors/http-502.md new file mode 100644 index 0000000000..7205d049a1 --- /dev/null +++ b/linkerd.io/content/2.15/common-errors/http-502.md @@ -0,0 +1,11 @@ ++++ +title = "HTTP 502 Errors" +description = "HTTP 502 means connection errors between proxies." ++++ + +The Linkerd proxy will return a 502 error for connection errors between +proxies. Unfortunately it's fairly common to see an uptick in 502s when +first meshing a workload that hasn't previously been used with a mesh, +because the mesh surfaces errors that were previously invisible! + +There's actually a whole page on [debugging 502s](../../tasks/debugging-502s/). diff --git a/linkerd.io/content/2.15/common-errors/http-503-504.md b/linkerd.io/content/2.15/common-errors/http-503-504.md new file mode 100644 index 0000000000..a8777413af --- /dev/null +++ b/linkerd.io/content/2.15/common-errors/http-503-504.md @@ -0,0 +1,27 @@ ++++ +title = "HTTP 503 and 504 Errors" +description = "HTTP 503 and 504 mean overloaded workloads." ++++ + +503s and 504s show up when a Linkerd proxy is trying to make so many +requests to a workload that it gets overwhelmed. + +When the workload next to a proxy makes a request, the proxy adds it +to an internal dispatch queue. When things are going smoothly, the +request is pulled from the queue and dispatched almost immediately. +If the queue gets too long, though (which can generally happen only +if the called service is slow to respond), the proxy will go into +_load-shedding_, where any new request gets an immediate 503. The +proxy can only get _out_ of load-shedding when the queue shrinks. + +Failfast also plays a role here: if the proxy puts a service into +failfast while there are requests in the dispatch queue, all the +requests in the dispatch queue get an immediate 504 before the +proxy goes into load-shedding. + +To get out of failfast, some endpoints for the service have to +become available. + +To get out of load-shedding, the dispatch queue has to start +emptying, which implies that the service has to get more capacity +to process requests or that the incoming request rate has to drop. diff --git a/linkerd.io/content/2.15/common-errors/protocol-detection.md b/linkerd.io/content/2.15/common-errors/protocol-detection.md new file mode 100644 index 0000000000..515b065515 --- /dev/null +++ b/linkerd.io/content/2.15/common-errors/protocol-detection.md @@ -0,0 +1,35 @@ ++++ +title = "Protocol Detection Errors" +description = "Protocol detection errors indicate that Linkerd doesn't understand the protocol in use." ++++ + +Linkerd is capable of proxying all TCP traffic, including TLS connections, +WebSockets, and HTTP tunneling. In most cases where the client speaks first +when a new connection is made, Linkerd can detect the protocol in use, +allowing it to perform per-request routing and metrics. + +If your proxy logs contain messages like `protocol detection timed out after +10s`, or you're experiencing 10-second delays when establishing connections, +you're probably running a situation where Linkerd cannot detect the protocol. +This is most common for protocols where the server speaks first, and the +client is waiting for information from the server. It may also occur with +non-HTTP protocols for which Linkerd doesn't yet understand the wire format of +a request. + +You'll need to understand exactly what the situation is to fix this: + +- A server-speaks-first protocol will probably need to be configured as a + `skip` or `opaque` port, as described in the [protocol detection + documentation](../../features/protocol-detection/#configuring-protocol-detection). + +- If you're seeing transient protocol detection timeouts, this is more likely + to indicate a misbehaving workload. + +- If you know the protocol is client-speaks-first but you're getting + consistent protocol detection timeouts, you'll probably need to fall back on + a `skip` or `opaque` port. + +Note that marking ports as `skip` or `opaque` has ramifications beyond +protocol detection timeouts; see the [protocol detection +documentation](../../features/protocol-detection/#configuring-protocol-detection) +for more information. From d66d4f8c373abe4f95b47ee851d945b03ec77b65 Mon Sep 17 00:00:00 2001 From: Travis Beckham Date: Mon, 8 Apr 2024 15:52:01 -0500 Subject: [PATCH 03/18] 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 @@