document HTTPRoute timeouts (#1662)

This branch adds new documentation for the HTTPRoute timeout fields
added in Linkerd 2.14. This includes adding the HTTPRoute timeout fields
to the HTTPRoute reference docs, and adding a section on using HTTPRoute
timeouts to the "Configuring Timeouts" tasks doc.

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

@@ -15,6 +15,8 @@ to that resource, based on parameters such as the request's path, method, and
 headers, and can configure how requests matching that rule are routed by the
 Linkerd service mesh.
 
+## Inbound and Outbound HTTPRoutes
+
 Two types of HTTPRoute are used for configuring the behavior of Linkerd's
 proxies:
 
@@ -38,17 +40,17 @@ configuration, as long as the ServiceProfile
 exists.
 {{< /warning >}}
 
+## Learn More
+
 To get started with HTTPRoutes, you can:
 
-<!-- TODO(eliza): add this link once the timeout doc discusses HTTPRoutes...
-- [Configure timeouts][timeouts] using an outbound HTTPRoute.
--->
 <!-- TODO(eliza): add this link once the fault injection doc discusses
   HTTPRoutes...
 - [Configure fault injection](../../tasks/fault-injection/) using an outbound
   HTTPRoute.
 -->
 
+- [Configure timeouts][timeouts] using an outbound HTTPRoute.
 - [Configure dynamic request routing][dyn-routing] using an outbound HTTPRoute.
 - [Configure per-route authorization policy][auth-policy] using an inbound
   HTTPRoute.
@@ -61,4 +63,4 @@ To get started with HTTPRoutes, you can:
 [Server]: ../../reference/authorization-policy/#server
 [auth-policy]: ../../tasks/configuring-per-route-policy/
 [dyn-routing]:../../tasks/configuring-dynamic-request-routing/
-[timeouts]: ../../tasks/configuring-dynamic-request-routing/
+[timeouts]: ../../tasks/configuring-timeouts/#using-httproutes

linkerd.io/content/2-edge/reference/httproute.md

@@ -59,6 +59,7 @@ HTTPRouteRule defines semantics for matching an HTTP request based on conditions
 | `matches`| A list of [httpRouteMatches](#httproutematch). Each match is independent, i.e. this rule will be matched if **any** one of the matches is satisfied.|
 | `filters`| A list of [httpRouteFilters](#httproutefilter) which will be applied to each request which matches this rule.|
 | `backendRefs`| An array of [HTTPBackendRefs](#httpbackendref) to declare where the traffic should be routed to (only allowed with Service [parentRefs](#parentreference)).|
+| `timeouts` | An optional [httpRouteTimeouts](#httproutetimeouts) object which configures timeouts for requests matching this rule. |
 {{< /table >}}
 
 ### httpRouteMatch
@@ -190,6 +191,32 @@ sent to. Only allowed when a route has Service [parentRefs](#parentReference).
 | `weight`| Proportion of requests sent to this backend.|
 {{< /table >}}
 
+### httpRouteTimeouts
+
+`HTTPRouteTimeouts` defines the timeouts that can be configured for an HTTP
+request.
+
+Linkerd implements HTTPRoute timeouts as described in [GEP-1742]. Timeout
+durations are specified as strings using the [Gateway API duration format]
+specified by [GEP-2257](https://gateway-api.sigs.k8s.io/geps/gep-2257/) (e.g.
+1h/1m/1s/1ms), and MUST be at least 1ms. A timeout field with duration 0
+disables that timeout.
+
+{{< table >}}
+| field| value |
+|------|-------|
+| `request` | Specifies the duration for processing an HTTP client request after which the proxy will time out if unable to send a response. When this field is unspecified or 0, the proxy will not enforce request timeouts. |
+| `backendRequest` | Specifies a timeout for an individual request from the proxy to a backend service. This covers the time from when the request first starts being sent from the proxy to when the response has been received from the backend. When this field is unspecified or 0, the proxy will not enforce a backend request timeout, but may still enforce the `request` timeout, if one is configured. |
+{{< /table >}}
+
+If retries are enabled, a request received by the proxy may be retried by
+sending it to a different backend. In this case, a new `backendRequest` timeout
+will be started for each retry request, but each retry request will count
+against the overall `request` timeout.
+
+[GEP-1742]: https://gateway-api.sigs.k8s.io/geps/gep-1742/
+[Gateway API duration format]: https://gateway-api.sigs.k8s.io/geps/gep-2257/#gateway-api-duration-format
+
 ## HTTPRoute Examples
 
 An HTTPRoute attached to a Server resource which matches GETs to

linkerd.io/content/2-edge/tasks/configuring-timeouts.md

@@ -4,16 +4,77 @@ description = "Configure Linkerd to automatically fail requests that take too lo
 +++
 
 To limit how long Linkerd will wait before failing an outgoing request to
-another service, you can configure timeouts. Timeouts can be specified using
-either [HTTPRoute]s or [service profile](../../features/service-profiles/) for
-the service you're sending requests to.
+another service, you can configure timeouts. Timeouts specify the maximum amount
+of time to wait for a response from a remote service to complete after the
+request is sent. If the timeout elapses without receiving a response, Linkerd
+will cancel the request and return a [504 Gateway Timeout] response.
+
+Timeouts can be specified either [using HTTPRoutes](#using-httproutes) or [using
+legacy ServiceProfiles](#using-serviceprofiles). Since [HTTPRoute] is a newer
+configuration mechanism intended to replace [ServiceProfile]s, prefer the use of
+HTTPRoute timeouts unless a ServiceProfile already exists for the Service.
+
+## Using HTTPRoutes
+
+Linkerd supports timeouts as specified in [GEP-1742], for [outbound
+HTTPRoutes](../../features/httproute/#inbound-and-outbound-httproutes)
+with Service parents.
+
+{{< warning >}}
+Support for [GEP-1742](https://gateway-api.sigs.k8s.io/geps/gep-1742/) has not
+yet been implemented by the upstream Gateway API HTTPRoute resource. The GEP has
+been accepted, but it has not yet been added to the definition of the HTTPRoute
+resource. This means that HTTPRoute timeout fields can currently be used only in
+HTTPRoute resources with the `policy.linkerd.io` API group, *not* the
+`gateway.networking.k8s.io` API group.
+
+When the [GEP-1742](https://gateway-api.sigs.k8s.io/geps/gep-1742/) timeout
+fields are added to the upstream resource definition, Linkerd will support
+timeout configuration for HTTPRoutes with both API groups.
+{{< /warning >}}
+
+Each [rule](../../reference/httproute/#httprouterule) in an [HTTPRoute] may
+define an optional [`timeouts`](../../reference/httproute/#httproutetimeouts)
+object, which can define `request` and/or `backendRequest` fields:
+
+- `timeouts.request` specifies the *total time* to wait for a request matching
+  this rule to complete (including retries). This timeout starts when the proxy
+  receives a request, and ends when successful response is sent to the client.
+- `timeouts.backendRequest` specifies the time to wait for a single request to a
+  backend to complete. This timeout starts when a request is dispatched to a
+  [backend](../../reference/httproute/#httpbackendref), and ends when a response
+  is received from that backend. This is a subset of the `timeouts.request`
+  timeout. If the request fails and is retried (if applicable), the
+  `backendRequest` timeout will be restarted for each retry request.
+
+Timeout durations are specified specified as strings using the [Gateway API
+duration format] specified by
+[GEP-2257](https://gateway-api.sigs.k8s.io/geps/gep-2257/)
+(e.g. 1h/1m/1s/1ms), and must be at least 1ms. If either field is unspecified or
+set to 0, the timeout configured by that field will not be enforced.
+
+For example:
+
+```yaml
+spec:
+  rules:
+  - matches:
+    - path:
+        type: RegularExpression
+        value: /authors/[^/]*\.json"
+      method: GET
+    timeouts:
+      request: 600ms
+      backendRequest: 300ms
+```
 
 ## Using ServiceProfiles
 
-Each route may define a timeout which specifies the maximum amount of time to
-wait for a response (including retries) to complete after the request is sent.
-If this timeout is reached, Linkerd will cancel the request, and return a 504
-response.  If unspecified, the default timeout is 10 seconds.
+Each [route](../../reference/service-profiles/#route) in a [ServiceProfile] may
+define a request timeout for requests matching that route. This timeout secifies
+the maximum amount of time to wait for a response (including retries) to
+complete after the request is sent. If unspecified, the default timeout is 10
+seconds.
 
 ```yaml
 spec:
@@ -26,12 +87,12 @@ spec:
 ```
 
 Check out the [timeouts section](../books/#timeouts) of the books demo for
-a tutorial of how to configure timeouts.
+a tutorial of how to configure timeouts using ServiceProfiles.
 
 ## Monitoring Timeouts
 
-Requests which reach the timeout will be canceled, return a 504 Gateway Timeout
-response, and count as a failure for the purposes of [effective success
+Requests which reach the timeout will be canceled, return a [504 Gateway
+Timeout] response, and count as a failure for the purposes of [effective success
 rate](../configuring-retries/#monitoring-retries).  Since the request was
 canceled before any actual response was received, a timeout will not count
 towards the actual request volume at all.  This means that effective request
@@ -40,3 +101,11 @@ Furthermore, if a response is received just as the timeout is exceeded, it is
 possible for the request to be counted as an actual success but an effective
 failure.  This can result in effective success rate being lower than actual
 success rate.
+
+[HTTPRoute]: ../../features/httproute/
+[ServiceProfile]: ../../features/service-profiles/
+[504 Gateway Timeout]:
+    https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504
+[GEP-1742]: https://gateway-api.sigs.k8s.io/geps/gep-1742/
+[Gateway API duration format]:
+    https://gateway-api.sigs.k8s.io/geps/gep-2257/#gateway-api-duration-format