HTTP routing

The HTTPRoute resource allows you to match on HTTP traffic and direct it to Kubernetes backends. This guide shows how the HTTPRoute matches traffic on host, header, and path fields and forwards it to different Kubernetes Services.

The following diagram describes a required traffic flow across three different Services:

  • Traffic to foo.example.com/login is forwarded to foo-svc
  • Traffic to bar.example.com/* with a env: canary header is forwarded to bar-svc-canary
  • Traffic to bar.example.com/* without the header is forwarded to bar-svc

HTTP Routing

The dotted lines show the Gateway resources deployed to configure this routing behavior. There are two HTTPRoute resources that create routing rules on the same prod-web Gateway. This illustrates how more than one Route can bind to a Gateway which allows Routes to merge on a Gateway as long as they don’t conflict. For more information on Route merging, refer to the HTTPRoute documentation.

In order to receive traffic from a Gateway an HTTPRoute resource must be configured with ParentRefs which reference the parent gateway(s) that it should be attached to. The following example shows how the combination of Gateway and HTTPRoute would be configured to serve HTTP traffic:

  1. apiVersion: gateway.networking.k8s.io/v1
  2. kind: Gateway
  3. metadata:
  4.   name: example-gateway
  5. spec:
  6.   gatewayClassName: example-gateway-class
  7.   listeners:
  8.   - name: http
  9.     protocol: HTTP
  10.     port: 80
  11. ---
  12. apiVersion: gateway.networking.k8s.io/v1
  13. kind: HTTPRoute
  14. metadata:
  15.   name: example-route
  16. spec:
  17.   parentRefs:
  18.   - name: example-gateway
  19.   hostnames:
  20.   - "example.com"
  21.   rules:
  22.   - backendRefs:
  23.     - name: example-svc
  24.       port: 80

An HTTPRoute can match against a single set of hostnames. These hostnames are matched before any other matching within the HTTPRoute takes place. Since foo.example.com and bar.example.com are separate hosts with different routing requirements, each is deployed as its own HTTPRoute - foo-route and bar-route.

The following foo-route will match any traffic for foo.example.com and apply its routing rules to forward the traffic to the correct backend. Since there is only one match specified, only foo.example.com/login/* traffic will be forwarded. Traffic to any other paths that do not begin with /login will not be matched by this Route.

  1. apiVersion: gateway.networking.k8s.io/v1
  2. kind: HTTPRoute
  3. metadata:
  4.   name: foo-route
  5. spec:
  6.   parentRefs:
  7.   - name: example-gateway
  8.   hostnames:
  9.   - "foo.example.com"
  10.   rules:
  11.   - matches:
  12.     - path:
  13.         type: PathPrefix
  14.         value: /login
  15.     backendRefs:
  16.     - name: foo-svc
  17.       port: 8080

Similarly, the bar-route HTTPRoute matches traffic for bar.example.com. All traffic for this hostname will be evaluated against the routing rules. The most specific match will take precedence which means that any traffic with the env: canary header will be forwarded to bar-svc-canary and if the header is missing or not canary then it’ll be forwarded to bar-svc.

  1. apiVersion: gateway.networking.k8s.io/v1
  2. kind: HTTPRoute
  3. metadata:
  4.   name: bar-route
  5. spec:
  6.   parentRefs:
  7.   - name: example-gateway
  8.   hostnames:
  9.   - "bar.example.com"
  10.   rules:
  11.   - matches:
  12.     - headers:
  13.       - type: Exact
  14.         name: env
  15.         value: canary
  16.     backendRefs:
  17.     - name: bar-svc-canary
  18.       port: 8080
  19.   - backendRefs:
  20.     - name: bar-svc
  21.       port: 8080