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.

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

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

An HTTPRoute spec may contain the following top level fields:

parentReference

A reference to the parent resource this HTTPRoute is a part of.

HTTPRoutes can be attached to a Server to allow defining an authorization policy 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.

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, a HTTPRoute with a parentRef that references a Service in the same namespace as the HTTPRoute is referred to as a producer route, while an HTTPRoute with a parentRef referencing a Service in a different namespace is referred to as a consumer route. A producer route will apply to requests originating from clients in any namespace. On the other hand, a consumer route is scoped to apply only to traffic originating in the HTTPRoute’s namespace. See the “Namespace boundaries” section in GEP-1426 for details on producer and consumer routes.

httpRouteRule

HTTPRouteRule defines semantics for matching an HTTP request based on conditions (matches) and processing it (filters).

httpRouteMatch

HTTPRouteMatch defines the predicate used to match requests to a given action. Multiple match types are ANDed together, i.e. the match will evaluate to true only if all conditions are satisfied.

httpPathMatch

HTTPPathMatch describes how to select a HTTP route by matching the HTTP request path.

httpHeaderMatch

HTTPHeaderMatch describes how to select a HTTP route by matching HTTP request headers.

httpQueryParamMatch

HTTPQueryParamMatch describes how to select a HTTP route by matching HTTP query parameters.

httpRouteFilter

HTTPRouteFilter defines processing steps that must be completed during the request or response lifecycle.

httpHeaderFilter

A filter which modifies HTTP request or response headers.

httpHeader

HTTPHeader represents an HTTP Header name and value as defined by RFC 7230.

httpRequestRedirectFilter

HTTPRequestRedirect defines a filter that redirects a request.

httpPathModfier

HTTPPathModifier defines configuration for path modifiers.

httpBackendRef

HTTPBackendRef defines the list of objects where matching requests should be sent to. Only allowed when a route has Service parentRefs.

httpRouteTimeouts

HTTPRouteTimeouts defines the timeouts that can be configured for an HTTP request.

Linkerd implements HTTPRoute timeouts as described in GEP-1742. Timeout durations are specified as strings using the Gateway API duration format specified by GEP-2257 (e.g. 1h/1m/1s/1ms), and MUST be at least 1ms. A timeout field with duration 0 disables that timeout.

If retries are enabled, a request received by the proxy may be retried by sending it to a different backend. In this case, a new backendRequest timeout will be started for each retry request, but each retry request will count against the overall request timeout.

HTTPRoute Examples

An HTTPRoute attached to a Server resource which matches GETs to /authors.json or /authors/*:

apiVersion: policy.linkerd.io/v1beta2
kind: HTTPRoute
metadata:
  name: authors-get-route
  namespace: booksapp
spec:
  parentRefs:
    - name: authors-server
      kind: Server
      group: policy.linkerd.io
  rules:
    - matches:
      - path:
          value: "/authors.json"
        method: GET
      - path:
          value: "/authors/"
          type: "PathPrefix"
        method: GET

An HTTPRoute attached to a Service to perform header-based routing. If there’s a x-faces-user: testuser header in the request, the request is routed to the smiley2 backend Service. Otherwise, the request is routed to the smiley backend Service.

apiVersion: policy.linkerd.io/v1beta2
kind: HTTPRoute
metadata:
  name: smiley-a-b
  namespace: faces
spec:
  parentRefs:
    - name: smiley
      kind: Service
      group: core
      port: 80
  rules:
    - matches:
      - headers:
        - name: "x-faces-user"
          value: "testuser"
      backendRefs:
        - name: smiley2
          port: 80
    - backendRefs:
      - name: smiley
        port: 80