HTTPRoutes

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 for details.

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, 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.

Warning

Outbound HTTPRoutes and ServiceProfiles 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.

Learn More

To get started with HTTPRoutes, you can:

Configure fault injection using an outbound HTTPRoute.
Configure timeouts using an outbound HTTPRoute.
Configure dynamic request routing using an outbound HTTPRoute.
Configure per-route authorization policy using an inbound HTTPRoute.
See the reference documentation for a complete description of the HTTPRoute resource.