Merge branch 'main' into ver/dev-v44

linkerd.io/README.md

@@ -4,8 +4,8 @@
 
 Please do not put files in the `static` directory that are referenced on
 linkerd.io. This directory is reserved for assets that are used as external
-resources. If you need to add images for a page, please add them in the [page
-bundle](https://gohugo.io/content-management/page-bundles/).
+resources. If you need to add images for a page, please add them in the
+[page bundle](https://gohugo.io/content-management/page-bundles/).
 
 **Note:** Images in page bundles that have a width or height larger than 2400
 pixels will be downsized.
@@ -27,9 +27,46 @@ date: # The date of your post in the format: `2024-01-01T00:00:00Z`
 slug: # The URL slug for the page. Only set this param if you want to use a different slug than the title.
 keywords: [] # An array of keywords are used to relate blog posts
 params:
-  author: # The author id of the blog post. It must be an author from `data/authors.yaml`
+  author: # The author of the blog post
 ```
 
+#### Assigning an author
+
+There are 2 ways to assign an author to a blog post.
+
+1. If the author has more than one blog post, the author data should be defined
+   in `data/authors.yaml`, then the author id can be set in the frontmatter
+   params. For example:
+
+```yaml
+params:
+  author: william
+```
+
+2. If the author is only going to have a single blog post, the author data can
+   be set inline if desired. For example:
+
+```yaml
+params:
+  author:
+    name: Author name
+    avatar: avatar.png
+```
+
+For inline author data, the avatar image can either be a page resource or a
+remote image. To use a remote image, simply provide the full url to the image,
+and Hugo will download and resize it when the site is published. For example:
+
+```yaml
+params:
+  author:
+    name: John Smith
+    avatar: https://example.com/avatars/john-smith.png
+```
+
+**Note:** If an author only has a single blog post, but there's a chance they
+will have more in the future, please not use the inline method.
+
 #### Cover, thumbnail, and feature images
 
 To associate a cover, thumbnail, or feature image to a blog post, you do not
@@ -48,14 +85,14 @@ blog/
 
 If a blog post is featured, by default, the cover image will be used on the blog
 list page. If a cover image is not present, or you would like to use a different
-image than the cover image, you can name it `feature` and place it in the
-blog post folder.
+image than the cover image, you can name it `feature` and place it in the blog
+post folder.
 
 If a thumbnail image is not present in the blog post folder, the thumbnail image
 will be created from the cover image. By default, the thumbnail image will be
 cropped and resized into a square. If you would like to maintaining the original
-aspect ratio, you can set the `thumbnailProcess` frontmatter param to `fit`.
-For example:
+aspect ratio, you can set the `thumbnailProcess` frontmatter param to `fit`. For
+example:
 
 ```yaml
 params:
@@ -89,8 +126,8 @@ post is shared on social media. For example:
 images: [social.png]
 ```
 
-If the images array is empty, images with names matching `feature`, `cover`,
-or `thumbnail` will be used in that order.
+If the images array is empty, images with names matching `feature`, `cover`, or
+`thumbnail` will be used in that order.
 
 #### Markdown images
 

linkerd.io/config/_default/menu.yaml

@@ -39,6 +39,9 @@ docs:
   - name: Linkerd edge
     pageRef: /2-edge/
     weight: 99
+  - name: Linkerd 2.17
+    pageRef: /2.17/
+    weight: 17
   - name: Linkerd 2.16
     pageRef: /2.16/
     weight: 16

linkerd.io/config/_default/params.yaml

@@ -12,4 +12,4 @@ social:
   twitter: Linkerd
 
 # Latest major version of Linkerd
-latestMajorVersion: "2.16"
+latestMajorVersion: "2.17"

linkerd.io/content/2-edge/features/egress.md

@@ -1,5 +1,6 @@
 ---
 title: Egress
+description: Linkerd features capabilities to monitor and apply policies to egress traffic.
 ---
 
 Linkerd features capabilities to monitor and apply policies to egress traffic.
@@ -21,6 +22,6 @@ more comprehensive approach.
 
 Related content:
 
-* [Guide:  Managing egress traffic]
-  ({{< relref "../tasks/managing-egress-traffic" >}})
+* [Guide: Managing egress traffic]({{< relref
+  "../tasks/managing-egress-traffic" >}})
 * [EgressNetwork Reference]({{< relref "../reference/egress-network" >}})

linkerd.io/content/2-edge/reference/egress-network.md

@@ -1,5 +1,6 @@
 ---
 title: EgressNetwork
+description: Reference guide to the EgressNetwork resource.
 ---
 
 Linkerd's [egress functionality]({{< relref "../features/egress">}}) allows

linkerd.io/content/2.16/reference/k8s-versions.md

@@ -24,6 +24,7 @@ chart below as these situations arise.
 | `2.13`          | `1.21`                     | `1.28`                     |
 | `2.14`          | `1.21`                     | `1.28`                     |
 | `2.15`          | `1.22`                     | `1.29`                     |
+| `2.16`          | `1.22`                     | `1.29`                     |
 {{< /keyval >}}
 
 Note that Linkerd will almost never change the supported Kubernetes version in

linkerd.io/content/2.17/_index.md

@@ -0,0 +1,11 @@
+---
+title: Docs
+cascade:
+  type: docs
+
+# Redirect
+type: _default
+layout: redirect
+params:
+  redirect: ./overview
+---

linkerd.io/content/2.17/checks/index.md

@@ -0,0 +1,10 @@
+---
+title: Checks
+
+# Redirect
+type: _default
+layout: redirect
+params:
+  unlisted: true
+  redirect: /2/tasks/troubleshooting/
+---

linkerd.io/content/2.17/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
+
+{{< docs/section-toc >}}

linkerd.io/content/2.17/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.

linkerd.io/content/2.17/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/).

linkerd.io/content/2.17/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.

linkerd.io/content/2.17/common-errors/protocol-detection.md

@@ -0,0 +1,36 @@
+---
+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.

linkerd.io/content/2.17/features/_index.md

@@ -0,0 +1,14 @@
+---
+title: Features
+weight: 3
+sitemap:
+  priority: 1.0
+---
+
+Linkerd offers many features, outlined below. For our walkthroughs and guides,
+please see the [Linkerd task docs]({{< relref "../tasks" >}}). For a reference,
+see the [Linkerd reference docs]({{< relref "../reference" >}}).
+
+## Linkerd's features
+
+{{< docs/section-toc >}}

linkerd.io/content/2.17/features/access-logging.md

@@ -0,0 +1,62 @@
+---
+title: HTTP Access Logging
+description: Linkerd proxies can be configured to emit HTTP access logs.
+---
+
+Linkerd proxies can be configured to generate an HTTP access log that records
+all HTTP requests that transit the proxy.
+
+The `config.linkerd.io/access-log` annotation is used to enable proxy HTTP
+access logging. Adding this annotation to a namespace or workload configures the
+proxy injector to set an environment variable in the proxy container that
+configures access logging.
+
+HTTP access logging is disabled by default because it has a performance impact,
+compared to proxies without access logging enabled. Enabling access logging may
+increase tail latency and CPU consumption under load. The severity of
+this performance cost may vary depending on the traffic being proxied, and may
+be acceptable in some environments.
+
+{{< note >}}
+The proxy's HTTP access log is distinct from proxy debug logging, which is
+configured separately. See the documentation on [modifying the proxy log
+level](../../tasks/modifying-proxy-log-level/) for details on configuring the
+proxy's debug logging.
+{{< /note >}}
+
+## Access Log Formats
+
+The value of the `config.linkerd.io/access-log` annotation determines the format
+of HTTP access log entries, and can be either "apache" or "json".
+
+Setting the `config.linkerd.io/access-log: "apache"` annotation configures the
+proxy to emit HTTP access logs in the [Apache Common Log
+Format](https://en.wikipedia.org/wiki/Common_Log_Format). For example:
+
+```text {class=disable-copy}
+10.42.0.63:51160 traffic.booksapp.serviceaccount.identity.linkerd.cluster.local - [2022-08-23T20:28:20.071809491Z] "GET http://webapp:7000/ HTTP/2.0" 200
+10.42.0.63:51160 traffic.booksapp.serviceaccount.identity.linkerd.cluster.local - [2022-08-23T20:28:20.187706137Z] "POST http://webapp:7000/authors HTTP/2.0" 303
+10.42.0.63:51160 traffic.booksapp.serviceaccount.identity.linkerd.cluster.local - [2022-08-23T20:28:20.301798187Z] "GET http://webapp:7000/authors/104 HTTP/2.0" 200
+10.42.0.63:51160 traffic.booksapp.serviceaccount.identity.linkerd.cluster.local - [2022-08-23T20:28:20.409177224Z] "POST http://webapp:7000/books HTTP/2.0" 303
+10.42.0.1:43682 - - [2022-08-23T20:28:23.049685223Z] "GET /ping HTTP/1.1" 200
+```
+
+Setting the `config.linkerd.io/access-log: json` annotation configures the proxy
+to emit access logs in a JSON format. For example:
+
+```json {class=disable-copy}
+{"client.addr":"10.42.0.70:32996","client.id":"traffic.booksapp.serviceaccount.identity.linkerd.cluster.local","host":"webapp:7000","method":"GET","processing_ns":"39826","request_bytes":"","response_bytes":"19627","status":200,"timestamp":"2022-08-23T20:33:42.321746212Z","total_ns":"14441135","trace_id":"","uri":"http://webapp:7000/","user_agent":"Go-http-client/1.1","version":"HTTP/2.0"}
+{"client.addr":"10.42.0.70:32996","client.id":"traffic.booksapp.serviceaccount.identity.linkerd.cluster.local","host":"webapp:7000","method":"POST","processing_ns":"30036","request_bytes":"33","response_bytes":"0","status":303,"timestamp":"2022-08-23T20:33:42.436964052Z","total_ns":"14122403","trace_id":"","uri":"http://webapp:7000/authors","user_agent":"Go-http-client/1.1","version":"HTTP/2.0"}
+{"client.addr":"10.42.0.70:32996","client.id":"traffic.booksapp.serviceaccount.identity.linkerd.cluster.local","host":"webapp:7000","method":"GET","processing_ns":"38664","request_bytes":"","response_bytes":"2350","status":200,"timestamp":"2022-08-23T20:33:42.551768300Z","total_ns":"6998222","trace_id":"","uri":"http://webapp:7000/authors/105","user_agent":"Go-http-client/1.1","version":"HTTP/2.0"}
+{"client.addr":"10.42.0.70:32996","client.id":"traffic.booksapp.serviceaccount.identity.linkerd.cluster.local","host":"webapp:7000","method":"POST","processing_ns":"42492","request_bytes":"46","response_bytes":"0","status":303,"timestamp":"2022-08-23T20:33:42.659401621Z","total_ns":"9274163","trace_id":"","uri":"http://webapp:7000/books","user_agent":"Go-http-client/1.1","version":"HTTP/2.0"}
+{"client.addr":"10.42.0.1:56300","client.id":"-","host":"10.42.0.69:7000","method":"GET","processing_ns":"35848","request_bytes":"","response_bytes":"4","status":200,"timestamp":"2022-08-23T20:33:49.254262428Z","total_ns":"1416066","trace_id":"","uri":"/ping","user_agent":"kube-probe/1.24","version":"HTTP/1.1"}
+```
+
+## Consuming Access Logs
+
+The HTTP access log is written to the proxy container's `stderr` stream, while
+the proxy's standard debug logging is written to the proxy container's `stdout`
+stream. Currently, the `kubectl logs` command will always output both the
+container's `stdout` and `stderr` streams. However, [KEP
+3289](https://github.com/kubernetes/enhancements/pull/3289) will add support for
+separating a container's `stdout` or `stderr` in the `kubectl logs` command.