diff --git a/linkerd.io/content/2-edge/features/gateway-api.md b/linkerd.io/content/2-edge/features/gateway-api.md new file mode 100644 index 0000000000..014d58fad8 --- /dev/null +++ b/linkerd.io/content/2-edge/features/gateway-api.md @@ -0,0 +1,100 @@ +--- +title: Gateway API support +description: Linkerd uses the Gateway API resource types for much configuration. +--- + +The Gateway API is a set of CRDs in the `gateway.networking.k8s.io` API group +which describe types of traffic in a way that is independent of a specific mesh +or ingress implementation. Recent versions of Linkerd fully support the +[Kubernetes Gateway API](https://gateway-api.sigs.k8s.io/) as a core +configuration mechanism, and many Linkerd features, including [authorization +policies][auth-policy], [dynamic traffic routing][dyn-routing], and [request +timeouts][timeouts], rely on resource types from the Gateway API for +configuration. + +The two primary Gateway API types used to configure Linkerd are: + +- [HTTPRoute], which parameterizes HTTP requests +- [GRPCRoute], which parameterizes gRPC requests + +Both of these types are used in a variety of ways when configuring Linkerd. + +## Managing the Gateway API + +One complication with using the Gateway API in practice is that many different +packages, not just Linkerd, may provide the Gateway API on your cluster, but +only some Gateway API *versions* are compatible with Linkerd. + +In practice, there are two basic approaches to managing the Gateway API with +Linkerd. You can let Linkerd manage the Gateway API resources, or you can let a +different tool manage them. + +### Option 1: Linkerd manages the Gateway API + +This is the default behavior for Linkerd, which will create, update, and delete +Gateway API resources as required. In this approach, any other tools on your +system that use Gateway API resources will be need to be compatible with the +version of the Gateway API that Linkerd installs: + +| Linkerd versions | Gateway API version installed | HTTPRoute version | gRPC version | +| ---------------- | ----------------------------- | ----------------- | ------------ | +| 2.15 - 2.17 | 0.7 | v1beta1 | v1alpha2 | + +### Option 2: A different tool manages the Gateway API + +Alternatively, you may prefer to have something other than Linkerd manage the +Gateway API resources on your cluster. To do this, you will need to instruct +Linkerd *not* to install, update, or delete the Gateway API resources, by +passing pass the `--set enableHttpRoutes=false` flag during the `linkerd install +--crds` step, or setting the `enableHttpRoutes=false` Helm value when installing +the `linkerd-crds` Helm chart. + +You will also need to ensure that version of the Gateway API installed is +compatible with Linkerd: + +| Linkerd versions | Compatible Gateway API versions | Recommended Gateway API version | +| ---------------- | ------------------------------- | ------------------------------- | +| 2.15 - 2.17 | 0.7, 0.7.1, 1.1.1-experimental | 1.1.1-experimental | + +If possible, you should install the *recommended* Gateway API version in the +table above. (Note that the use of *experimental* Gateway API versions is +sometimes necessary to allow for full functionality; despite the name, these +versions are production capable.) + +{{< warning >}} +Running Linkerd with an incompatible version of the Gateway API +on the cluster can lead to hard-to-debug issues with your Linkerd installation. +{{< /warning >}} + +## Precursors to Gateway API-based configuration + +Prior to the complete support of the Gateway API introduced in Linkerd 2.14, +Linkerd provided two earlier variants of configuration: + +- A Linkerd-specific `HTTPRoute` CRD provided by Linkerd in the + `policy.linkerd.io` API group +- [ServiceProfiles], which allowed for configuration of per-route metrics, + retries, and timeouts prior to the introduction of the Gateway API types. + +Both of these earlier configuration mechanisms continue to be supported; +however, newer feature development is focused on the standard Gateway API +types. + +## Learn More + +To get started with the Gateway API types, you can: + +- [Configure fault injection](../../tasks/fault-injection/) +- [Configure timeouts][timeouts] +- [Configure dynamic request routing][dyn-routing] +- [Configure per-route authorization policy][auth-policy] + +[HTTPRoute]: ../../reference/httproute/ +[GRPCRoute]: ../../reference/grpcroute/ +[Gateway API]: https://gateway-api.sigs.k8s.io/ +[Service]: https://kubernetes.io/docs/concepts/services-networking/service/ +[Server]: ../../reference/authorization-policy/#server +[auth-policy]: ../../tasks/configuring-per-route-policy/ +[dyn-routing]:../../tasks/configuring-dynamic-request-routing/ +[timeouts]: ../../features/retries-and-timeouts/ +[ServiceProfiles]: ../../features/service-profiles/ diff --git a/linkerd.io/content/2-edge/features/httproute.md b/linkerd.io/content/2-edge/features/httproute.md deleted file mode 100644 index 199b6f7ea6..0000000000 --- a/linkerd.io/content/2-edge/features/httproute.md +++ /dev/null @@ -1,81 +0,0 @@ ---- -title: HTTPRoutes -description: Linkerd can use the HTTPRoute resource to configure per-route policies. ---- - -To configure routing behavior and policy for HTTP traffic, Linkerd supports the -[HTTPRoute resource], defined by the Kubernetes [Gateway API]. - -{{< note >}} -Two versions of the HTTPRoute resource may be used with Linkerd: - -- The upstream version provided by the Gateway API, with the - `gateway.networking.k8s.io` API group -- A Linkerd-specific CRD provided by Linkerd, with the `policy.linkerd.io` API - group - -The two HTTPRoute resource definitions are similar, but the Linkerd version -implements experimental features not yet available with the upstream Gateway API -resource definition. See [the HTTPRoute reference -documentation](../../reference/httproute/#linkerd-and-gateway-api-httproutes) -for details. -{{< /note >}} - -If the Gateway API CRDs already exist in your cluster, then Linkerd must be -installed with the `--set enableHttpRoutes=false` flag during the -`linkerd install --crds` step or with the `enableHttpRoutes=false` Helm value -when installing the `linkerd-crds` Helm chart. This avoid conflicts by -instructing Linkerd to not install the Gateway API CRDs and instead rely on the -Gateway CRDs which already exist. - -An HTTPRoute is a Kubernetes resource which attaches to a parent resource, such -as a [Service]. The HTTPRoute defines a set of rules which match HTTP requests -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: - -- HTTPRoutes with a [Service] as their parent resource configure policies for - _outbound_ proxies in pods which are clients of that [Service]. Outbound - policy includes [dynamic request routing][dyn-routing], adding request - headers, modifying a request's path, and reliability features such as - [timeouts]. -- HTTPRoutes with a [Server] as their parent resource configure policy for - _inbound_ proxies in pods which recieve traffic to that [Server]. Inbound - HTTPRoutes are used to configure fine-grained [per-route authorization and - authentication policies][auth-policy]. - -{{< warning >}} -**Outbound HTTPRoutes and [ServiceProfiles](../service-profiles/) provide -overlapping configuration.** For backwards-compatibility reasons, a -ServiceProfile will take precedence over HTTPRoutes which configure the same -Service. If a ServiceProfile is defined for the parent Service of an HTTPRoute, -proxies will use the ServiceProfile configuration, rather than the HTTPRoute -configuration, as long as the ServiceProfile -exists. -{{< /warning >}} - -## Learn More - -To get started with HTTPRoutes, you can: - -- [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. -- See the [reference documentation](../../reference/httproute/) for a complete - description of the HTTPRoute resource. - -[HTTPRoute resource]: https://gateway-api.sigs.k8s.io/api-types/httproute/ -[Gateway API]: https://gateway-api.sigs.k8s.io/ -[Service]: https://kubernetes.io/docs/concepts/services-networking/service/ -[Server]: ../../reference/authorization-policy/#server -[auth-policy]: ../../tasks/configuring-per-route-policy/ -[dyn-routing]:../../tasks/configuring-dynamic-request-routing/ -[timeouts]: ../../tasks/configuring-timeouts/#using-httproutes diff --git a/linkerd.io/content/2-edge/features/retries-and-timeouts.md b/linkerd.io/content/2-edge/features/retries-and-timeouts.md index c0c62260ed..e53a7eb18b 100644 --- a/linkerd.io/content/2-edge/features/retries-and-timeouts.md +++ b/linkerd.io/content/2-edge/features/retries-and-timeouts.md @@ -1,27 +1,100 @@ --- title: Retries and Timeouts -description: Linkerd can perform service-specific retries and timeouts. +description: Linkerd can retry and timeout HTTP and gRPC requests. weight: 3 --- -Timeouts and automatic retries are two of the most powerful and useful -mechanisms a service mesh has for gracefully handling partial or transient -application failures. +Timeouts and automatic retries are two of the most powerful mechanisms a service +mesh has for gracefully handling partial or transient application failures. -Timeouts and retries can be configured using [HTTPRoute], GRPCRoute, or Service -resources. Retries and timeouts are always performed on the *outbound* (client) -side. +* **Timeouts** allow Linkerd to cancel a request that is exceeding a time + limit. +* **Retries** allow Linkerd to automatically retry failed requests, potentially + sending it to a different endpoint. + +Timeouts and retries are configured with a set of annotations, e.g +`retry.linkerd.io/http` and `timeout.linkerd.io/request`. These annotations are +placed on [HTTPRoute] or [GRPCRoute] resources to configure behavior on HTTP or +gRPC requests that match those resources. Alternatively, they can be placed on +`Service` resources configure retries and timeouts for all traffic to that +service. + +As of Linkerd 2.16, timeouts and retries *compose*: requests that timeout are +eligible for being retried. + +{{< note >}} +Note that retries and timeouts are performed on the *outbound* (client) side. +This means that regardless of where the annotations are placed, the source of +the traffic must be meshed. +{{< /note >}} {{< note >}} -If working with headless services, outbound policy cannot be retrieved. Linkerd -reads service discovery information based off the target IP address, and if that -happens to be a pod IP address then it cannot tell which service the pod belongs -to. +Retries and timeouts do not work with headless services. This is because +Linkerd reads service discovery information based off the target IP address, and +if that happens to be a pod IP address then it cannot tell which service the pod +belongs to. {{< /note >}} -These can be setup by following the guides: +{{< warning >}} +Prior to Linkerd 2.16, retries and timeouts were configured with +[ServiceProfile](../../reference/service-profiles/)s. While service profiles are +still supported, retries configured with HTTPRoute or GPRCRoute are +**incompatible with ServiceProfiles**. If a ServiceProfile is defined for a +Service, proxies will use the ServiceProfile retry configuration and ignore any +retry annotations. +{{< /warning >}} + +## Using retries safely + +Retries are an opt-in behavior that require some thought and planning. Misuse +can be dangerous. First, automatically retrying a request that changes system +state each time it is called can be disastrous. Thus, retries should only be +used on _idempotent_ methods, i.e. methods that have the same effect even if +called multiple times. + +Second, retries by definition will increase the load on your system. A set of +services that have requests being constantly retried could potentially get taken +down by the retries instead of being allowed time to recover. + +The exact configuration of retry behavior to improve overall reliability +without significantly increasing risk will require some care on the part of the +user. + +## Per-request policies + +In addition to the annotation approach outlined above, retries and timeouts +can be set on a per-request basis by setting specific HTTP headers. + +In order to enable this per-request policy, Linkerd must be installed with the +`--set policyController.additionalArgs="--allow-l5d-request-headers"` flag or +the corresponding Helm value. + +{{< warning >}} +Per-request policies should **not** be enabled if your application accepts +unfiltered requests from untrusted sources. For example, if you mesh an ingress +controller which takes unfiltered Internet traffic (and you do not use +`skip-inbound-ports` to instruct Linkerd to skip handling inbound traffic to the +pod), untrusted clients will be able to specify Linkerd retry and timeout policy +on their requests. +{{< /warning >}} + +Once per-request policy is enabled, you can set timeout and retry policy on +individual requests by setting these headers: + +* `l5d-retry-http`: Overrides the `retry.linkerd.io/http` annotation +* `l5d-retry-grpc`: Overrides the `retry.linkerd.io/grpc` annotation +* `l5d-retry-limit`: Overrides the `retry.linkerd.io/limit` annotation +* `l5d-retry-timeout`: Overrides the `retry.linkerd.io/timeout` annotation +* `l5d-timeout`: Overrides the `timeout.linkerd.io/request` annotation +* `l5d-response-timeout`: Overrides the `timeout.linkerd.io/response` annotation + +## Further reading -- [Configuring Retries](../../tasks/configuring-retries/) -- [Configuring Timeouts](../../tasks/configuring-timeouts/) +* [Retries reference](../../reference/retries/) +* [Timeout reference](../../reference/timeouts/) +* The [Debugging HTTP applications with per-route + metrics](../../tasks/books/) contains examples of retries and timeout + annotations. -[HTTPRoute]: ../httproute/ +[HTTPRoute]: ../../reference/httproute/ +[GRPCRoute]: ../../reference/grpcroute/ diff --git a/linkerd.io/content/2-edge/features/server-policy.md b/linkerd.io/content/2-edge/features/server-policy.md index 757d7e5603..12cae0e9f7 100644 --- a/linkerd.io/content/2-edge/features/server-policy.md +++ b/linkerd.io/content/2-edge/features/server-policy.md @@ -70,11 +70,12 @@ Linkerd uses a set of CRDs. In contrast to default policy annotations, these policy CRDs can be changed dynamically and policy behavior will be updated on the fly. -Two policy CRDs represent "targets" for policy: subsets of traffic over which +Three policy CRDs represent "targets" for policy: subsets of traffic over which policy can be applied. - [`Server`]: all traffic to a port, for a set of pods in a namespace -- [`HTTPRoute`]: a subset of HTTP requests for a [`Server`] +- [`HTTPRoute`]: a subset of HTTP requests for a `Server` +- [`GRPCRoute`]: a subset of gRPC requests for a `Server` Two policy CRDs represent authentication rules that must be satisfied as part of a policy rule: @@ -90,11 +91,11 @@ authentication rules to targets. unless an authentication rule is met - `ServerAuthorization`: an earlier form of policy that restricts access to - [`Server`]s only (i.e. not [`HTTPRoute`]s) + `Server`s only (i.e. not `HTTPRoute`s or `GRPCRoute`s) The general pattern for Linkerd's dynamic, fine-grained policy is to define the traffic target that must be protected (via a combination of `Server` and -[`HTTPRoute`] CRs); define the types of authentication that are required before +`HTTPRoute` CRs); define the types of authentication that are required before access to that traffic is permitted (via `MeshTLSAuthentication` and `NetworkAuthentication`); and then define the policy that maps authentication to target (via an `AuthorizationPolicy`). @@ -105,7 +106,7 @@ details on how these resources work. ## ServerAuthorization vs AuthorizationPolicy Linkerd 2.12 introduced `AuthorizationPolicy` as a more flexible alternative to -`ServerAuthorization` that can target [`HTTPRoute`]s as well as `Server`s. Use of +`ServerAuthorization` that can target `HTTPRoute`s as well as `Server`s. Use of `AuthorizationPolicy` is preferred, and `ServerAuthorization` will be deprecated in future releases. @@ -116,11 +117,11 @@ from Kubernetes, meaning that the pod would not be able to start. Thus, any default-deny setup must, in practice, still authorize these probes. In order to simplify default-deny setups, Linkerd automatically authorizes -probes to pods. These default authorizations apply only when no [`Server`] is -configured for a port, or when a [`Server`] is configured but no [`HTTPRoute`]s are -configured for that [`Server`]. If any [`HTTPRoute`] matches the `Server`, these -automatic authorizations are not created and you must explicitly create them for -health and readiness probes. +probes to pods. These default authorizations apply only when no `Server` is +configured for a port, or when a `Server` is configured but no `HTTPRoute`s or +`GRPCRoute` are configured for that `Server`. If any `HTTPRoute` or `GRPCRoute` +matches the `Server`, these automatic authorizations are not created and you +must explicitly create them for health and readiness probes. ## Policy rejections @@ -133,7 +134,7 @@ result in an abrupt termination of those connections. ## Audit mode -A [`Server`]'s default policy is defined in its `accessPolicy` field, which +A `Server`'s default policy is defined in its `accessPolicy` field, which defaults to `deny`. That means that, by default, traffic that doesn't conform to the rules associated to that Server is denied (the same applies to `Servers` that don't have associated rules yet). This can inadvertently prevent traffic if @@ -166,5 +167,6 @@ be allowed but it would be logged and surfaced in metrics as detailed above. - [Authorization policy reference](../../reference/authorization-policy/) - [Guide to configuring per-route policy](../../tasks/configuring-per-route-policy/) -[`HTTPRoute`]: ../httproute/ +[`HTTPRoute`]: ../../reference/httproute/ +[`GRPCRoute`]: ../../reference/grpcroute/ [`Server`]: ../../reference/authorization-policy/#server diff --git a/linkerd.io/content/2-edge/features/service-profiles.md b/linkerd.io/content/2-edge/features/service-profiles.md index adc9bac675..6b84f5c149 100644 --- a/linkerd.io/content/2-edge/features/service-profiles.md +++ b/linkerd.io/content/2-edge/features/service-profiles.md @@ -4,11 +4,12 @@ description: Linkerd's service profiles enable per-route metrics as well as retr and timeouts. --- -{{< note >}} -[HTTPRoutes](../httproute/) are the recommended method for getting per-route -metrics, specifying timeouts, and specifying retries. Service profiles continue -to be supported for backwards compatibility. -{{< /note >}} +{{< warning >}} +As of Linkerd 2.16, ServiceProfiles have been fully supplanted by [Gateway API +types](../gateway-api/), including for getting per-route metrics, specifying +timeouts, and specifying retries. Service profiles continue to be supported for +backwards compatibility, but will not receive further feature development. +{{< /warning >}} A service profile is a custom Kubernetes resource ([CRD][crd]) that can provide Linkerd additional information about a service. In particular, it allows you to diff --git a/linkerd.io/content/2-edge/reference/grpcroute.md b/linkerd.io/content/2-edge/reference/grpcroute.md new file mode 100644 index 0000000000..e049d3518b --- /dev/null +++ b/linkerd.io/content/2-edge/reference/grpcroute.md @@ -0,0 +1,85 @@ +--- +title: GRPCRoute +description: Reference guide to GRPCRoute resources. +--- + +A GRPCRoute is a Kubernetes resource which attaches to a "parent" resource, +such as a [Service], and defines a set of rules which match gRPC requests to +that resource. These rules can be based on parameters such as path, method, +headers, or other aspects of the gRPC request. + +GRPCRoutes are used to configure various aspects of Linkerd's behavior, and form +part of [Linkerd's support for the Gateway API](../../features/gateway-api/). + +{{< note >}} +The GRPCRoute resource is part of the Gateway API and is not Linkerd-specific. +The canonical reference doc is the [Gateway API GRPCRoute +documentation](https://gateway-api.sigs.k8s.io/api-types/grpcroute/). This page +is intended as a *supplement* to that doc, and will detail how this type is +used by Linkerd specifically. +{{< /note >}} + +## Inbound vs outbound GRPCRoutes + +GRPCRoutes usage in Linkerd falls into two categories: configuration of +*inbound* behavior and configuration of *outbound* behavior. + +**Inbound behavior.** GRPCRoutes with a [Server] as their parent resource +configure policy for _inbound_ traffic to pods which receive traffic to that +[Server]. Inbound GRPCRoutes are used to configure fine-grained [per-route +authorization and authentication policies][auth-policy]. + +**Outbound behavior.** GRPCRoutes with a [Service] as their parent resource +configure policies for _outbound_ proxies in pods which are clients of that +[Service]. Outbound policy includes [dynamic request routing][dyn-routing], +adding request headers, modifying a request's path, and reliability features +such as [timeouts]. + +{{< warning >}} +**Outbound GRPCRoutes and [ServiceProfiles](../service-profiles/) provide +overlapping configuration.** For backwards-compatibility reasons, a +ServiceProfile will take precedence over GRPCRoutes which configure the same +Service. If a ServiceProfile is defined for the parent Service of an GRPCRoute, +proxies will use the ServiceProfile configuration, rather than the GRPCRoute +configuration, as long as the ServiceProfile +exists. +{{< /warning >}} + +## Usage in practice + +See important notes in the [Gateway API] documentation about using these types +in practice, including ownership of types and compatible versions. + +## GRPCRoute Examples + +This example demonstrates how to split traffic between two backends. A portion +of requests is directed to the `smiley2` backend Service, while the rest go to +the `smiley` backend Service. + +```yaml +apiVersion: gateway.networking.k8s.io/v1alpha2 +kind: GRPCRoute +metadata: + name: smiley-a-b + namespace: faces +spec: + parentRefs: + - name: smiley + kind: Service + group: core + port: 50051 + rules: + - backendRefs: + - name: smiley + port: 50051 + weight: 40 + - name: smiley2 + port: 80 + weight: 50051 +``` + +[ServiceProfile]: ../../features/service-profiles/ +[Gateway API]: https://gateway-api.sigs.k8s.io/ +[ns-boundaries]: https://gateway-api.sigs.k8s.io/geps/gep-1426/#namespace-boundaries +[Server]: ../authorization-policy/#server +[Service]: https://kubernetes.io/docs/concepts/services-networking/service/ diff --git a/linkerd.io/content/2-edge/reference/httproute.md b/linkerd.io/content/2-edge/reference/httproute.md index b94f709d58..11c35b91e7 100644 --- a/linkerd.io/content/2-edge/reference/httproute.md +++ b/linkerd.io/content/2-edge/reference/httproute.md @@ -3,35 +3,59 @@ title: HTTPRoute description: Reference guide to HTTPRoute resources. --- - - - - -## Linkerd and Gateway API HTTPRoutes - -The HTTPRoute resource was originally specified by the Kubernetes [Gateway API] -project. Linkerd currently supports two versions of the HTTPRoute resource: the -upstream version from the Gateway API, with the -`gateway.networking.kubernetes.io` API group, and a Linkerd-specific version, -with the `policy.linkerd.io` API group. While these two resource definitions are -largely the same, the `policy.linkerd.io` HTTPRoute resource is an experimental -version that contains features not yet stabilized in the upstream -`gateway.networking.k8s.io` HTTPRoute resource, such as -[timeouts](#httproutetimeouts). Both the Linkerd and Gateway API resource -definitions coexist within the same cluster, and both can be used to configure -policies for use with Linkerd. - -If the Gateway API CRDs already exist in your cluster, then Linkerd must be -installed with the `--set enableHttpRoutes=false` flag during the -`linkerd install --crds` step or with the `enableHttpRoutes=false` Helm value -when installing the `linkerd-crds` Helm chart. This avoid conflicts by -instructing Linkerd to not install the Gateway API CRDs and instead rely on the -Gateway CRDs which already exist. - -This documentation describes the `policy.linkerd.io` HTTPRoute resource. For a -similar description of the upstream Gateway API HTTPRoute resource, refer to the -Gateway API's [HTTPRoute -specification](https://gateway-api.sigs.k8s.io/references/spec/#gateway.networking.k8s.io/v1beta1.HTTPRoute). +An HTTPRoute is a Kubernetes resource which attaches to a "parent" resource, +such as a [Service], and defines a set of rules which match HTTP requests to +that resource. These rules can be based on parameters such as path, method, +headers, or other aspects of the HTTP request. + +HTTPRoutes are used to configure various aspects of Linkerd's behavior, and form +part of [Linkerd's support for the Gateway API](../../features/gateway-api/). + +{{< note >}} +The HTTPRoute resource is part of the Gateway API and is not Linkerd-specific. +The canonical reference doc is the [Gateway API HTTPRoute +documentation](https://gateway-api.sigs.k8s.io/api-types/httproute/). This page +is intended as a *supplement* to that doc, and will detail how this type is +used by Linkerd specifically. +{{< /note >}} + +## Inbound vs outbound HTTPRoutes + +HTTPRoutes usage in Linkerd falls into two categories: configuration of +*inbound* behavior and configuration of *outbound* behavior. + +**Inbound behavior.** HTTPRoutes with a [Server] as their parent resource +configure policy for _inbound_ traffic to pods which receive traffic to that +[Server]. Inbound HTTPRoutes are used to configure fine-grained [per-route +authorization and authentication policies][auth-policy]. + +**Outbound behavior.** HTTPRoutes with a [Service] as their parent resource +configure policies for _outbound_ proxies in pods which are clients of that +[Service]. Outbound policy includes [dynamic request routing][dyn-routing], +adding request headers, modifying a request's path, and reliability features +such as [timeouts]. + +{{< warning >}} +**Outbound HTTPRoutes and [ServiceProfiles](../service-profiles/) provide +overlapping configuration.** For backwards-compatibility reasons, a +ServiceProfile will take precedence over HTTPRoutes which configure the same +Service. If a ServiceProfile is defined for the parent Service of an HTTPRoute, +proxies will use the ServiceProfile configuration, rather than the HTTPRoute +configuration, as long as the ServiceProfile +exists. +{{< /warning >}} + +## Usage in practice + +See important notes in the [Gateway API] documentation about using these types +in practice, including ownership of types and compatible versions. + +## The `policy.linkerd.io` group + +In earlier Linkerd versions, Linkerd provided a variant of the HTTPRoute +resource in the `policy.linkerd.io` group. These versions are still supported +but are not actively maintained; users are encouraged to switch to the canonical +`gateway.networking.kubernetes.io` resources. ## HTTPRoute Spec @@ -58,13 +82,6 @@ depending on path, headers, query params, and/or verb. Requests can then be rerouted to different backend services. This can be used to perform [dynamic request routing](../../tasks/configuring-dynamic-request-routing/). -{{< warning >}} **Outbound HTTPRoutes and [ServiceProfile]s provide overlapping -configuration.** For backwards-compatibility reasons, a ServiceProfile will -take precedence over HTTPRoutes which configure the same Service. If a -ServiceProfile is defined for the parent Service of an HTTPRoute, proxies will -use the ServiceProfile configuration, rather than the HTTPRoute configuration, -as long as the ServiceProfile exists. {{< /warning >}} - ParentReferences are namespaced, and may reference either a parent in the same namespace as the HTTPRoute, or one in a different namespace. As described in [GEP-1426][ns-boundaries], a HTTPRoute with a `parentRef` that references a @@ -317,3 +334,4 @@ spec: [Gateway API]: https://gateway-api.sigs.k8s.io/ [ns-boundaries]: https://gateway-api.sigs.k8s.io/geps/gep-1426/#namespace-boundaries [Server]: ../authorization-policy/#server +[Service]: https://kubernetes.io/docs/concepts/services-networking/service/ diff --git a/linkerd.io/content/2-edge/reference/proxy-metrics.md b/linkerd.io/content/2-edge/reference/proxy-metrics.md index 743aebf3c2..feb6de3d24 100644 --- a/linkerd.io/content/2-edge/reference/proxy-metrics.md +++ b/linkerd.io/content/2-edge/reference/proxy-metrics.md @@ -276,4 +276,4 @@ following labels: [prom-format]: https://prometheus.io/docs/instrumenting/exposition_formats/#format-version-0.0.4 [pod-template-hash]: https://kubernetes.io/docs/concepts/workloads/controllers/deployment/#pod-template-hash-label [ttfb]: https://en.wikipedia.org/wiki/Time_to_first_byte -[HTTPRoute]: ../../features/httproute/ +[HTTPRoute]: ../httproute/ diff --git a/linkerd.io/content/2-edge/reference/service-profiles.md b/linkerd.io/content/2-edge/reference/service-profiles.md index ac4af46148..362a53ba79 100644 --- a/linkerd.io/content/2-edge/reference/service-profiles.md +++ b/linkerd.io/content/2-edge/reference/service-profiles.md @@ -3,6 +3,14 @@ title: Service Profiles description: Details on the specification and what is possible with service profiles. --- +{{< warning >}} +As of Linkerd 2.16, ServiceProfiles have been fully supplanted by [Gateway API +types](../../features/gateway-api/), including for getting per-route metrics, +specifying timeouts, and specifying retries. Service profiles continue to be +supported for backwards compatibility, but will not receive further feature +development. +{{< /warning >}} + [Service profiles](../../features/service-profiles/) provide Linkerd additional information about a service. This is a reference for everything that can be done with service profiles. diff --git a/linkerd.io/content/2-edge/tasks/configuring-dynamic-request-routing.md b/linkerd.io/content/2-edge/tasks/configuring-dynamic-request-routing.md index 4e38c7fe6f..23c1c4e802 100644 --- a/linkerd.io/content/2-edge/tasks/configuring-dynamic-request-routing.md +++ b/linkerd.io/content/2-edge/tasks/configuring-dynamic-request-routing.md @@ -1,22 +1,22 @@ --- title: Configuring Dynamic Request Routing -description: Configuring HTTPRoute resources to perform dynamic request routing. +description: Dynamically route traffic based on parts of the HTTP call. --- ## Prerequisites -To use this guide, you'll need to have Linkerd installed on your cluster. Follow -the [Installing Linkerd Guide](../install/) if you haven't already done this -(make sure you have at least linkerd stable-2.13.0 or edge-23.3.2). +To use this guide, you'll need to have Linkerd installed on your cluster and the +[Helm](https://helm.sh/docs/intro/quickstart/) CLI installed. -You also need to have the [Helm](https://helm.sh/docs/intro/quickstart/) CLI -installed. +## Dynamic request routing -## HTTPRoute for Dynamic Request Routing - -With dynamic request routing, you can route HTTP traffic based on the contents +With dynamic request routing, you can route HTTP traffic based on the content of request headers. This can be useful for performing things like A/B testing -and many other strategies for traffic management. +and other strategies for traffic management. + +The core configuration mechanism are the [Gateway API] types, [HTTPRoute] and +[GRPCRoute]. In this example we'll look at the common use case using the +HTTPRoute type. In this tutorial, we'll make use of the [podinfo](https://github.com/stefanprodan/podinfo) project to showcase dynamic @@ -75,7 +75,7 @@ PODINFO_UI_MESSAGE=A backend ## Introducing HTTPRoute -Let's apply the following [`HTTPRoute`] resource to enable header-based routing: +Let's apply the following `HTTPRoute` resource to enable header-based routing: ```yaml cat <}} -Two versions of the HTTPRoute resource may be used with Linkerd: - -- The upstream version provided by the Gateway API, with the - `gateway.networking.k8s.io` API group -- A Linkerd-specific CRD provided by Linkerd, with the `policy.linkerd.io` API - group - -The two HTTPRoute resource definitions are similar, but the Linkerd version -implements experimental features not yet available with the upstream Gateway API -resource definition. See [the HTTPRoute reference -documentation](../../reference/httproute/#linkerd-and-gateway-api-httproutes) -for details. -{{< /note >}} - -In `parentRefs` we specify the resources we want this [`HTTPRoute`] instance to -act on. So here we point to the `backend-a-podinfo` Service on the [`HTTPRoute`]'s +In `parentRefs` we specify the resources we want this `HTTPRoute` instance to +act on. So here we point to the `backend-a-podinfo` Service on the `HTTPRoute`'s namespace (`test`), and also specify the Service port number (not the Service's target port). -{{< warning >}} -**Outbound [`HTTPRoute`](../../features/httproute/)s and -[`ServiceProfile`](../../features/service-profiles/)s provide overlapping -configuration.** For backwards-compatibility reasons, a `ServiceProfile` will -take precedence over `HTTPRoute`s which configure the same Service. If a -`ServiceProfile` is defined for the parent Service of an `HTTPRoute`, -proxies will use the `ServiceProfile` configuration, rather than the -`HTTPRoute` configuration, as long as the `ServiceProfile` exists. -{{< /warning >}} - Next, we give a list of rules that will act on the traffic hitting that Service. The first rule contains two entries: `matches` and `backendRefs`. @@ -150,7 +125,7 @@ In `backendRefs` we specify the final destination for requests matching the current rule, via the Service's `name` and `port`. Here we're specifying we'd like to route to `backend-b-podinfo` all the requests -having the `x-request-id: alterrnative` header. If the header is not present, +having the `x-request-id: alternative` header. If the header is not present, the engine fall backs to the last rule which has no `matches` entries and points to the `backend-a-podinfo` Service. @@ -163,7 +138,7 @@ $ curl -sX POST localhost:9898/echo \ PODINFO_UI_MESSAGE=A backend ``` -But if we add the "`x-request-id: alternative`" header they get routed to +But if we add the `x-request-id: alternative` header, they get routed to `backend-b-podinfo`: ```bash @@ -175,17 +150,17 @@ $ curl -sX POST \ PODINFO_UI_MESSAGE=B backend ``` -### To Keep in Mind +### Implementation notes -Note that you can use any header you like, but for this to work the frontend has -to forward it. "`x-request-id`" is a common header used in microservices, that is -explicitly forwarded by podinfo, and that's why we chose it. +In the example above, we used the `x-request-id` header, which is a common +header that is forwarded by podinfo. However, the same technique will work with +arbitrary headers, as long as the application forwards them. -Also, keep in mind the linkerd proxy handles this on the client side of the -request (the frontend pod in this case) and so that pod needs to be injected, -whereas the destination pods don't require to be injected. But of course the -more workloads you have injected the better, to benefit from things like easy -mTLS setup and all the other advantages that linkerd brings to the table! +Note also that dyanmic request routing is client-side behavior, so while the +traffic source (in this case, the frontend pod) needs to be meshed, strictly +speaking, the destination does not need to be meshed. -[`HTTPRoute`]: ../../features/httproute/ +[HTTPRoute]: ../../reference/httproute/ +[GRPCRoute]: ../../reference/httproute/ +[Gateway API]: ../../features/gateway-api/ [`ServiceProfile`]: ../../features/ServiceProfile/ diff --git a/linkerd.io/content/2-edge/tasks/configuring-retries.md b/linkerd.io/content/2-edge/tasks/configuring-retries.md deleted file mode 100644 index ba3cd3d49b..0000000000 --- a/linkerd.io/content/2-edge/tasks/configuring-retries.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -title: Configuring Retries -description: Configure Linkerd to automatically retry failing requests. ---- - -In order for Linkerd to do automatic retries of failures, there are two -questions that need to be answered: - -- Which requests should be retried? -- How many times should the requests be retried? - -Both of these questions can be answered by adding annotations to the Service, -HTTPRoute, or GRPCRoute resource you're sending requests to. - -The reason why these pieces of configuration are required is because retries can -potentially be dangerous. Automatically retrying a request that changes state -(e.g. a request that submits a financial transaction) could potentially impact -your user's experience negatively. In addition, retries increase the load on -your system. A set of services that have requests being constantly retried -could potentially get taken down by the retries instead of being allowed time -to recover. - -Check out the [retries section](../books/#retries) of the books demo -for a tutorial of how to configure retries. - -{{< warning >}} -Retries configured in this way are **incompatible with ServiceProfiles**. If a -[ServiceProfile](../../features/service-profiles/) is defined for a Service, -proxies will use the ServiceProfile retry configuration and ignore any retry -annotations. -{{< /warning >}} - -## Retries - -For HTTPRoutes that are idempotent, you can add the `retry.linkerd.io/http: 5xx` -annotation which instructs Linkerd to retry any requests which fail with an HTTP -response status in the 500s. - -Note that requests will not be retried if the body exceeds 64KiB. - -## Retry Limits - -You can also add the `retry.linkerd.io/limit` annotation to specify the maximum -number of times a request may be retried. By default, this limit is `1`. - -## gRPC Retries - -Retries can also be configured for gRPC traffic by adding the -`retry.linkerd.io/grpc` annotation to a GRPCRoute or Service resource. The value -of this annotation is a comma seperated list of gRPC status codes that should -be retried. diff --git a/linkerd.io/content/2-edge/tasks/configuring-timeouts.md b/linkerd.io/content/2-edge/tasks/configuring-timeouts.md deleted file mode 100644 index 6ac672a5be..0000000000 --- a/linkerd.io/content/2-edge/tasks/configuring-timeouts.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: Configuring Timeouts -description: Configure Linkerd to automatically fail requests that take too long. ---- - -To limit how long Linkerd will wait before failing an outgoing request 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 by adding annotations to HTTPRoute, GRPCRoute, or -Service resources. - -{{< warning >}} -Timeouts configured in this way are **incompatible with ServiceProfiles**. If a -[ServiceProfile](../../features/service-profiles/) is defined for a Service, -proxies will use the ServiceProfile timeout configuration and ignore any timeout -annotations. -{{< /warning >}} - -## Timeouts - -Check out the [timeouts section](../books/#timeouts) of the books demo -for a tutorial of how to configure timeouts. diff --git a/linkerd.io/content/2-edge/tasks/getting-per-route-metrics.md b/linkerd.io/content/2-edge/tasks/getting-per-route-metrics.md deleted file mode 100644 index 5cb7b2c26e..0000000000 --- a/linkerd.io/content/2-edge/tasks/getting-per-route-metrics.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: Getting Per-Route Metrics -description: Configure per-route metrics for your application. ---- - -To get per-route metrics, you must create [HTTPRoute] resources. If a route has -a `parent_ref` which points to a **Service** resource, Linkerd will generate -outbound per-route traffic metrics for all HTTP traffic that it sends to that -Service. If a route has a `parent_ref` which points to a **Server** resource, -Linkerd will generate inbound per-route traffic metrcs for all HTTP traffic that -it receives on that Server. Note that an [HTTPRoute] can have multiple -`parent_ref`s which means that the same [HTTPRoute] resource can be used to -describe both outbound and inbound routes. - -For a tutorial that shows off per-route metrics, check out the -[books demo](../books/#service-profiles). - -{{< note >}} -Routes configured in service profiles are different from [HTTPRoute] resources. -If a [ServiceProfile](../../features/service-profiles/) is defined for a -Service, proxies will ignore any [HTTPRoute] for that Service. -{{< /note >}} - -[HTTPRoute]: ../../features/httproute/ diff --git a/linkerd.io/content/2-edge/tasks/per-request-policy.md b/linkerd.io/content/2-edge/tasks/per-request-policy.md deleted file mode 100644 index 4dfa701414..0000000000 --- a/linkerd.io/content/2-edge/tasks/per-request-policy.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -title: Per-Request Policy -description: Using HTTP headers to specify per-request policy ---- - -[Retries](../configuring-retries/) and [timeouts](../configuring-timeouts/) can -be configured by annotating Service, HTTPRoute, or GRPCRoute resources. This -will apply the retry or timeout policy to all requests that are sent to that -service/route. - -Additionally, retry and timeout policy can be configured for individual HTTP -requests by adding special HTTP headers to those requests. - -## Enabling Per-Request Policy - -In order to enable per-request policy, Linkerd must be installed with the -`--set policyController.additionalArgs="--allow-l5d-request-headers"` flag or -the corresponding Helm value. Enabling per-request policy is **not** -recommended if your application accepts requests from untrusted sources (e.g. -if it is an ingress) since this allows untrusted clients to specify Linkerd -policy. - -## Per-Request Policy Headers - -Once per-request policy is enabled, the following HTTP headers can be added to -a request to set or override retry and/or timeout policy for that request: - -+ `l5d-retry-http`: Overrides the `retry.linkerd.io/http` annotation -+ `l5d-retry-grpc`: Overrides the `retry.linkerd.io/grpc` annotation -+ `l5d-retry-limit`: Overrides the `retry.linkerd.io/limit` annotation -+ `l5d-retry-timeout`: Overrides the `retry.linkerd.io/timeout` annotation -+ `l5d-timeout`: Overrides the `timeout.linkerd.io/request` annotation -+ `l5d-response-timeout`: Overrides the `timeout.linkerd.io/response` annotation diff --git a/linkerd.io/content/2-edge/tasks/restricting-access.md b/linkerd.io/content/2-edge/tasks/restricting-access.md index 699d726c68..3fbb1a03cb 100644 --- a/linkerd.io/content/2-edge/tasks/restricting-access.md +++ b/linkerd.io/content/2-edge/tasks/restricting-access.md @@ -167,16 +167,18 @@ explicitly create an authorization to allow those probe requests. For more information about adding route-scoped authorizations, see [Configuring Per-Route Policy](../configuring-per-route-policy/). -## Further Considerations - Audit Mode +## Enabling authorization policies in live systems You may have noticed that there was a period of time after we created the `Server` resource but before we created the `ServerAuthorization` where all requests were being rejected. To avoid this situation in live systems, we -recommend that you enable [audit mode](../../features/server-policy/#audit-mode) -in the `Server` resource (via `accessPolicy:audit`) and check the proxy -logs/metrics in the target services to see if traffic would get inadvertently -denied. Afterwards, when you're sure about your policy rules, you can fully -enable them by resetting `accessPolicy` back to `deny`. +recommend that you start with [audit +mode](../../features/server-policy/#audit-mode) enabled on the `Server` +resource. In this mode, traffic that violates the policy will not actually be +denied, and you will be able to check the proxy logs/metrics on the target +services for a complete picture of what would happen when audit mode is +disabled. Once you're sure about your policy rules, you can fully enable them by +removing audit mode to enforce the policies. ## Per-Route Policy diff --git a/linkerd.io/content/2-edge/tasks/setting-up-service-profiles.md b/linkerd.io/content/2-edge/tasks/setting-up-service-profiles.md index 0950e937c9..a77a903f7b 100644 --- a/linkerd.io/content/2-edge/tasks/setting-up-service-profiles.md +++ b/linkerd.io/content/2-edge/tasks/setting-up-service-profiles.md @@ -4,6 +4,14 @@ description: Create a service profile that provides more details for Linkerd to on. --- +{{< warning >}} +As of Linkerd 2.16, ServiceProfiles have been fully supplanted by [Gateway API +types](../../features/gateway-api/), including for getting per-route metrics, +specifying timeouts, and specifying retries. Service profiles continue to be +supported for backwards compatibility, but will not receive further feature +development. +{{< /warning >}} + [Service profiles](../../features/service-profiles/) provide Linkerd additional information about a service and how to handle requests for a service. @@ -11,9 +19,7 @@ When an HTTP (not HTTPS) request is received by a Linkerd proxy, the `destination service` of that request is identified. If a service profile for that destination service exists, then that service profile is used to -to provide [per-route metrics](../getting-per-route-metrics/), -[retries](../configuring-retries/) and -[timeouts](../configuring-timeouts/). +to provide per-route metric, retries, and timeouts. The `destination service` for a request is computed by selecting the value of the first header to exist of, `l5d-dst-override`, @@ -21,10 +27,7 @@ the value of the first header to exist of, `l5d-dst-override`, including the colon, is stripped. That value is mapped to the fully qualified DNS name. When the `destination service` matches the name of a service profile in the namespace of the sender or the -receiver, Linkerd will use that to provide [per-route -metrics](../getting-per-route-metrics/), -[retries](../configuring-retries/) and -[timeouts](../configuring-timeouts/). +receiver, Linkerd will use that for additional features. There are times when you may need to define a service profile for a service which resides in a namespace that you do not control. To diff --git a/linkerd.io/content/2-edge/tasks/traffic-shifting.md b/linkerd.io/content/2-edge/tasks/traffic-shifting.md index 991adcb8a5..0d39b08167 100644 --- a/linkerd.io/content/2-edge/tasks/traffic-shifting.md +++ b/linkerd.io/content/2-edge/tasks/traffic-shifting.md @@ -5,25 +5,25 @@ description: Dynamically split and shift traffic between backends Traffic splitting and shifting are powerful features that enable operators to dynamically shift traffic to different backend Services. This can be used to -implement A/B experiments, red/green deploys, canary rollouts, -[fault injection](../fault-injection/) and more. +implement A/B experiments, red/green deploys, canary rollouts, [fault +injection](../fault-injection/), and more. -Linkerd supports two different ways to configure traffic shifting: you can -use the [Linkerd SMI extension](../linkerd-smi/) and +Traffic splitting is accomplished with [HTTPRoute] and [GRPCRoute] types. + +{{< note >}} +Earlier versions of Linkerd provided a [TrafficSplit](https://github.com/servicemeshinterface/smi-spec/blob/main/apis/traffic-split/v1alpha2/traffic-split.md/) -resources, or you can use [HTTPRoute](../../features/httproute/) resources which -Linkerd natively supports. While certain integrations such as -[Flagger](../flagger/) rely on the SMI and `TrafficSplit` approach, using -`HTTPRoute` is the preferred method going forward. +resource as part of the the [Linkerd SMI extension](../linkerd-smi/) for traffic +splitting. This approach is still supported but will not recieve further feature +development. +{{< /note >}} {{< docs/production-note >}} ## Prerequisites -To use this guide, you'll need a Kubernetes cluster running: - -- Linkerd and Linkerd-Viz. If you haven't installed these yet, follow the - [Installing Linkerd Guide](../install/). +To use this guide, you'll need a Kubernetes cluster running Linkerd and +Linkerd-Viz. ## Set up the demo @@ -245,3 +245,7 @@ NAME MESHED SUCCESS RPS LATENCY_P50 LATENCY_P95 LATENCY_P99 TC v1 1/1 - - - - - - v2 1/1 100.00% 10.0rps 1ms 1ms 2ms 1 ``` + +[HTTPRoute]: ../../reference/httproute/ +[GRPCRoute]: ../../reference/httproute/ +[Gateway API]: ../../features/gateway-api/ diff --git a/linkerd.io/content/2.16/features/gateway-api.md b/linkerd.io/content/2.16/features/gateway-api.md new file mode 100644 index 0000000000..014d58fad8 --- /dev/null +++ b/linkerd.io/content/2.16/features/gateway-api.md @@ -0,0 +1,100 @@ +--- +title: Gateway API support +description: Linkerd uses the Gateway API resource types for much configuration. +--- + +The Gateway API is a set of CRDs in the `gateway.networking.k8s.io` API group +which describe types of traffic in a way that is independent of a specific mesh +or ingress implementation. Recent versions of Linkerd fully support the +[Kubernetes Gateway API](https://gateway-api.sigs.k8s.io/) as a core +configuration mechanism, and many Linkerd features, including [authorization +policies][auth-policy], [dynamic traffic routing][dyn-routing], and [request +timeouts][timeouts], rely on resource types from the Gateway API for +configuration. + +The two primary Gateway API types used to configure Linkerd are: + +- [HTTPRoute], which parameterizes HTTP requests +- [GRPCRoute], which parameterizes gRPC requests + +Both of these types are used in a variety of ways when configuring Linkerd. + +## Managing the Gateway API + +One complication with using the Gateway API in practice is that many different +packages, not just Linkerd, may provide the Gateway API on your cluster, but +only some Gateway API *versions* are compatible with Linkerd. + +In practice, there are two basic approaches to managing the Gateway API with +Linkerd. You can let Linkerd manage the Gateway API resources, or you can let a +different tool manage them. + +### Option 1: Linkerd manages the Gateway API + +This is the default behavior for Linkerd, which will create, update, and delete +Gateway API resources as required. In this approach, any other tools on your +system that use Gateway API resources will be need to be compatible with the +version of the Gateway API that Linkerd installs: + +| Linkerd versions | Gateway API version installed | HTTPRoute version | gRPC version | +| ---------------- | ----------------------------- | ----------------- | ------------ | +| 2.15 - 2.17 | 0.7 | v1beta1 | v1alpha2 | + +### Option 2: A different tool manages the Gateway API + +Alternatively, you may prefer to have something other than Linkerd manage the +Gateway API resources on your cluster. To do this, you will need to instruct +Linkerd *not* to install, update, or delete the Gateway API resources, by +passing pass the `--set enableHttpRoutes=false` flag during the `linkerd install +--crds` step, or setting the `enableHttpRoutes=false` Helm value when installing +the `linkerd-crds` Helm chart. + +You will also need to ensure that version of the Gateway API installed is +compatible with Linkerd: + +| Linkerd versions | Compatible Gateway API versions | Recommended Gateway API version | +| ---------------- | ------------------------------- | ------------------------------- | +| 2.15 - 2.17 | 0.7, 0.7.1, 1.1.1-experimental | 1.1.1-experimental | + +If possible, you should install the *recommended* Gateway API version in the +table above. (Note that the use of *experimental* Gateway API versions is +sometimes necessary to allow for full functionality; despite the name, these +versions are production capable.) + +{{< warning >}} +Running Linkerd with an incompatible version of the Gateway API +on the cluster can lead to hard-to-debug issues with your Linkerd installation. +{{< /warning >}} + +## Precursors to Gateway API-based configuration + +Prior to the complete support of the Gateway API introduced in Linkerd 2.14, +Linkerd provided two earlier variants of configuration: + +- A Linkerd-specific `HTTPRoute` CRD provided by Linkerd in the + `policy.linkerd.io` API group +- [ServiceProfiles], which allowed for configuration of per-route metrics, + retries, and timeouts prior to the introduction of the Gateway API types. + +Both of these earlier configuration mechanisms continue to be supported; +however, newer feature development is focused on the standard Gateway API +types. + +## Learn More + +To get started with the Gateway API types, you can: + +- [Configure fault injection](../../tasks/fault-injection/) +- [Configure timeouts][timeouts] +- [Configure dynamic request routing][dyn-routing] +- [Configure per-route authorization policy][auth-policy] + +[HTTPRoute]: ../../reference/httproute/ +[GRPCRoute]: ../../reference/grpcroute/ +[Gateway API]: https://gateway-api.sigs.k8s.io/ +[Service]: https://kubernetes.io/docs/concepts/services-networking/service/ +[Server]: ../../reference/authorization-policy/#server +[auth-policy]: ../../tasks/configuring-per-route-policy/ +[dyn-routing]:../../tasks/configuring-dynamic-request-routing/ +[timeouts]: ../../features/retries-and-timeouts/ +[ServiceProfiles]: ../../features/service-profiles/ diff --git a/linkerd.io/content/2.16/features/httproute.md b/linkerd.io/content/2.16/features/httproute.md deleted file mode 100644 index 199b6f7ea6..0000000000 --- a/linkerd.io/content/2.16/features/httproute.md +++ /dev/null @@ -1,81 +0,0 @@ ---- -title: HTTPRoutes -description: Linkerd can use the HTTPRoute resource to configure per-route policies. ---- - -To configure routing behavior and policy for HTTP traffic, Linkerd supports the -[HTTPRoute resource], defined by the Kubernetes [Gateway API]. - -{{< note >}} -Two versions of the HTTPRoute resource may be used with Linkerd: - -- The upstream version provided by the Gateway API, with the - `gateway.networking.k8s.io` API group -- A Linkerd-specific CRD provided by Linkerd, with the `policy.linkerd.io` API - group - -The two HTTPRoute resource definitions are similar, but the Linkerd version -implements experimental features not yet available with the upstream Gateway API -resource definition. See [the HTTPRoute reference -documentation](../../reference/httproute/#linkerd-and-gateway-api-httproutes) -for details. -{{< /note >}} - -If the Gateway API CRDs already exist in your cluster, then Linkerd must be -installed with the `--set enableHttpRoutes=false` flag during the -`linkerd install --crds` step or with the `enableHttpRoutes=false` Helm value -when installing the `linkerd-crds` Helm chart. This avoid conflicts by -instructing Linkerd to not install the Gateway API CRDs and instead rely on the -Gateway CRDs which already exist. - -An HTTPRoute is a Kubernetes resource which attaches to a parent resource, such -as a [Service]. The HTTPRoute defines a set of rules which match HTTP requests -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: - -- HTTPRoutes with a [Service] as their parent resource configure policies for - _outbound_ proxies in pods which are clients of that [Service]. Outbound - policy includes [dynamic request routing][dyn-routing], adding request - headers, modifying a request's path, and reliability features such as - [timeouts]. -- HTTPRoutes with a [Server] as their parent resource configure policy for - _inbound_ proxies in pods which recieve traffic to that [Server]. Inbound - HTTPRoutes are used to configure fine-grained [per-route authorization and - authentication policies][auth-policy]. - -{{< warning >}} -**Outbound HTTPRoutes and [ServiceProfiles](../service-profiles/) provide -overlapping configuration.** For backwards-compatibility reasons, a -ServiceProfile will take precedence over HTTPRoutes which configure the same -Service. If a ServiceProfile is defined for the parent Service of an HTTPRoute, -proxies will use the ServiceProfile configuration, rather than the HTTPRoute -configuration, as long as the ServiceProfile -exists. -{{< /warning >}} - -## Learn More - -To get started with HTTPRoutes, you can: - -- [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. -- See the [reference documentation](../../reference/httproute/) for a complete - description of the HTTPRoute resource. - -[HTTPRoute resource]: https://gateway-api.sigs.k8s.io/api-types/httproute/ -[Gateway API]: https://gateway-api.sigs.k8s.io/ -[Service]: https://kubernetes.io/docs/concepts/services-networking/service/ -[Server]: ../../reference/authorization-policy/#server -[auth-policy]: ../../tasks/configuring-per-route-policy/ -[dyn-routing]:../../tasks/configuring-dynamic-request-routing/ -[timeouts]: ../../tasks/configuring-timeouts/#using-httproutes diff --git a/linkerd.io/content/2.16/features/retries-and-timeouts.md b/linkerd.io/content/2.16/features/retries-and-timeouts.md index c0c62260ed..e53a7eb18b 100644 --- a/linkerd.io/content/2.16/features/retries-and-timeouts.md +++ b/linkerd.io/content/2.16/features/retries-and-timeouts.md @@ -1,27 +1,100 @@ --- title: Retries and Timeouts -description: Linkerd can perform service-specific retries and timeouts. +description: Linkerd can retry and timeout HTTP and gRPC requests. weight: 3 --- -Timeouts and automatic retries are two of the most powerful and useful -mechanisms a service mesh has for gracefully handling partial or transient -application failures. +Timeouts and automatic retries are two of the most powerful mechanisms a service +mesh has for gracefully handling partial or transient application failures. -Timeouts and retries can be configured using [HTTPRoute], GRPCRoute, or Service -resources. Retries and timeouts are always performed on the *outbound* (client) -side. +* **Timeouts** allow Linkerd to cancel a request that is exceeding a time + limit. +* **Retries** allow Linkerd to automatically retry failed requests, potentially + sending it to a different endpoint. + +Timeouts and retries are configured with a set of annotations, e.g +`retry.linkerd.io/http` and `timeout.linkerd.io/request`. These annotations are +placed on [HTTPRoute] or [GRPCRoute] resources to configure behavior on HTTP or +gRPC requests that match those resources. Alternatively, they can be placed on +`Service` resources configure retries and timeouts for all traffic to that +service. + +As of Linkerd 2.16, timeouts and retries *compose*: requests that timeout are +eligible for being retried. + +{{< note >}} +Note that retries and timeouts are performed on the *outbound* (client) side. +This means that regardless of where the annotations are placed, the source of +the traffic must be meshed. +{{< /note >}} {{< note >}} -If working with headless services, outbound policy cannot be retrieved. Linkerd -reads service discovery information based off the target IP address, and if that -happens to be a pod IP address then it cannot tell which service the pod belongs -to. +Retries and timeouts do not work with headless services. This is because +Linkerd reads service discovery information based off the target IP address, and +if that happens to be a pod IP address then it cannot tell which service the pod +belongs to. {{< /note >}} -These can be setup by following the guides: +{{< warning >}} +Prior to Linkerd 2.16, retries and timeouts were configured with +[ServiceProfile](../../reference/service-profiles/)s. While service profiles are +still supported, retries configured with HTTPRoute or GPRCRoute are +**incompatible with ServiceProfiles**. If a ServiceProfile is defined for a +Service, proxies will use the ServiceProfile retry configuration and ignore any +retry annotations. +{{< /warning >}} + +## Using retries safely + +Retries are an opt-in behavior that require some thought and planning. Misuse +can be dangerous. First, automatically retrying a request that changes system +state each time it is called can be disastrous. Thus, retries should only be +used on _idempotent_ methods, i.e. methods that have the same effect even if +called multiple times. + +Second, retries by definition will increase the load on your system. A set of +services that have requests being constantly retried could potentially get taken +down by the retries instead of being allowed time to recover. + +The exact configuration of retry behavior to improve overall reliability +without significantly increasing risk will require some care on the part of the +user. + +## Per-request policies + +In addition to the annotation approach outlined above, retries and timeouts +can be set on a per-request basis by setting specific HTTP headers. + +In order to enable this per-request policy, Linkerd must be installed with the +`--set policyController.additionalArgs="--allow-l5d-request-headers"` flag or +the corresponding Helm value. + +{{< warning >}} +Per-request policies should **not** be enabled if your application accepts +unfiltered requests from untrusted sources. For example, if you mesh an ingress +controller which takes unfiltered Internet traffic (and you do not use +`skip-inbound-ports` to instruct Linkerd to skip handling inbound traffic to the +pod), untrusted clients will be able to specify Linkerd retry and timeout policy +on their requests. +{{< /warning >}} + +Once per-request policy is enabled, you can set timeout and retry policy on +individual requests by setting these headers: + +* `l5d-retry-http`: Overrides the `retry.linkerd.io/http` annotation +* `l5d-retry-grpc`: Overrides the `retry.linkerd.io/grpc` annotation +* `l5d-retry-limit`: Overrides the `retry.linkerd.io/limit` annotation +* `l5d-retry-timeout`: Overrides the `retry.linkerd.io/timeout` annotation +* `l5d-timeout`: Overrides the `timeout.linkerd.io/request` annotation +* `l5d-response-timeout`: Overrides the `timeout.linkerd.io/response` annotation + +## Further reading -- [Configuring Retries](../../tasks/configuring-retries/) -- [Configuring Timeouts](../../tasks/configuring-timeouts/) +* [Retries reference](../../reference/retries/) +* [Timeout reference](../../reference/timeouts/) +* The [Debugging HTTP applications with per-route + metrics](../../tasks/books/) contains examples of retries and timeout + annotations. -[HTTPRoute]: ../httproute/ +[HTTPRoute]: ../../reference/httproute/ +[GRPCRoute]: ../../reference/grpcroute/ diff --git a/linkerd.io/content/2.16/features/server-policy.md b/linkerd.io/content/2.16/features/server-policy.md index 757d7e5603..12cae0e9f7 100644 --- a/linkerd.io/content/2.16/features/server-policy.md +++ b/linkerd.io/content/2.16/features/server-policy.md @@ -70,11 +70,12 @@ Linkerd uses a set of CRDs. In contrast to default policy annotations, these policy CRDs can be changed dynamically and policy behavior will be updated on the fly. -Two policy CRDs represent "targets" for policy: subsets of traffic over which +Three policy CRDs represent "targets" for policy: subsets of traffic over which policy can be applied. - [`Server`]: all traffic to a port, for a set of pods in a namespace -- [`HTTPRoute`]: a subset of HTTP requests for a [`Server`] +- [`HTTPRoute`]: a subset of HTTP requests for a `Server` +- [`GRPCRoute`]: a subset of gRPC requests for a `Server` Two policy CRDs represent authentication rules that must be satisfied as part of a policy rule: @@ -90,11 +91,11 @@ authentication rules to targets. unless an authentication rule is met - `ServerAuthorization`: an earlier form of policy that restricts access to - [`Server`]s only (i.e. not [`HTTPRoute`]s) + `Server`s only (i.e. not `HTTPRoute`s or `GRPCRoute`s) The general pattern for Linkerd's dynamic, fine-grained policy is to define the traffic target that must be protected (via a combination of `Server` and -[`HTTPRoute`] CRs); define the types of authentication that are required before +`HTTPRoute` CRs); define the types of authentication that are required before access to that traffic is permitted (via `MeshTLSAuthentication` and `NetworkAuthentication`); and then define the policy that maps authentication to target (via an `AuthorizationPolicy`). @@ -105,7 +106,7 @@ details on how these resources work. ## ServerAuthorization vs AuthorizationPolicy Linkerd 2.12 introduced `AuthorizationPolicy` as a more flexible alternative to -`ServerAuthorization` that can target [`HTTPRoute`]s as well as `Server`s. Use of +`ServerAuthorization` that can target `HTTPRoute`s as well as `Server`s. Use of `AuthorizationPolicy` is preferred, and `ServerAuthorization` will be deprecated in future releases. @@ -116,11 +117,11 @@ from Kubernetes, meaning that the pod would not be able to start. Thus, any default-deny setup must, in practice, still authorize these probes. In order to simplify default-deny setups, Linkerd automatically authorizes -probes to pods. These default authorizations apply only when no [`Server`] is -configured for a port, or when a [`Server`] is configured but no [`HTTPRoute`]s are -configured for that [`Server`]. If any [`HTTPRoute`] matches the `Server`, these -automatic authorizations are not created and you must explicitly create them for -health and readiness probes. +probes to pods. These default authorizations apply only when no `Server` is +configured for a port, or when a `Server` is configured but no `HTTPRoute`s or +`GRPCRoute` are configured for that `Server`. If any `HTTPRoute` or `GRPCRoute` +matches the `Server`, these automatic authorizations are not created and you +must explicitly create them for health and readiness probes. ## Policy rejections @@ -133,7 +134,7 @@ result in an abrupt termination of those connections. ## Audit mode -A [`Server`]'s default policy is defined in its `accessPolicy` field, which +A `Server`'s default policy is defined in its `accessPolicy` field, which defaults to `deny`. That means that, by default, traffic that doesn't conform to the rules associated to that Server is denied (the same applies to `Servers` that don't have associated rules yet). This can inadvertently prevent traffic if @@ -166,5 +167,6 @@ be allowed but it would be logged and surfaced in metrics as detailed above. - [Authorization policy reference](../../reference/authorization-policy/) - [Guide to configuring per-route policy](../../tasks/configuring-per-route-policy/) -[`HTTPRoute`]: ../httproute/ +[`HTTPRoute`]: ../../reference/httproute/ +[`GRPCRoute`]: ../../reference/grpcroute/ [`Server`]: ../../reference/authorization-policy/#server diff --git a/linkerd.io/content/2.16/features/service-profiles.md b/linkerd.io/content/2.16/features/service-profiles.md index adc9bac675..6b84f5c149 100644 --- a/linkerd.io/content/2.16/features/service-profiles.md +++ b/linkerd.io/content/2.16/features/service-profiles.md @@ -4,11 +4,12 @@ description: Linkerd's service profiles enable per-route metrics as well as retr and timeouts. --- -{{< note >}} -[HTTPRoutes](../httproute/) are the recommended method for getting per-route -metrics, specifying timeouts, and specifying retries. Service profiles continue -to be supported for backwards compatibility. -{{< /note >}} +{{< warning >}} +As of Linkerd 2.16, ServiceProfiles have been fully supplanted by [Gateway API +types](../gateway-api/), including for getting per-route metrics, specifying +timeouts, and specifying retries. Service profiles continue to be supported for +backwards compatibility, but will not receive further feature development. +{{< /warning >}} A service profile is a custom Kubernetes resource ([CRD][crd]) that can provide Linkerd additional information about a service. In particular, it allows you to diff --git a/linkerd.io/content/2.16/reference/grpcroute.md b/linkerd.io/content/2.16/reference/grpcroute.md new file mode 100644 index 0000000000..e049d3518b --- /dev/null +++ b/linkerd.io/content/2.16/reference/grpcroute.md @@ -0,0 +1,85 @@ +--- +title: GRPCRoute +description: Reference guide to GRPCRoute resources. +--- + +A GRPCRoute is a Kubernetes resource which attaches to a "parent" resource, +such as a [Service], and defines a set of rules which match gRPC requests to +that resource. These rules can be based on parameters such as path, method, +headers, or other aspects of the gRPC request. + +GRPCRoutes are used to configure various aspects of Linkerd's behavior, and form +part of [Linkerd's support for the Gateway API](../../features/gateway-api/). + +{{< note >}} +The GRPCRoute resource is part of the Gateway API and is not Linkerd-specific. +The canonical reference doc is the [Gateway API GRPCRoute +documentation](https://gateway-api.sigs.k8s.io/api-types/grpcroute/). This page +is intended as a *supplement* to that doc, and will detail how this type is +used by Linkerd specifically. +{{< /note >}} + +## Inbound vs outbound GRPCRoutes + +GRPCRoutes usage in Linkerd falls into two categories: configuration of +*inbound* behavior and configuration of *outbound* behavior. + +**Inbound behavior.** GRPCRoutes with a [Server] as their parent resource +configure policy for _inbound_ traffic to pods which receive traffic to that +[Server]. Inbound GRPCRoutes are used to configure fine-grained [per-route +authorization and authentication policies][auth-policy]. + +**Outbound behavior.** GRPCRoutes with a [Service] as their parent resource +configure policies for _outbound_ proxies in pods which are clients of that +[Service]. Outbound policy includes [dynamic request routing][dyn-routing], +adding request headers, modifying a request's path, and reliability features +such as [timeouts]. + +{{< warning >}} +**Outbound GRPCRoutes and [ServiceProfiles](../service-profiles/) provide +overlapping configuration.** For backwards-compatibility reasons, a +ServiceProfile will take precedence over GRPCRoutes which configure the same +Service. If a ServiceProfile is defined for the parent Service of an GRPCRoute, +proxies will use the ServiceProfile configuration, rather than the GRPCRoute +configuration, as long as the ServiceProfile +exists. +{{< /warning >}} + +## Usage in practice + +See important notes in the [Gateway API] documentation about using these types +in practice, including ownership of types and compatible versions. + +## GRPCRoute Examples + +This example demonstrates how to split traffic between two backends. A portion +of requests is directed to the `smiley2` backend Service, while the rest go to +the `smiley` backend Service. + +```yaml +apiVersion: gateway.networking.k8s.io/v1alpha2 +kind: GRPCRoute +metadata: + name: smiley-a-b + namespace: faces +spec: + parentRefs: + - name: smiley + kind: Service + group: core + port: 50051 + rules: + - backendRefs: + - name: smiley + port: 50051 + weight: 40 + - name: smiley2 + port: 80 + weight: 50051 +``` + +[ServiceProfile]: ../../features/service-profiles/ +[Gateway API]: https://gateway-api.sigs.k8s.io/ +[ns-boundaries]: https://gateway-api.sigs.k8s.io/geps/gep-1426/#namespace-boundaries +[Server]: ../authorization-policy/#server +[Service]: https://kubernetes.io/docs/concepts/services-networking/service/ diff --git a/linkerd.io/content/2.16/reference/httproute.md b/linkerd.io/content/2.16/reference/httproute.md index caacb269f1..11c35b91e7 100644 --- a/linkerd.io/content/2.16/reference/httproute.md +++ b/linkerd.io/content/2.16/reference/httproute.md @@ -3,35 +3,59 @@ title: HTTPRoute description: Reference guide to HTTPRoute resources. --- - - - - -## Linkerd and Gateway API HTTPRoutes - -The HTTPRoute resource was originally specified by the Kubernetes [Gateway API] -project. Linkerd currently supports two versions of the HTTPRoute resource: the -upstream version from the Gateway API, with the -`gateway.networking.kubernetes.io` API group, and a Linkerd-specific version, -with the `policy.linkerd.io` API group. While these two resource definitions are -largely the same, the `policy.linkerd.io` HTTPRoute resource is an experimental -version that contains features not yet stabilized in the upstream -`gateway.networking.k8s.io` HTTPRoute resource, such as -[timeouts](#httproutetimeouts). Both the Linkerd and Gateway API resource -definitions coexist within the same cluster, and both can be used to configure -policies for use with Linkerd. - -If the Gateway API CRDs already exist in your cluster, then Linkerd must be -installed with the `--set enableHttpRoutes=false` flag during the -`linkerd install --crds` step or with the `enableHttpRoutes=false` Helm value -when installing the `linkerd-crds` Helm chart. This avoid conflicts by -instructing Linkerd to not install the Gateway API CRDs and instead rely on the -Gateway CRDs which already exist. - -This documentation describes the `policy.linkerd.io` HTTPRoute resource. For a -similar description of the upstream Gateway API HTTPRoute resource, refer to the -Gateway API's [HTTPRoute -specification](https://gateway-api.sigs.k8s.io/references/spec/#gateway.networking.k8s.io/v1beta1.HTTPRoute). +An HTTPRoute is a Kubernetes resource which attaches to a "parent" resource, +such as a [Service], and defines a set of rules which match HTTP requests to +that resource. These rules can be based on parameters such as path, method, +headers, or other aspects of the HTTP request. + +HTTPRoutes are used to configure various aspects of Linkerd's behavior, and form +part of [Linkerd's support for the Gateway API](../../features/gateway-api/). + +{{< note >}} +The HTTPRoute resource is part of the Gateway API and is not Linkerd-specific. +The canonical reference doc is the [Gateway API HTTPRoute +documentation](https://gateway-api.sigs.k8s.io/api-types/httproute/). This page +is intended as a *supplement* to that doc, and will detail how this type is +used by Linkerd specifically. +{{< /note >}} + +## Inbound vs outbound HTTPRoutes + +HTTPRoutes usage in Linkerd falls into two categories: configuration of +*inbound* behavior and configuration of *outbound* behavior. + +**Inbound behavior.** HTTPRoutes with a [Server] as their parent resource +configure policy for _inbound_ traffic to pods which receive traffic to that +[Server]. Inbound HTTPRoutes are used to configure fine-grained [per-route +authorization and authentication policies][auth-policy]. + +**Outbound behavior.** HTTPRoutes with a [Service] as their parent resource +configure policies for _outbound_ proxies in pods which are clients of that +[Service]. Outbound policy includes [dynamic request routing][dyn-routing], +adding request headers, modifying a request's path, and reliability features +such as [timeouts]. + +{{< warning >}} +**Outbound HTTPRoutes and [ServiceProfiles](../service-profiles/) provide +overlapping configuration.** For backwards-compatibility reasons, a +ServiceProfile will take precedence over HTTPRoutes which configure the same +Service. If a ServiceProfile is defined for the parent Service of an HTTPRoute, +proxies will use the ServiceProfile configuration, rather than the HTTPRoute +configuration, as long as the ServiceProfile +exists. +{{< /warning >}} + +## Usage in practice + +See important notes in the [Gateway API] documentation about using these types +in practice, including ownership of types and compatible versions. + +## The `policy.linkerd.io` group + +In earlier Linkerd versions, Linkerd provided a variant of the HTTPRoute +resource in the `policy.linkerd.io` group. These versions are still supported +but are not actively maintained; users are encouraged to switch to the canonical +`gateway.networking.kubernetes.io` resources. ## HTTPRoute Spec @@ -49,23 +73,15 @@ An HTTPRoute spec may contain the following top level fields: A reference to the parent resource this HTTPRoute is a part of. -HTTPRoutes can be attached to a [Server](../authorization-policy/#server) to -allow defining an [authorization -policy](../authorization-policy/#authorizationpolicy) for specific routes served -on that Server. +HTTPRoutes can be attached to a [Server] to allow defining an [authorization +policy](../authorization-policy/#authorizationpolicy) for specific routes +served on that Server. HTTPRoutes can also be attached to a Service, in order to route requests depending on path, headers, query params, and/or verb. Requests can then be rerouted to different backend services. This can be used to perform [dynamic request routing](../../tasks/configuring-dynamic-request-routing/). -{{< warning >}} **Outbound HTTPRoutes and [ServiceProfile]s provide overlapping -configuration.** For backwards-compatibility reasons, a ServiceProfile will -take precedence over HTTPRoutes which configure the same Service. If a -ServiceProfile is defined for the parent Service of an HTTPRoute, proxies will -use the ServiceProfile configuration, rather than the HTTPRoute configuration, -as long as the ServiceProfile exists. {{< /warning >}} - ParentReferences are namespaced, and may reference either a parent in the same namespace as the HTTPRoute, or one in a different namespace. As described in [GEP-1426][ns-boundaries], a HTTPRoute with a `parentRef` that references a @@ -318,3 +334,4 @@ spec: [Gateway API]: https://gateway-api.sigs.k8s.io/ [ns-boundaries]: https://gateway-api.sigs.k8s.io/geps/gep-1426/#namespace-boundaries [Server]: ../authorization-policy/#server +[Service]: https://kubernetes.io/docs/concepts/services-networking/service/ diff --git a/linkerd.io/content/2.16/reference/proxy-metrics.md b/linkerd.io/content/2.16/reference/proxy-metrics.md index 743aebf3c2..feb6de3d24 100644 --- a/linkerd.io/content/2.16/reference/proxy-metrics.md +++ b/linkerd.io/content/2.16/reference/proxy-metrics.md @@ -276,4 +276,4 @@ following labels: [prom-format]: https://prometheus.io/docs/instrumenting/exposition_formats/#format-version-0.0.4 [pod-template-hash]: https://kubernetes.io/docs/concepts/workloads/controllers/deployment/#pod-template-hash-label [ttfb]: https://en.wikipedia.org/wiki/Time_to_first_byte -[HTTPRoute]: ../../features/httproute/ +[HTTPRoute]: ../httproute/ diff --git a/linkerd.io/content/2.16/reference/service-profiles.md b/linkerd.io/content/2.16/reference/service-profiles.md index ac4af46148..362a53ba79 100644 --- a/linkerd.io/content/2.16/reference/service-profiles.md +++ b/linkerd.io/content/2.16/reference/service-profiles.md @@ -3,6 +3,14 @@ title: Service Profiles description: Details on the specification and what is possible with service profiles. --- +{{< warning >}} +As of Linkerd 2.16, ServiceProfiles have been fully supplanted by [Gateway API +types](../../features/gateway-api/), including for getting per-route metrics, +specifying timeouts, and specifying retries. Service profiles continue to be +supported for backwards compatibility, but will not receive further feature +development. +{{< /warning >}} + [Service profiles](../../features/service-profiles/) provide Linkerd additional information about a service. This is a reference for everything that can be done with service profiles. diff --git a/linkerd.io/content/2.16/tasks/configuring-dynamic-request-routing.md b/linkerd.io/content/2.16/tasks/configuring-dynamic-request-routing.md index 4e38c7fe6f..23c1c4e802 100644 --- a/linkerd.io/content/2.16/tasks/configuring-dynamic-request-routing.md +++ b/linkerd.io/content/2.16/tasks/configuring-dynamic-request-routing.md @@ -1,22 +1,22 @@ --- title: Configuring Dynamic Request Routing -description: Configuring HTTPRoute resources to perform dynamic request routing. +description: Dynamically route traffic based on parts of the HTTP call. --- ## Prerequisites -To use this guide, you'll need to have Linkerd installed on your cluster. Follow -the [Installing Linkerd Guide](../install/) if you haven't already done this -(make sure you have at least linkerd stable-2.13.0 or edge-23.3.2). +To use this guide, you'll need to have Linkerd installed on your cluster and the +[Helm](https://helm.sh/docs/intro/quickstart/) CLI installed. -You also need to have the [Helm](https://helm.sh/docs/intro/quickstart/) CLI -installed. +## Dynamic request routing -## HTTPRoute for Dynamic Request Routing - -With dynamic request routing, you can route HTTP traffic based on the contents +With dynamic request routing, you can route HTTP traffic based on the content of request headers. This can be useful for performing things like A/B testing -and many other strategies for traffic management. +and other strategies for traffic management. + +The core configuration mechanism are the [Gateway API] types, [HTTPRoute] and +[GRPCRoute]. In this example we'll look at the common use case using the +HTTPRoute type. In this tutorial, we'll make use of the [podinfo](https://github.com/stefanprodan/podinfo) project to showcase dynamic @@ -75,7 +75,7 @@ PODINFO_UI_MESSAGE=A backend ## Introducing HTTPRoute -Let's apply the following [`HTTPRoute`] resource to enable header-based routing: +Let's apply the following `HTTPRoute` resource to enable header-based routing: ```yaml cat <}} -Two versions of the HTTPRoute resource may be used with Linkerd: - -- The upstream version provided by the Gateway API, with the - `gateway.networking.k8s.io` API group -- A Linkerd-specific CRD provided by Linkerd, with the `policy.linkerd.io` API - group - -The two HTTPRoute resource definitions are similar, but the Linkerd version -implements experimental features not yet available with the upstream Gateway API -resource definition. See [the HTTPRoute reference -documentation](../../reference/httproute/#linkerd-and-gateway-api-httproutes) -for details. -{{< /note >}} - -In `parentRefs` we specify the resources we want this [`HTTPRoute`] instance to -act on. So here we point to the `backend-a-podinfo` Service on the [`HTTPRoute`]'s +In `parentRefs` we specify the resources we want this `HTTPRoute` instance to +act on. So here we point to the `backend-a-podinfo` Service on the `HTTPRoute`'s namespace (`test`), and also specify the Service port number (not the Service's target port). -{{< warning >}} -**Outbound [`HTTPRoute`](../../features/httproute/)s and -[`ServiceProfile`](../../features/service-profiles/)s provide overlapping -configuration.** For backwards-compatibility reasons, a `ServiceProfile` will -take precedence over `HTTPRoute`s which configure the same Service. If a -`ServiceProfile` is defined for the parent Service of an `HTTPRoute`, -proxies will use the `ServiceProfile` configuration, rather than the -`HTTPRoute` configuration, as long as the `ServiceProfile` exists. -{{< /warning >}} - Next, we give a list of rules that will act on the traffic hitting that Service. The first rule contains two entries: `matches` and `backendRefs`. @@ -150,7 +125,7 @@ In `backendRefs` we specify the final destination for requests matching the current rule, via the Service's `name` and `port`. Here we're specifying we'd like to route to `backend-b-podinfo` all the requests -having the `x-request-id: alterrnative` header. If the header is not present, +having the `x-request-id: alternative` header. If the header is not present, the engine fall backs to the last rule which has no `matches` entries and points to the `backend-a-podinfo` Service. @@ -163,7 +138,7 @@ $ curl -sX POST localhost:9898/echo \ PODINFO_UI_MESSAGE=A backend ``` -But if we add the "`x-request-id: alternative`" header they get routed to +But if we add the `x-request-id: alternative` header, they get routed to `backend-b-podinfo`: ```bash @@ -175,17 +150,17 @@ $ curl -sX POST \ PODINFO_UI_MESSAGE=B backend ``` -### To Keep in Mind +### Implementation notes -Note that you can use any header you like, but for this to work the frontend has -to forward it. "`x-request-id`" is a common header used in microservices, that is -explicitly forwarded by podinfo, and that's why we chose it. +In the example above, we used the `x-request-id` header, which is a common +header that is forwarded by podinfo. However, the same technique will work with +arbitrary headers, as long as the application forwards them. -Also, keep in mind the linkerd proxy handles this on the client side of the -request (the frontend pod in this case) and so that pod needs to be injected, -whereas the destination pods don't require to be injected. But of course the -more workloads you have injected the better, to benefit from things like easy -mTLS setup and all the other advantages that linkerd brings to the table! +Note also that dyanmic request routing is client-side behavior, so while the +traffic source (in this case, the frontend pod) needs to be meshed, strictly +speaking, the destination does not need to be meshed. -[`HTTPRoute`]: ../../features/httproute/ +[HTTPRoute]: ../../reference/httproute/ +[GRPCRoute]: ../../reference/httproute/ +[Gateway API]: ../../features/gateway-api/ [`ServiceProfile`]: ../../features/ServiceProfile/ diff --git a/linkerd.io/content/2.16/tasks/configuring-retries.md b/linkerd.io/content/2.16/tasks/configuring-retries.md deleted file mode 100644 index ba3cd3d49b..0000000000 --- a/linkerd.io/content/2.16/tasks/configuring-retries.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -title: Configuring Retries -description: Configure Linkerd to automatically retry failing requests. ---- - -In order for Linkerd to do automatic retries of failures, there are two -questions that need to be answered: - -- Which requests should be retried? -- How many times should the requests be retried? - -Both of these questions can be answered by adding annotations to the Service, -HTTPRoute, or GRPCRoute resource you're sending requests to. - -The reason why these pieces of configuration are required is because retries can -potentially be dangerous. Automatically retrying a request that changes state -(e.g. a request that submits a financial transaction) could potentially impact -your user's experience negatively. In addition, retries increase the load on -your system. A set of services that have requests being constantly retried -could potentially get taken down by the retries instead of being allowed time -to recover. - -Check out the [retries section](../books/#retries) of the books demo -for a tutorial of how to configure retries. - -{{< warning >}} -Retries configured in this way are **incompatible with ServiceProfiles**. If a -[ServiceProfile](../../features/service-profiles/) is defined for a Service, -proxies will use the ServiceProfile retry configuration and ignore any retry -annotations. -{{< /warning >}} - -## Retries - -For HTTPRoutes that are idempotent, you can add the `retry.linkerd.io/http: 5xx` -annotation which instructs Linkerd to retry any requests which fail with an HTTP -response status in the 500s. - -Note that requests will not be retried if the body exceeds 64KiB. - -## Retry Limits - -You can also add the `retry.linkerd.io/limit` annotation to specify the maximum -number of times a request may be retried. By default, this limit is `1`. - -## gRPC Retries - -Retries can also be configured for gRPC traffic by adding the -`retry.linkerd.io/grpc` annotation to a GRPCRoute or Service resource. The value -of this annotation is a comma seperated list of gRPC status codes that should -be retried. diff --git a/linkerd.io/content/2.16/tasks/configuring-timeouts.md b/linkerd.io/content/2.16/tasks/configuring-timeouts.md deleted file mode 100644 index 6ac672a5be..0000000000 --- a/linkerd.io/content/2.16/tasks/configuring-timeouts.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: Configuring Timeouts -description: Configure Linkerd to automatically fail requests that take too long. ---- - -To limit how long Linkerd will wait before failing an outgoing request 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 by adding annotations to HTTPRoute, GRPCRoute, or -Service resources. - -{{< warning >}} -Timeouts configured in this way are **incompatible with ServiceProfiles**. If a -[ServiceProfile](../../features/service-profiles/) is defined for a Service, -proxies will use the ServiceProfile timeout configuration and ignore any timeout -annotations. -{{< /warning >}} - -## Timeouts - -Check out the [timeouts section](../books/#timeouts) of the books demo -for a tutorial of how to configure timeouts. diff --git a/linkerd.io/content/2.16/tasks/getting-per-route-metrics.md b/linkerd.io/content/2.16/tasks/getting-per-route-metrics.md deleted file mode 100644 index 5cb7b2c26e..0000000000 --- a/linkerd.io/content/2.16/tasks/getting-per-route-metrics.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: Getting Per-Route Metrics -description: Configure per-route metrics for your application. ---- - -To get per-route metrics, you must create [HTTPRoute] resources. If a route has -a `parent_ref` which points to a **Service** resource, Linkerd will generate -outbound per-route traffic metrics for all HTTP traffic that it sends to that -Service. If a route has a `parent_ref` which points to a **Server** resource, -Linkerd will generate inbound per-route traffic metrcs for all HTTP traffic that -it receives on that Server. Note that an [HTTPRoute] can have multiple -`parent_ref`s which means that the same [HTTPRoute] resource can be used to -describe both outbound and inbound routes. - -For a tutorial that shows off per-route metrics, check out the -[books demo](../books/#service-profiles). - -{{< note >}} -Routes configured in service profiles are different from [HTTPRoute] resources. -If a [ServiceProfile](../../features/service-profiles/) is defined for a -Service, proxies will ignore any [HTTPRoute] for that Service. -{{< /note >}} - -[HTTPRoute]: ../../features/httproute/ diff --git a/linkerd.io/content/2.16/tasks/per-request-policy.md b/linkerd.io/content/2.16/tasks/per-request-policy.md deleted file mode 100644 index 4dfa701414..0000000000 --- a/linkerd.io/content/2.16/tasks/per-request-policy.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -title: Per-Request Policy -description: Using HTTP headers to specify per-request policy ---- - -[Retries](../configuring-retries/) and [timeouts](../configuring-timeouts/) can -be configured by annotating Service, HTTPRoute, or GRPCRoute resources. This -will apply the retry or timeout policy to all requests that are sent to that -service/route. - -Additionally, retry and timeout policy can be configured for individual HTTP -requests by adding special HTTP headers to those requests. - -## Enabling Per-Request Policy - -In order to enable per-request policy, Linkerd must be installed with the -`--set policyController.additionalArgs="--allow-l5d-request-headers"` flag or -the corresponding Helm value. Enabling per-request policy is **not** -recommended if your application accepts requests from untrusted sources (e.g. -if it is an ingress) since this allows untrusted clients to specify Linkerd -policy. - -## Per-Request Policy Headers - -Once per-request policy is enabled, the following HTTP headers can be added to -a request to set or override retry and/or timeout policy for that request: - -+ `l5d-retry-http`: Overrides the `retry.linkerd.io/http` annotation -+ `l5d-retry-grpc`: Overrides the `retry.linkerd.io/grpc` annotation -+ `l5d-retry-limit`: Overrides the `retry.linkerd.io/limit` annotation -+ `l5d-retry-timeout`: Overrides the `retry.linkerd.io/timeout` annotation -+ `l5d-timeout`: Overrides the `timeout.linkerd.io/request` annotation -+ `l5d-response-timeout`: Overrides the `timeout.linkerd.io/response` annotation diff --git a/linkerd.io/content/2.16/tasks/restricting-access.md b/linkerd.io/content/2.16/tasks/restricting-access.md index 699d726c68..3fbb1a03cb 100644 --- a/linkerd.io/content/2.16/tasks/restricting-access.md +++ b/linkerd.io/content/2.16/tasks/restricting-access.md @@ -167,16 +167,18 @@ explicitly create an authorization to allow those probe requests. For more information about adding route-scoped authorizations, see [Configuring Per-Route Policy](../configuring-per-route-policy/). -## Further Considerations - Audit Mode +## Enabling authorization policies in live systems You may have noticed that there was a period of time after we created the `Server` resource but before we created the `ServerAuthorization` where all requests were being rejected. To avoid this situation in live systems, we -recommend that you enable [audit mode](../../features/server-policy/#audit-mode) -in the `Server` resource (via `accessPolicy:audit`) and check the proxy -logs/metrics in the target services to see if traffic would get inadvertently -denied. Afterwards, when you're sure about your policy rules, you can fully -enable them by resetting `accessPolicy` back to `deny`. +recommend that you start with [audit +mode](../../features/server-policy/#audit-mode) enabled on the `Server` +resource. In this mode, traffic that violates the policy will not actually be +denied, and you will be able to check the proxy logs/metrics on the target +services for a complete picture of what would happen when audit mode is +disabled. Once you're sure about your policy rules, you can fully enable them by +removing audit mode to enforce the policies. ## Per-Route Policy diff --git a/linkerd.io/content/2.16/tasks/setting-up-service-profiles.md b/linkerd.io/content/2.16/tasks/setting-up-service-profiles.md index 0950e937c9..a77a903f7b 100644 --- a/linkerd.io/content/2.16/tasks/setting-up-service-profiles.md +++ b/linkerd.io/content/2.16/tasks/setting-up-service-profiles.md @@ -4,6 +4,14 @@ description: Create a service profile that provides more details for Linkerd to on. --- +{{< warning >}} +As of Linkerd 2.16, ServiceProfiles have been fully supplanted by [Gateway API +types](../../features/gateway-api/), including for getting per-route metrics, +specifying timeouts, and specifying retries. Service profiles continue to be +supported for backwards compatibility, but will not receive further feature +development. +{{< /warning >}} + [Service profiles](../../features/service-profiles/) provide Linkerd additional information about a service and how to handle requests for a service. @@ -11,9 +19,7 @@ When an HTTP (not HTTPS) request is received by a Linkerd proxy, the `destination service` of that request is identified. If a service profile for that destination service exists, then that service profile is used to -to provide [per-route metrics](../getting-per-route-metrics/), -[retries](../configuring-retries/) and -[timeouts](../configuring-timeouts/). +to provide per-route metric, retries, and timeouts. The `destination service` for a request is computed by selecting the value of the first header to exist of, `l5d-dst-override`, @@ -21,10 +27,7 @@ the value of the first header to exist of, `l5d-dst-override`, including the colon, is stripped. That value is mapped to the fully qualified DNS name. When the `destination service` matches the name of a service profile in the namespace of the sender or the -receiver, Linkerd will use that to provide [per-route -metrics](../getting-per-route-metrics/), -[retries](../configuring-retries/) and -[timeouts](../configuring-timeouts/). +receiver, Linkerd will use that for additional features. There are times when you may need to define a service profile for a service which resides in a namespace that you do not control. To diff --git a/linkerd.io/content/2.16/tasks/traffic-shifting.md b/linkerd.io/content/2.16/tasks/traffic-shifting.md index 991adcb8a5..0d39b08167 100644 --- a/linkerd.io/content/2.16/tasks/traffic-shifting.md +++ b/linkerd.io/content/2.16/tasks/traffic-shifting.md @@ -5,25 +5,25 @@ description: Dynamically split and shift traffic between backends Traffic splitting and shifting are powerful features that enable operators to dynamically shift traffic to different backend Services. This can be used to -implement A/B experiments, red/green deploys, canary rollouts, -[fault injection](../fault-injection/) and more. +implement A/B experiments, red/green deploys, canary rollouts, [fault +injection](../fault-injection/), and more. -Linkerd supports two different ways to configure traffic shifting: you can -use the [Linkerd SMI extension](../linkerd-smi/) and +Traffic splitting is accomplished with [HTTPRoute] and [GRPCRoute] types. + +{{< note >}} +Earlier versions of Linkerd provided a [TrafficSplit](https://github.com/servicemeshinterface/smi-spec/blob/main/apis/traffic-split/v1alpha2/traffic-split.md/) -resources, or you can use [HTTPRoute](../../features/httproute/) resources which -Linkerd natively supports. While certain integrations such as -[Flagger](../flagger/) rely on the SMI and `TrafficSplit` approach, using -`HTTPRoute` is the preferred method going forward. +resource as part of the the [Linkerd SMI extension](../linkerd-smi/) for traffic +splitting. This approach is still supported but will not recieve further feature +development. +{{< /note >}} {{< docs/production-note >}} ## Prerequisites -To use this guide, you'll need a Kubernetes cluster running: - -- Linkerd and Linkerd-Viz. If you haven't installed these yet, follow the - [Installing Linkerd Guide](../install/). +To use this guide, you'll need a Kubernetes cluster running Linkerd and +Linkerd-Viz. ## Set up the demo @@ -245,3 +245,7 @@ NAME MESHED SUCCESS RPS LATENCY_P50 LATENCY_P95 LATENCY_P99 TC v1 1/1 - - - - - - v2 1/1 100.00% 10.0rps 1ms 1ms 2ms 1 ``` + +[HTTPRoute]: ../../reference/httproute/ +[GRPCRoute]: ../../reference/httproute/ +[Gateway API]: ../../features/gateway-api/ diff --git a/linkerd.io/content/2.17/features/gateway-api.md b/linkerd.io/content/2.17/features/gateway-api.md new file mode 100644 index 0000000000..014d58fad8 --- /dev/null +++ b/linkerd.io/content/2.17/features/gateway-api.md @@ -0,0 +1,100 @@ +--- +title: Gateway API support +description: Linkerd uses the Gateway API resource types for much configuration. +--- + +The Gateway API is a set of CRDs in the `gateway.networking.k8s.io` API group +which describe types of traffic in a way that is independent of a specific mesh +or ingress implementation. Recent versions of Linkerd fully support the +[Kubernetes Gateway API](https://gateway-api.sigs.k8s.io/) as a core +configuration mechanism, and many Linkerd features, including [authorization +policies][auth-policy], [dynamic traffic routing][dyn-routing], and [request +timeouts][timeouts], rely on resource types from the Gateway API for +configuration. + +The two primary Gateway API types used to configure Linkerd are: + +- [HTTPRoute], which parameterizes HTTP requests +- [GRPCRoute], which parameterizes gRPC requests + +Both of these types are used in a variety of ways when configuring Linkerd. + +## Managing the Gateway API + +One complication with using the Gateway API in practice is that many different +packages, not just Linkerd, may provide the Gateway API on your cluster, but +only some Gateway API *versions* are compatible with Linkerd. + +In practice, there are two basic approaches to managing the Gateway API with +Linkerd. You can let Linkerd manage the Gateway API resources, or you can let a +different tool manage them. + +### Option 1: Linkerd manages the Gateway API + +This is the default behavior for Linkerd, which will create, update, and delete +Gateway API resources as required. In this approach, any other tools on your +system that use Gateway API resources will be need to be compatible with the +version of the Gateway API that Linkerd installs: + +| Linkerd versions | Gateway API version installed | HTTPRoute version | gRPC version | +| ---------------- | ----------------------------- | ----------------- | ------------ | +| 2.15 - 2.17 | 0.7 | v1beta1 | v1alpha2 | + +### Option 2: A different tool manages the Gateway API + +Alternatively, you may prefer to have something other than Linkerd manage the +Gateway API resources on your cluster. To do this, you will need to instruct +Linkerd *not* to install, update, or delete the Gateway API resources, by +passing pass the `--set enableHttpRoutes=false` flag during the `linkerd install +--crds` step, or setting the `enableHttpRoutes=false` Helm value when installing +the `linkerd-crds` Helm chart. + +You will also need to ensure that version of the Gateway API installed is +compatible with Linkerd: + +| Linkerd versions | Compatible Gateway API versions | Recommended Gateway API version | +| ---------------- | ------------------------------- | ------------------------------- | +| 2.15 - 2.17 | 0.7, 0.7.1, 1.1.1-experimental | 1.1.1-experimental | + +If possible, you should install the *recommended* Gateway API version in the +table above. (Note that the use of *experimental* Gateway API versions is +sometimes necessary to allow for full functionality; despite the name, these +versions are production capable.) + +{{< warning >}} +Running Linkerd with an incompatible version of the Gateway API +on the cluster can lead to hard-to-debug issues with your Linkerd installation. +{{< /warning >}} + +## Precursors to Gateway API-based configuration + +Prior to the complete support of the Gateway API introduced in Linkerd 2.14, +Linkerd provided two earlier variants of configuration: + +- A Linkerd-specific `HTTPRoute` CRD provided by Linkerd in the + `policy.linkerd.io` API group +- [ServiceProfiles], which allowed for configuration of per-route metrics, + retries, and timeouts prior to the introduction of the Gateway API types. + +Both of these earlier configuration mechanisms continue to be supported; +however, newer feature development is focused on the standard Gateway API +types. + +## Learn More + +To get started with the Gateway API types, you can: + +- [Configure fault injection](../../tasks/fault-injection/) +- [Configure timeouts][timeouts] +- [Configure dynamic request routing][dyn-routing] +- [Configure per-route authorization policy][auth-policy] + +[HTTPRoute]: ../../reference/httproute/ +[GRPCRoute]: ../../reference/grpcroute/ +[Gateway API]: https://gateway-api.sigs.k8s.io/ +[Service]: https://kubernetes.io/docs/concepts/services-networking/service/ +[Server]: ../../reference/authorization-policy/#server +[auth-policy]: ../../tasks/configuring-per-route-policy/ +[dyn-routing]:../../tasks/configuring-dynamic-request-routing/ +[timeouts]: ../../features/retries-and-timeouts/ +[ServiceProfiles]: ../../features/service-profiles/ diff --git a/linkerd.io/content/2.17/features/httproute.md b/linkerd.io/content/2.17/features/httproute.md deleted file mode 100644 index 199b6f7ea6..0000000000 --- a/linkerd.io/content/2.17/features/httproute.md +++ /dev/null @@ -1,81 +0,0 @@ ---- -title: HTTPRoutes -description: Linkerd can use the HTTPRoute resource to configure per-route policies. ---- - -To configure routing behavior and policy for HTTP traffic, Linkerd supports the -[HTTPRoute resource], defined by the Kubernetes [Gateway API]. - -{{< note >}} -Two versions of the HTTPRoute resource may be used with Linkerd: - -- The upstream version provided by the Gateway API, with the - `gateway.networking.k8s.io` API group -- A Linkerd-specific CRD provided by Linkerd, with the `policy.linkerd.io` API - group - -The two HTTPRoute resource definitions are similar, but the Linkerd version -implements experimental features not yet available with the upstream Gateway API -resource definition. See [the HTTPRoute reference -documentation](../../reference/httproute/#linkerd-and-gateway-api-httproutes) -for details. -{{< /note >}} - -If the Gateway API CRDs already exist in your cluster, then Linkerd must be -installed with the `--set enableHttpRoutes=false` flag during the -`linkerd install --crds` step or with the `enableHttpRoutes=false` Helm value -when installing the `linkerd-crds` Helm chart. This avoid conflicts by -instructing Linkerd to not install the Gateway API CRDs and instead rely on the -Gateway CRDs which already exist. - -An HTTPRoute is a Kubernetes resource which attaches to a parent resource, such -as a [Service]. The HTTPRoute defines a set of rules which match HTTP requests -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: - -- HTTPRoutes with a [Service] as their parent resource configure policies for - _outbound_ proxies in pods which are clients of that [Service]. Outbound - policy includes [dynamic request routing][dyn-routing], adding request - headers, modifying a request's path, and reliability features such as - [timeouts]. -- HTTPRoutes with a [Server] as their parent resource configure policy for - _inbound_ proxies in pods which recieve traffic to that [Server]. Inbound - HTTPRoutes are used to configure fine-grained [per-route authorization and - authentication policies][auth-policy]. - -{{< warning >}} -**Outbound HTTPRoutes and [ServiceProfiles](../service-profiles/) provide -overlapping configuration.** For backwards-compatibility reasons, a -ServiceProfile will take precedence over HTTPRoutes which configure the same -Service. If a ServiceProfile is defined for the parent Service of an HTTPRoute, -proxies will use the ServiceProfile configuration, rather than the HTTPRoute -configuration, as long as the ServiceProfile -exists. -{{< /warning >}} - -## Learn More - -To get started with HTTPRoutes, you can: - -- [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. -- See the [reference documentation](../../reference/httproute/) for a complete - description of the HTTPRoute resource. - -[HTTPRoute resource]: https://gateway-api.sigs.k8s.io/api-types/httproute/ -[Gateway API]: https://gateway-api.sigs.k8s.io/ -[Service]: https://kubernetes.io/docs/concepts/services-networking/service/ -[Server]: ../../reference/authorization-policy/#server -[auth-policy]: ../../tasks/configuring-per-route-policy/ -[dyn-routing]:../../tasks/configuring-dynamic-request-routing/ -[timeouts]: ../../tasks/configuring-timeouts/#using-httproutes diff --git a/linkerd.io/content/2.17/features/retries-and-timeouts.md b/linkerd.io/content/2.17/features/retries-and-timeouts.md index c0c62260ed..e53a7eb18b 100644 --- a/linkerd.io/content/2.17/features/retries-and-timeouts.md +++ b/linkerd.io/content/2.17/features/retries-and-timeouts.md @@ -1,27 +1,100 @@ --- title: Retries and Timeouts -description: Linkerd can perform service-specific retries and timeouts. +description: Linkerd can retry and timeout HTTP and gRPC requests. weight: 3 --- -Timeouts and automatic retries are two of the most powerful and useful -mechanisms a service mesh has for gracefully handling partial or transient -application failures. +Timeouts and automatic retries are two of the most powerful mechanisms a service +mesh has for gracefully handling partial or transient application failures. -Timeouts and retries can be configured using [HTTPRoute], GRPCRoute, or Service -resources. Retries and timeouts are always performed on the *outbound* (client) -side. +* **Timeouts** allow Linkerd to cancel a request that is exceeding a time + limit. +* **Retries** allow Linkerd to automatically retry failed requests, potentially + sending it to a different endpoint. + +Timeouts and retries are configured with a set of annotations, e.g +`retry.linkerd.io/http` and `timeout.linkerd.io/request`. These annotations are +placed on [HTTPRoute] or [GRPCRoute] resources to configure behavior on HTTP or +gRPC requests that match those resources. Alternatively, they can be placed on +`Service` resources configure retries and timeouts for all traffic to that +service. + +As of Linkerd 2.16, timeouts and retries *compose*: requests that timeout are +eligible for being retried. + +{{< note >}} +Note that retries and timeouts are performed on the *outbound* (client) side. +This means that regardless of where the annotations are placed, the source of +the traffic must be meshed. +{{< /note >}} {{< note >}} -If working with headless services, outbound policy cannot be retrieved. Linkerd -reads service discovery information based off the target IP address, and if that -happens to be a pod IP address then it cannot tell which service the pod belongs -to. +Retries and timeouts do not work with headless services. This is because +Linkerd reads service discovery information based off the target IP address, and +if that happens to be a pod IP address then it cannot tell which service the pod +belongs to. {{< /note >}} -These can be setup by following the guides: +{{< warning >}} +Prior to Linkerd 2.16, retries and timeouts were configured with +[ServiceProfile](../../reference/service-profiles/)s. While service profiles are +still supported, retries configured with HTTPRoute or GPRCRoute are +**incompatible with ServiceProfiles**. If a ServiceProfile is defined for a +Service, proxies will use the ServiceProfile retry configuration and ignore any +retry annotations. +{{< /warning >}} + +## Using retries safely + +Retries are an opt-in behavior that require some thought and planning. Misuse +can be dangerous. First, automatically retrying a request that changes system +state each time it is called can be disastrous. Thus, retries should only be +used on _idempotent_ methods, i.e. methods that have the same effect even if +called multiple times. + +Second, retries by definition will increase the load on your system. A set of +services that have requests being constantly retried could potentially get taken +down by the retries instead of being allowed time to recover. + +The exact configuration of retry behavior to improve overall reliability +without significantly increasing risk will require some care on the part of the +user. + +## Per-request policies + +In addition to the annotation approach outlined above, retries and timeouts +can be set on a per-request basis by setting specific HTTP headers. + +In order to enable this per-request policy, Linkerd must be installed with the +`--set policyController.additionalArgs="--allow-l5d-request-headers"` flag or +the corresponding Helm value. + +{{< warning >}} +Per-request policies should **not** be enabled if your application accepts +unfiltered requests from untrusted sources. For example, if you mesh an ingress +controller which takes unfiltered Internet traffic (and you do not use +`skip-inbound-ports` to instruct Linkerd to skip handling inbound traffic to the +pod), untrusted clients will be able to specify Linkerd retry and timeout policy +on their requests. +{{< /warning >}} + +Once per-request policy is enabled, you can set timeout and retry policy on +individual requests by setting these headers: + +* `l5d-retry-http`: Overrides the `retry.linkerd.io/http` annotation +* `l5d-retry-grpc`: Overrides the `retry.linkerd.io/grpc` annotation +* `l5d-retry-limit`: Overrides the `retry.linkerd.io/limit` annotation +* `l5d-retry-timeout`: Overrides the `retry.linkerd.io/timeout` annotation +* `l5d-timeout`: Overrides the `timeout.linkerd.io/request` annotation +* `l5d-response-timeout`: Overrides the `timeout.linkerd.io/response` annotation + +## Further reading -- [Configuring Retries](../../tasks/configuring-retries/) -- [Configuring Timeouts](../../tasks/configuring-timeouts/) +* [Retries reference](../../reference/retries/) +* [Timeout reference](../../reference/timeouts/) +* The [Debugging HTTP applications with per-route + metrics](../../tasks/books/) contains examples of retries and timeout + annotations. -[HTTPRoute]: ../httproute/ +[HTTPRoute]: ../../reference/httproute/ +[GRPCRoute]: ../../reference/grpcroute/ diff --git a/linkerd.io/content/2.17/features/server-policy.md b/linkerd.io/content/2.17/features/server-policy.md index 757d7e5603..12cae0e9f7 100644 --- a/linkerd.io/content/2.17/features/server-policy.md +++ b/linkerd.io/content/2.17/features/server-policy.md @@ -70,11 +70,12 @@ Linkerd uses a set of CRDs. In contrast to default policy annotations, these policy CRDs can be changed dynamically and policy behavior will be updated on the fly. -Two policy CRDs represent "targets" for policy: subsets of traffic over which +Three policy CRDs represent "targets" for policy: subsets of traffic over which policy can be applied. - [`Server`]: all traffic to a port, for a set of pods in a namespace -- [`HTTPRoute`]: a subset of HTTP requests for a [`Server`] +- [`HTTPRoute`]: a subset of HTTP requests for a `Server` +- [`GRPCRoute`]: a subset of gRPC requests for a `Server` Two policy CRDs represent authentication rules that must be satisfied as part of a policy rule: @@ -90,11 +91,11 @@ authentication rules to targets. unless an authentication rule is met - `ServerAuthorization`: an earlier form of policy that restricts access to - [`Server`]s only (i.e. not [`HTTPRoute`]s) + `Server`s only (i.e. not `HTTPRoute`s or `GRPCRoute`s) The general pattern for Linkerd's dynamic, fine-grained policy is to define the traffic target that must be protected (via a combination of `Server` and -[`HTTPRoute`] CRs); define the types of authentication that are required before +`HTTPRoute` CRs); define the types of authentication that are required before access to that traffic is permitted (via `MeshTLSAuthentication` and `NetworkAuthentication`); and then define the policy that maps authentication to target (via an `AuthorizationPolicy`). @@ -105,7 +106,7 @@ details on how these resources work. ## ServerAuthorization vs AuthorizationPolicy Linkerd 2.12 introduced `AuthorizationPolicy` as a more flexible alternative to -`ServerAuthorization` that can target [`HTTPRoute`]s as well as `Server`s. Use of +`ServerAuthorization` that can target `HTTPRoute`s as well as `Server`s. Use of `AuthorizationPolicy` is preferred, and `ServerAuthorization` will be deprecated in future releases. @@ -116,11 +117,11 @@ from Kubernetes, meaning that the pod would not be able to start. Thus, any default-deny setup must, in practice, still authorize these probes. In order to simplify default-deny setups, Linkerd automatically authorizes -probes to pods. These default authorizations apply only when no [`Server`] is -configured for a port, or when a [`Server`] is configured but no [`HTTPRoute`]s are -configured for that [`Server`]. If any [`HTTPRoute`] matches the `Server`, these -automatic authorizations are not created and you must explicitly create them for -health and readiness probes. +probes to pods. These default authorizations apply only when no `Server` is +configured for a port, or when a `Server` is configured but no `HTTPRoute`s or +`GRPCRoute` are configured for that `Server`. If any `HTTPRoute` or `GRPCRoute` +matches the `Server`, these automatic authorizations are not created and you +must explicitly create them for health and readiness probes. ## Policy rejections @@ -133,7 +134,7 @@ result in an abrupt termination of those connections. ## Audit mode -A [`Server`]'s default policy is defined in its `accessPolicy` field, which +A `Server`'s default policy is defined in its `accessPolicy` field, which defaults to `deny`. That means that, by default, traffic that doesn't conform to the rules associated to that Server is denied (the same applies to `Servers` that don't have associated rules yet). This can inadvertently prevent traffic if @@ -166,5 +167,6 @@ be allowed but it would be logged and surfaced in metrics as detailed above. - [Authorization policy reference](../../reference/authorization-policy/) - [Guide to configuring per-route policy](../../tasks/configuring-per-route-policy/) -[`HTTPRoute`]: ../httproute/ +[`HTTPRoute`]: ../../reference/httproute/ +[`GRPCRoute`]: ../../reference/grpcroute/ [`Server`]: ../../reference/authorization-policy/#server diff --git a/linkerd.io/content/2.17/features/service-profiles.md b/linkerd.io/content/2.17/features/service-profiles.md index adc9bac675..6b84f5c149 100644 --- a/linkerd.io/content/2.17/features/service-profiles.md +++ b/linkerd.io/content/2.17/features/service-profiles.md @@ -4,11 +4,12 @@ description: Linkerd's service profiles enable per-route metrics as well as retr and timeouts. --- -{{< note >}} -[HTTPRoutes](../httproute/) are the recommended method for getting per-route -metrics, specifying timeouts, and specifying retries. Service profiles continue -to be supported for backwards compatibility. -{{< /note >}} +{{< warning >}} +As of Linkerd 2.16, ServiceProfiles have been fully supplanted by [Gateway API +types](../gateway-api/), including for getting per-route metrics, specifying +timeouts, and specifying retries. Service profiles continue to be supported for +backwards compatibility, but will not receive further feature development. +{{< /warning >}} A service profile is a custom Kubernetes resource ([CRD][crd]) that can provide Linkerd additional information about a service. In particular, it allows you to diff --git a/linkerd.io/content/2.17/reference/grpcroute.md b/linkerd.io/content/2.17/reference/grpcroute.md new file mode 100644 index 0000000000..e049d3518b --- /dev/null +++ b/linkerd.io/content/2.17/reference/grpcroute.md @@ -0,0 +1,85 @@ +--- +title: GRPCRoute +description: Reference guide to GRPCRoute resources. +--- + +A GRPCRoute is a Kubernetes resource which attaches to a "parent" resource, +such as a [Service], and defines a set of rules which match gRPC requests to +that resource. These rules can be based on parameters such as path, method, +headers, or other aspects of the gRPC request. + +GRPCRoutes are used to configure various aspects of Linkerd's behavior, and form +part of [Linkerd's support for the Gateway API](../../features/gateway-api/). + +{{< note >}} +The GRPCRoute resource is part of the Gateway API and is not Linkerd-specific. +The canonical reference doc is the [Gateway API GRPCRoute +documentation](https://gateway-api.sigs.k8s.io/api-types/grpcroute/). This page +is intended as a *supplement* to that doc, and will detail how this type is +used by Linkerd specifically. +{{< /note >}} + +## Inbound vs outbound GRPCRoutes + +GRPCRoutes usage in Linkerd falls into two categories: configuration of +*inbound* behavior and configuration of *outbound* behavior. + +**Inbound behavior.** GRPCRoutes with a [Server] as their parent resource +configure policy for _inbound_ traffic to pods which receive traffic to that +[Server]. Inbound GRPCRoutes are used to configure fine-grained [per-route +authorization and authentication policies][auth-policy]. + +**Outbound behavior.** GRPCRoutes with a [Service] as their parent resource +configure policies for _outbound_ proxies in pods which are clients of that +[Service]. Outbound policy includes [dynamic request routing][dyn-routing], +adding request headers, modifying a request's path, and reliability features +such as [timeouts]. + +{{< warning >}} +**Outbound GRPCRoutes and [ServiceProfiles](../service-profiles/) provide +overlapping configuration.** For backwards-compatibility reasons, a +ServiceProfile will take precedence over GRPCRoutes which configure the same +Service. If a ServiceProfile is defined for the parent Service of an GRPCRoute, +proxies will use the ServiceProfile configuration, rather than the GRPCRoute +configuration, as long as the ServiceProfile +exists. +{{< /warning >}} + +## Usage in practice + +See important notes in the [Gateway API] documentation about using these types +in practice, including ownership of types and compatible versions. + +## GRPCRoute Examples + +This example demonstrates how to split traffic between two backends. A portion +of requests is directed to the `smiley2` backend Service, while the rest go to +the `smiley` backend Service. + +```yaml +apiVersion: gateway.networking.k8s.io/v1alpha2 +kind: GRPCRoute +metadata: + name: smiley-a-b + namespace: faces +spec: + parentRefs: + - name: smiley + kind: Service + group: core + port: 50051 + rules: + - backendRefs: + - name: smiley + port: 50051 + weight: 40 + - name: smiley2 + port: 80 + weight: 50051 +``` + +[ServiceProfile]: ../../features/service-profiles/ +[Gateway API]: https://gateway-api.sigs.k8s.io/ +[ns-boundaries]: https://gateway-api.sigs.k8s.io/geps/gep-1426/#namespace-boundaries +[Server]: ../authorization-policy/#server +[Service]: https://kubernetes.io/docs/concepts/services-networking/service/ diff --git a/linkerd.io/content/2.17/reference/httproute.md b/linkerd.io/content/2.17/reference/httproute.md index b94f709d58..11c35b91e7 100644 --- a/linkerd.io/content/2.17/reference/httproute.md +++ b/linkerd.io/content/2.17/reference/httproute.md @@ -3,35 +3,59 @@ title: HTTPRoute description: Reference guide to HTTPRoute resources. --- - - - - -## Linkerd and Gateway API HTTPRoutes - -The HTTPRoute resource was originally specified by the Kubernetes [Gateway API] -project. Linkerd currently supports two versions of the HTTPRoute resource: the -upstream version from the Gateway API, with the -`gateway.networking.kubernetes.io` API group, and a Linkerd-specific version, -with the `policy.linkerd.io` API group. While these two resource definitions are -largely the same, the `policy.linkerd.io` HTTPRoute resource is an experimental -version that contains features not yet stabilized in the upstream -`gateway.networking.k8s.io` HTTPRoute resource, such as -[timeouts](#httproutetimeouts). Both the Linkerd and Gateway API resource -definitions coexist within the same cluster, and both can be used to configure -policies for use with Linkerd. - -If the Gateway API CRDs already exist in your cluster, then Linkerd must be -installed with the `--set enableHttpRoutes=false` flag during the -`linkerd install --crds` step or with the `enableHttpRoutes=false` Helm value -when installing the `linkerd-crds` Helm chart. This avoid conflicts by -instructing Linkerd to not install the Gateway API CRDs and instead rely on the -Gateway CRDs which already exist. - -This documentation describes the `policy.linkerd.io` HTTPRoute resource. For a -similar description of the upstream Gateway API HTTPRoute resource, refer to the -Gateway API's [HTTPRoute -specification](https://gateway-api.sigs.k8s.io/references/spec/#gateway.networking.k8s.io/v1beta1.HTTPRoute). +An HTTPRoute is a Kubernetes resource which attaches to a "parent" resource, +such as a [Service], and defines a set of rules which match HTTP requests to +that resource. These rules can be based on parameters such as path, method, +headers, or other aspects of the HTTP request. + +HTTPRoutes are used to configure various aspects of Linkerd's behavior, and form +part of [Linkerd's support for the Gateway API](../../features/gateway-api/). + +{{< note >}} +The HTTPRoute resource is part of the Gateway API and is not Linkerd-specific. +The canonical reference doc is the [Gateway API HTTPRoute +documentation](https://gateway-api.sigs.k8s.io/api-types/httproute/). This page +is intended as a *supplement* to that doc, and will detail how this type is +used by Linkerd specifically. +{{< /note >}} + +## Inbound vs outbound HTTPRoutes + +HTTPRoutes usage in Linkerd falls into two categories: configuration of +*inbound* behavior and configuration of *outbound* behavior. + +**Inbound behavior.** HTTPRoutes with a [Server] as their parent resource +configure policy for _inbound_ traffic to pods which receive traffic to that +[Server]. Inbound HTTPRoutes are used to configure fine-grained [per-route +authorization and authentication policies][auth-policy]. + +**Outbound behavior.** HTTPRoutes with a [Service] as their parent resource +configure policies for _outbound_ proxies in pods which are clients of that +[Service]. Outbound policy includes [dynamic request routing][dyn-routing], +adding request headers, modifying a request's path, and reliability features +such as [timeouts]. + +{{< warning >}} +**Outbound HTTPRoutes and [ServiceProfiles](../service-profiles/) provide +overlapping configuration.** For backwards-compatibility reasons, a +ServiceProfile will take precedence over HTTPRoutes which configure the same +Service. If a ServiceProfile is defined for the parent Service of an HTTPRoute, +proxies will use the ServiceProfile configuration, rather than the HTTPRoute +configuration, as long as the ServiceProfile +exists. +{{< /warning >}} + +## Usage in practice + +See important notes in the [Gateway API] documentation about using these types +in practice, including ownership of types and compatible versions. + +## The `policy.linkerd.io` group + +In earlier Linkerd versions, Linkerd provided a variant of the HTTPRoute +resource in the `policy.linkerd.io` group. These versions are still supported +but are not actively maintained; users are encouraged to switch to the canonical +`gateway.networking.kubernetes.io` resources. ## HTTPRoute Spec @@ -58,13 +82,6 @@ depending on path, headers, query params, and/or verb. Requests can then be rerouted to different backend services. This can be used to perform [dynamic request routing](../../tasks/configuring-dynamic-request-routing/). -{{< warning >}} **Outbound HTTPRoutes and [ServiceProfile]s provide overlapping -configuration.** For backwards-compatibility reasons, a ServiceProfile will -take precedence over HTTPRoutes which configure the same Service. If a -ServiceProfile is defined for the parent Service of an HTTPRoute, proxies will -use the ServiceProfile configuration, rather than the HTTPRoute configuration, -as long as the ServiceProfile exists. {{< /warning >}} - ParentReferences are namespaced, and may reference either a parent in the same namespace as the HTTPRoute, or one in a different namespace. As described in [GEP-1426][ns-boundaries], a HTTPRoute with a `parentRef` that references a @@ -317,3 +334,4 @@ spec: [Gateway API]: https://gateway-api.sigs.k8s.io/ [ns-boundaries]: https://gateway-api.sigs.k8s.io/geps/gep-1426/#namespace-boundaries [Server]: ../authorization-policy/#server +[Service]: https://kubernetes.io/docs/concepts/services-networking/service/ diff --git a/linkerd.io/content/2.17/reference/proxy-metrics.md b/linkerd.io/content/2.17/reference/proxy-metrics.md index 743aebf3c2..feb6de3d24 100644 --- a/linkerd.io/content/2.17/reference/proxy-metrics.md +++ b/linkerd.io/content/2.17/reference/proxy-metrics.md @@ -276,4 +276,4 @@ following labels: [prom-format]: https://prometheus.io/docs/instrumenting/exposition_formats/#format-version-0.0.4 [pod-template-hash]: https://kubernetes.io/docs/concepts/workloads/controllers/deployment/#pod-template-hash-label [ttfb]: https://en.wikipedia.org/wiki/Time_to_first_byte -[HTTPRoute]: ../../features/httproute/ +[HTTPRoute]: ../httproute/ diff --git a/linkerd.io/content/2.17/reference/service-profiles.md b/linkerd.io/content/2.17/reference/service-profiles.md index ac4af46148..362a53ba79 100644 --- a/linkerd.io/content/2.17/reference/service-profiles.md +++ b/linkerd.io/content/2.17/reference/service-profiles.md @@ -3,6 +3,14 @@ title: Service Profiles description: Details on the specification and what is possible with service profiles. --- +{{< warning >}} +As of Linkerd 2.16, ServiceProfiles have been fully supplanted by [Gateway API +types](../../features/gateway-api/), including for getting per-route metrics, +specifying timeouts, and specifying retries. Service profiles continue to be +supported for backwards compatibility, but will not receive further feature +development. +{{< /warning >}} + [Service profiles](../../features/service-profiles/) provide Linkerd additional information about a service. This is a reference for everything that can be done with service profiles. diff --git a/linkerd.io/content/2.17/tasks/configuring-dynamic-request-routing.md b/linkerd.io/content/2.17/tasks/configuring-dynamic-request-routing.md index 4e38c7fe6f..23c1c4e802 100644 --- a/linkerd.io/content/2.17/tasks/configuring-dynamic-request-routing.md +++ b/linkerd.io/content/2.17/tasks/configuring-dynamic-request-routing.md @@ -1,22 +1,22 @@ --- title: Configuring Dynamic Request Routing -description: Configuring HTTPRoute resources to perform dynamic request routing. +description: Dynamically route traffic based on parts of the HTTP call. --- ## Prerequisites -To use this guide, you'll need to have Linkerd installed on your cluster. Follow -the [Installing Linkerd Guide](../install/) if you haven't already done this -(make sure you have at least linkerd stable-2.13.0 or edge-23.3.2). +To use this guide, you'll need to have Linkerd installed on your cluster and the +[Helm](https://helm.sh/docs/intro/quickstart/) CLI installed. -You also need to have the [Helm](https://helm.sh/docs/intro/quickstart/) CLI -installed. +## Dynamic request routing -## HTTPRoute for Dynamic Request Routing - -With dynamic request routing, you can route HTTP traffic based on the contents +With dynamic request routing, you can route HTTP traffic based on the content of request headers. This can be useful for performing things like A/B testing -and many other strategies for traffic management. +and other strategies for traffic management. + +The core configuration mechanism are the [Gateway API] types, [HTTPRoute] and +[GRPCRoute]. In this example we'll look at the common use case using the +HTTPRoute type. In this tutorial, we'll make use of the [podinfo](https://github.com/stefanprodan/podinfo) project to showcase dynamic @@ -75,7 +75,7 @@ PODINFO_UI_MESSAGE=A backend ## Introducing HTTPRoute -Let's apply the following [`HTTPRoute`] resource to enable header-based routing: +Let's apply the following `HTTPRoute` resource to enable header-based routing: ```yaml cat <}} -Two versions of the HTTPRoute resource may be used with Linkerd: - -- The upstream version provided by the Gateway API, with the - `gateway.networking.k8s.io` API group -- A Linkerd-specific CRD provided by Linkerd, with the `policy.linkerd.io` API - group - -The two HTTPRoute resource definitions are similar, but the Linkerd version -implements experimental features not yet available with the upstream Gateway API -resource definition. See [the HTTPRoute reference -documentation](../../reference/httproute/#linkerd-and-gateway-api-httproutes) -for details. -{{< /note >}} - -In `parentRefs` we specify the resources we want this [`HTTPRoute`] instance to -act on. So here we point to the `backend-a-podinfo` Service on the [`HTTPRoute`]'s +In `parentRefs` we specify the resources we want this `HTTPRoute` instance to +act on. So here we point to the `backend-a-podinfo` Service on the `HTTPRoute`'s namespace (`test`), and also specify the Service port number (not the Service's target port). -{{< warning >}} -**Outbound [`HTTPRoute`](../../features/httproute/)s and -[`ServiceProfile`](../../features/service-profiles/)s provide overlapping -configuration.** For backwards-compatibility reasons, a `ServiceProfile` will -take precedence over `HTTPRoute`s which configure the same Service. If a -`ServiceProfile` is defined for the parent Service of an `HTTPRoute`, -proxies will use the `ServiceProfile` configuration, rather than the -`HTTPRoute` configuration, as long as the `ServiceProfile` exists. -{{< /warning >}} - Next, we give a list of rules that will act on the traffic hitting that Service. The first rule contains two entries: `matches` and `backendRefs`. @@ -150,7 +125,7 @@ In `backendRefs` we specify the final destination for requests matching the current rule, via the Service's `name` and `port`. Here we're specifying we'd like to route to `backend-b-podinfo` all the requests -having the `x-request-id: alterrnative` header. If the header is not present, +having the `x-request-id: alternative` header. If the header is not present, the engine fall backs to the last rule which has no `matches` entries and points to the `backend-a-podinfo` Service. @@ -163,7 +138,7 @@ $ curl -sX POST localhost:9898/echo \ PODINFO_UI_MESSAGE=A backend ``` -But if we add the "`x-request-id: alternative`" header they get routed to +But if we add the `x-request-id: alternative` header, they get routed to `backend-b-podinfo`: ```bash @@ -175,17 +150,17 @@ $ curl -sX POST \ PODINFO_UI_MESSAGE=B backend ``` -### To Keep in Mind +### Implementation notes -Note that you can use any header you like, but for this to work the frontend has -to forward it. "`x-request-id`" is a common header used in microservices, that is -explicitly forwarded by podinfo, and that's why we chose it. +In the example above, we used the `x-request-id` header, which is a common +header that is forwarded by podinfo. However, the same technique will work with +arbitrary headers, as long as the application forwards them. -Also, keep in mind the linkerd proxy handles this on the client side of the -request (the frontend pod in this case) and so that pod needs to be injected, -whereas the destination pods don't require to be injected. But of course the -more workloads you have injected the better, to benefit from things like easy -mTLS setup and all the other advantages that linkerd brings to the table! +Note also that dyanmic request routing is client-side behavior, so while the +traffic source (in this case, the frontend pod) needs to be meshed, strictly +speaking, the destination does not need to be meshed. -[`HTTPRoute`]: ../../features/httproute/ +[HTTPRoute]: ../../reference/httproute/ +[GRPCRoute]: ../../reference/httproute/ +[Gateway API]: ../../features/gateway-api/ [`ServiceProfile`]: ../../features/ServiceProfile/ diff --git a/linkerd.io/content/2.17/tasks/configuring-retries.md b/linkerd.io/content/2.17/tasks/configuring-retries.md deleted file mode 100644 index ba3cd3d49b..0000000000 --- a/linkerd.io/content/2.17/tasks/configuring-retries.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -title: Configuring Retries -description: Configure Linkerd to automatically retry failing requests. ---- - -In order for Linkerd to do automatic retries of failures, there are two -questions that need to be answered: - -- Which requests should be retried? -- How many times should the requests be retried? - -Both of these questions can be answered by adding annotations to the Service, -HTTPRoute, or GRPCRoute resource you're sending requests to. - -The reason why these pieces of configuration are required is because retries can -potentially be dangerous. Automatically retrying a request that changes state -(e.g. a request that submits a financial transaction) could potentially impact -your user's experience negatively. In addition, retries increase the load on -your system. A set of services that have requests being constantly retried -could potentially get taken down by the retries instead of being allowed time -to recover. - -Check out the [retries section](../books/#retries) of the books demo -for a tutorial of how to configure retries. - -{{< warning >}} -Retries configured in this way are **incompatible with ServiceProfiles**. If a -[ServiceProfile](../../features/service-profiles/) is defined for a Service, -proxies will use the ServiceProfile retry configuration and ignore any retry -annotations. -{{< /warning >}} - -## Retries - -For HTTPRoutes that are idempotent, you can add the `retry.linkerd.io/http: 5xx` -annotation which instructs Linkerd to retry any requests which fail with an HTTP -response status in the 500s. - -Note that requests will not be retried if the body exceeds 64KiB. - -## Retry Limits - -You can also add the `retry.linkerd.io/limit` annotation to specify the maximum -number of times a request may be retried. By default, this limit is `1`. - -## gRPC Retries - -Retries can also be configured for gRPC traffic by adding the -`retry.linkerd.io/grpc` annotation to a GRPCRoute or Service resource. The value -of this annotation is a comma seperated list of gRPC status codes that should -be retried. diff --git a/linkerd.io/content/2.17/tasks/configuring-timeouts.md b/linkerd.io/content/2.17/tasks/configuring-timeouts.md deleted file mode 100644 index 6ac672a5be..0000000000 --- a/linkerd.io/content/2.17/tasks/configuring-timeouts.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: Configuring Timeouts -description: Configure Linkerd to automatically fail requests that take too long. ---- - -To limit how long Linkerd will wait before failing an outgoing request 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 by adding annotations to HTTPRoute, GRPCRoute, or -Service resources. - -{{< warning >}} -Timeouts configured in this way are **incompatible with ServiceProfiles**. If a -[ServiceProfile](../../features/service-profiles/) is defined for a Service, -proxies will use the ServiceProfile timeout configuration and ignore any timeout -annotations. -{{< /warning >}} - -## Timeouts - -Check out the [timeouts section](../books/#timeouts) of the books demo -for a tutorial of how to configure timeouts. diff --git a/linkerd.io/content/2.17/tasks/getting-per-route-metrics.md b/linkerd.io/content/2.17/tasks/getting-per-route-metrics.md deleted file mode 100644 index 5cb7b2c26e..0000000000 --- a/linkerd.io/content/2.17/tasks/getting-per-route-metrics.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: Getting Per-Route Metrics -description: Configure per-route metrics for your application. ---- - -To get per-route metrics, you must create [HTTPRoute] resources. If a route has -a `parent_ref` which points to a **Service** resource, Linkerd will generate -outbound per-route traffic metrics for all HTTP traffic that it sends to that -Service. If a route has a `parent_ref` which points to a **Server** resource, -Linkerd will generate inbound per-route traffic metrcs for all HTTP traffic that -it receives on that Server. Note that an [HTTPRoute] can have multiple -`parent_ref`s which means that the same [HTTPRoute] resource can be used to -describe both outbound and inbound routes. - -For a tutorial that shows off per-route metrics, check out the -[books demo](../books/#service-profiles). - -{{< note >}} -Routes configured in service profiles are different from [HTTPRoute] resources. -If a [ServiceProfile](../../features/service-profiles/) is defined for a -Service, proxies will ignore any [HTTPRoute] for that Service. -{{< /note >}} - -[HTTPRoute]: ../../features/httproute/ diff --git a/linkerd.io/content/2.17/tasks/per-request-policy.md b/linkerd.io/content/2.17/tasks/per-request-policy.md deleted file mode 100644 index 4dfa701414..0000000000 --- a/linkerd.io/content/2.17/tasks/per-request-policy.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -title: Per-Request Policy -description: Using HTTP headers to specify per-request policy ---- - -[Retries](../configuring-retries/) and [timeouts](../configuring-timeouts/) can -be configured by annotating Service, HTTPRoute, or GRPCRoute resources. This -will apply the retry or timeout policy to all requests that are sent to that -service/route. - -Additionally, retry and timeout policy can be configured for individual HTTP -requests by adding special HTTP headers to those requests. - -## Enabling Per-Request Policy - -In order to enable per-request policy, Linkerd must be installed with the -`--set policyController.additionalArgs="--allow-l5d-request-headers"` flag or -the corresponding Helm value. Enabling per-request policy is **not** -recommended if your application accepts requests from untrusted sources (e.g. -if it is an ingress) since this allows untrusted clients to specify Linkerd -policy. - -## Per-Request Policy Headers - -Once per-request policy is enabled, the following HTTP headers can be added to -a request to set or override retry and/or timeout policy for that request: - -+ `l5d-retry-http`: Overrides the `retry.linkerd.io/http` annotation -+ `l5d-retry-grpc`: Overrides the `retry.linkerd.io/grpc` annotation -+ `l5d-retry-limit`: Overrides the `retry.linkerd.io/limit` annotation -+ `l5d-retry-timeout`: Overrides the `retry.linkerd.io/timeout` annotation -+ `l5d-timeout`: Overrides the `timeout.linkerd.io/request` annotation -+ `l5d-response-timeout`: Overrides the `timeout.linkerd.io/response` annotation diff --git a/linkerd.io/content/2.17/tasks/restricting-access.md b/linkerd.io/content/2.17/tasks/restricting-access.md index 699d726c68..3fbb1a03cb 100644 --- a/linkerd.io/content/2.17/tasks/restricting-access.md +++ b/linkerd.io/content/2.17/tasks/restricting-access.md @@ -167,16 +167,18 @@ explicitly create an authorization to allow those probe requests. For more information about adding route-scoped authorizations, see [Configuring Per-Route Policy](../configuring-per-route-policy/). -## Further Considerations - Audit Mode +## Enabling authorization policies in live systems You may have noticed that there was a period of time after we created the `Server` resource but before we created the `ServerAuthorization` where all requests were being rejected. To avoid this situation in live systems, we -recommend that you enable [audit mode](../../features/server-policy/#audit-mode) -in the `Server` resource (via `accessPolicy:audit`) and check the proxy -logs/metrics in the target services to see if traffic would get inadvertently -denied. Afterwards, when you're sure about your policy rules, you can fully -enable them by resetting `accessPolicy` back to `deny`. +recommend that you start with [audit +mode](../../features/server-policy/#audit-mode) enabled on the `Server` +resource. In this mode, traffic that violates the policy will not actually be +denied, and you will be able to check the proxy logs/metrics on the target +services for a complete picture of what would happen when audit mode is +disabled. Once you're sure about your policy rules, you can fully enable them by +removing audit mode to enforce the policies. ## Per-Route Policy diff --git a/linkerd.io/content/2.17/tasks/setting-up-service-profiles.md b/linkerd.io/content/2.17/tasks/setting-up-service-profiles.md index 0950e937c9..a77a903f7b 100644 --- a/linkerd.io/content/2.17/tasks/setting-up-service-profiles.md +++ b/linkerd.io/content/2.17/tasks/setting-up-service-profiles.md @@ -4,6 +4,14 @@ description: Create a service profile that provides more details for Linkerd to on. --- +{{< warning >}} +As of Linkerd 2.16, ServiceProfiles have been fully supplanted by [Gateway API +types](../../features/gateway-api/), including for getting per-route metrics, +specifying timeouts, and specifying retries. Service profiles continue to be +supported for backwards compatibility, but will not receive further feature +development. +{{< /warning >}} + [Service profiles](../../features/service-profiles/) provide Linkerd additional information about a service and how to handle requests for a service. @@ -11,9 +19,7 @@ When an HTTP (not HTTPS) request is received by a Linkerd proxy, the `destination service` of that request is identified. If a service profile for that destination service exists, then that service profile is used to -to provide [per-route metrics](../getting-per-route-metrics/), -[retries](../configuring-retries/) and -[timeouts](../configuring-timeouts/). +to provide per-route metric, retries, and timeouts. The `destination service` for a request is computed by selecting the value of the first header to exist of, `l5d-dst-override`, @@ -21,10 +27,7 @@ the value of the first header to exist of, `l5d-dst-override`, including the colon, is stripped. That value is mapped to the fully qualified DNS name. When the `destination service` matches the name of a service profile in the namespace of the sender or the -receiver, Linkerd will use that to provide [per-route -metrics](../getting-per-route-metrics/), -[retries](../configuring-retries/) and -[timeouts](../configuring-timeouts/). +receiver, Linkerd will use that for additional features. There are times when you may need to define a service profile for a service which resides in a namespace that you do not control. To diff --git a/linkerd.io/content/2.17/tasks/traffic-shifting.md b/linkerd.io/content/2.17/tasks/traffic-shifting.md index 991adcb8a5..0d39b08167 100644 --- a/linkerd.io/content/2.17/tasks/traffic-shifting.md +++ b/linkerd.io/content/2.17/tasks/traffic-shifting.md @@ -5,25 +5,25 @@ description: Dynamically split and shift traffic between backends Traffic splitting and shifting are powerful features that enable operators to dynamically shift traffic to different backend Services. This can be used to -implement A/B experiments, red/green deploys, canary rollouts, -[fault injection](../fault-injection/) and more. +implement A/B experiments, red/green deploys, canary rollouts, [fault +injection](../fault-injection/), and more. -Linkerd supports two different ways to configure traffic shifting: you can -use the [Linkerd SMI extension](../linkerd-smi/) and +Traffic splitting is accomplished with [HTTPRoute] and [GRPCRoute] types. + +{{< note >}} +Earlier versions of Linkerd provided a [TrafficSplit](https://github.com/servicemeshinterface/smi-spec/blob/main/apis/traffic-split/v1alpha2/traffic-split.md/) -resources, or you can use [HTTPRoute](../../features/httproute/) resources which -Linkerd natively supports. While certain integrations such as -[Flagger](../flagger/) rely on the SMI and `TrafficSplit` approach, using -`HTTPRoute` is the preferred method going forward. +resource as part of the the [Linkerd SMI extension](../linkerd-smi/) for traffic +splitting. This approach is still supported but will not recieve further feature +development. +{{< /note >}} {{< docs/production-note >}} ## Prerequisites -To use this guide, you'll need a Kubernetes cluster running: - -- Linkerd and Linkerd-Viz. If you haven't installed these yet, follow the - [Installing Linkerd Guide](../install/). +To use this guide, you'll need a Kubernetes cluster running Linkerd and +Linkerd-Viz. ## Set up the demo @@ -245,3 +245,7 @@ NAME MESHED SUCCESS RPS LATENCY_P50 LATENCY_P95 LATENCY_P99 TC v1 1/1 - - - - - - v2 1/1 100.00% 10.0rps 1ms 1ms 2ms 1 ``` + +[HTTPRoute]: ../../reference/httproute/ +[GRPCRoute]: ../../reference/httproute/ +[Gateway API]: ../../features/gateway-api/