HTTPRoute
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. 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.
HTTPRoute Spec
An HTTPRoute spec may contain the following top level fields:
field | value |
---|---|
parentRefs | A set of ParentReferences which indicate which [Server]s or Services this HTTPRoute attaches to. |
hostnames | A set of hostnames that should match against the HTTP Host header. |
rules | An array of HTTPRouteRules. |
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.
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, 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.
field | value |
---|---|
group | The group of the referent. This must either be “policy.linkerd.io” (for Server) or “core” (for Service). |
kind | The kind of the referent. This must be either “Server” or “Service”. |
port | The targeted port number, when attaching to Services. |
namespace | The namespace of the referent. When unspecified (or empty string), this refers to the local namespace of the Route. |
name | The name of the referent. |
httpRouteRule
HTTPRouteRule defines semantics for matching an HTTP request based on conditions (matches) and processing it (filters).
field | value |
---|---|
matches | A list of httpRouteMatches. Each match is independent, i.e. this rule will be matched if any one of the matches is satisfied. |
filters | A list of httpRouteFilters which will be applied to each request which matches this rule. |
backendRefs | An array of HTTPBackendRefs to declare where the traffic should be routed to (only allowed with Service parentRefs). |
timeouts | An optional httpRouteTimeouts object which configures timeouts for requests matching this rule. |
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.
field | value |
---|---|
path | An httpPathMatch. If this field is not specified, a default prefix match on the “/” path is provided. |
headers | A list of httpHeaderMatches. Multiple match values are ANDed together. |
queryParams | A list of httpQueryParamMatches. Multiple match values are ANDed together. |
method | When specified, this route will be matched only if the request has the specified method. |
httpPathMatch
HTTPPathMatch
describes how to select a HTTP route by matching the HTTP
request path.
field | value |
---|---|
type | How to match against the path Value. One of: Exact, PathPrefix, RegularExpression. If this field is not specified, a default of “PathPrefix” is provided. |
value | The HTTP path to match against. |
httpHeaderMatch
HTTPHeaderMatch
describes how to select a HTTP route by matching HTTP request
headers.
field | value |
---|---|
type | How to match against the value of the header. One of: Exact, RegularExpression. If this field is not specified, a default of “Exact” is provided. |
name | The HTTP Header to be matched against. Name matching MUST be case insensitive. |
value | Value of HTTP Header to be matched. |
httpQueryParamMatch
HTTPQueryParamMatch
describes how to select a HTTP route by matching HTTP
query parameters.
field | value |
---|---|
type | How to match against the value of the query parameter. One of: Exact, RegularExpression. If this field is not specified, a default of “Exact” is provided. |
name | The HTTP query param to be matched. This must be an exact string match. |
value | Value of HTTP query param to be matched. |
httpRouteFilter
HTTPRouteFilter defines processing steps that must be completed during the request or response lifecycle.
field | value |
---|---|
type | One of: RequestHeaderModifier, ResponseHeaderModifier, or RequestRedirect. |
requestHeaderModifier | An httpHeaderFilter which modifies request headers. |
responseHeaderModifier | An httpHeaderFilter which modifies response headers. |
requestRedirect | An httpRequestRedirectFilter. |
httpHeaderFilter
A filter which modifies HTTP request or response headers.
field | value |
---|---|
set | A list of httpHeaders to overwrite on the request or response. |
add | A list of httpHeaders to add on to the request or response, appending to any existing value. |
remove | A list of header names to remove from the request or response. |
httpHeader
HTTPHeader
represents an HTTP Header name and value as defined by RFC 7230.
field | value |
---|---|
name | Name of the HTTP Header to be matched. Name matching MUST be case insensitive. |
value | Value of HTTP Header to be matched. |
httpRequestRedirectFilter
HTTPRequestRedirect
defines a filter that redirects a request.
field | value |
---|---|
scheme | The scheme to be used in the value of the Location header in the response. When empty, the scheme of the request is used. |
hostname | The hostname to be used in the value of the Location header in the response. When empty, the hostname of the request is used. |
path | An httpPathModfier which modifies the path of the incoming request and uses the modified path in the Location header. |
port | The port to be used in the value of the Location header in the response. When empty, port (if specified) of the request is used. |
statusCode | The HTTP status code to be used in response. |
httpPathModfier
HTTPPathModifier
defines configuration for path modifiers.
field | value |
---|---|
type | One of: ReplaceFullPath, ReplacePrefixMatch. |
replaceFullPath | The value with which to replace the full path of a request during a rewrite or redirect. |
replacePrefixMatch | The value with which to replace the prefix match of a request during a rewrite or redirect. |
httpBackendRef
HTTPBackendRef
defines the list of objects where matching requests should be
sent to. Only allowed when a route has Service parentRefs.
field | value |
---|---|
name | Name of service for this backend. |
port | Destination port number for this backend. |
namespace | Namespace of service for this backend. |
weight | Proportion of requests sent to this backend. |
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.
field | value |
---|---|
request | Specifies the duration for processing an HTTP client request after which the proxy will time out if unable to send a response. When this field is unspecified or 0, the proxy will not enforce request timeouts. |
backendRequest | Specifies a timeout for an individual request from the proxy to a backend service. This covers the time from when the request first starts being sent from the proxy to when the response has been received from the backend. When this field is unspecified or 0, the proxy will not enforce a backend request timeout, but may still enforce the request timeout, if one is configured. |
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