diff --git a/linkerd.io/content/2-edge/features/httproute.md b/linkerd.io/content/2-edge/features/httproute.md index 0b2bccb3a5..36f7c74505 100644 --- a/linkerd.io/content/2-edge/features/httproute.md +++ b/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: - +- [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 diff --git a/linkerd.io/content/2-edge/reference/httproute.md b/linkerd.io/content/2-edge/reference/httproute.md index 7b23460555..02a49a24cd 100644 --- a/linkerd.io/content/2-edge/reference/httproute.md +++ b/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 diff --git a/linkerd.io/content/2-edge/tasks/configuring-timeouts.md b/linkerd.io/content/2-edge/tasks/configuring-timeouts.md index 34dc55c17d..c0e0d7aa2b 100644 --- a/linkerd.io/content/2-edge/tasks/configuring-timeouts.md +++ b/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