Configure HTTP traffic steering with Gateway API HTTPRoute

Overview

F5 BIG-IP Next for Kubernetes (BNK) supports traffic steering through the HTTPRoute custom resource definition (CRD), part of the Gateway API standard (version 1.4). HTTPRoute lets you route HTTP requests based on specific criteria — such as hostnames, paths, headers, methods, and query parameters — without relying on iRules.

This feature works with Gateway resources to control how HTTP traffic moves across your Kubernetes cluster. It supports both HTTP/1.x and HTTP/2.0 traffic.

Before you begin

Make sure you have the following in place before you configure HTTPRoute resources:

  • A working BIG-IP Next for Kubernetes (BNK) deployment

  • A configured Gateway resource with at least one HTTP listener

  • Access to kubectl with permissions to create HTTPRoute resources

  • Familiarity with Kubernetes custom resource definitions (CRDs)

Key concepts

What is an HTTPRoute?

An HTTPRoute is a Kubernetes CRD that defines how to route HTTP traffic. It works with a Gateway resource to manage incoming requests. You define matching criteria that determine which requests the route handles, then specify actions to take on those requests.

Traffic matching criteria

You can steer traffic based on one or more of the following criteria:

Criteria

Description

Hostname matching

Route traffic based on the requested hostname, including wildcard listeners

Path matching

Route traffic using exact path matches or prefix-based matching

HTTP method matching

Route traffic based on the HTTP method (GET, POST, PUT, DELETE, PATCH, and others)

Query parameter matching

Route traffic based on exact query parameter values

Header matching

Route traffic based on exact HTTP header values

You can combine multiple criteria to create precise routing rules.

Traffic steering actions

After a request matches your criteria, you can apply one or more of the following actions:

Action

Description

URL redirect

Redirect requests to a different scheme, host, port, or path

Path rewrite

Rewrite the request path using full replacement or prefix matching

Host rewrite

Rewrite the host header to a different value

Header modification

Add, set, or remove request and response headers

Weighted load balancing

Distribute traffic across multiple backends based on assigned weights

Supported redirect status codes

When you configure URL redirects, you can use the following HTTP status codes:

Status code

Description

301

Moved permanently (default)

302

Found

Configure an HTTPRoute

  1. Create an HTTPRoute resource that specifies how to match incoming traffic. The following example matches requests to example.com on the /app path:

    apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: example-route
spec:
  parentRefs:
    - name: my-gateway
  hostnames:
    - "example.com"
  rules:
    - matches:
        - path:
            type: Exact
            value: /app
      backendRefs:
        - name: my-backend
          port: 8080

  2. Add a redirect filter to your routing rules. The following example redirects HTTP traffic to HTTPS using a 301 status code:

    apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: redirect-route
spec:
  parentRefs:
    - name: my-gateway
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /
      filters:
        - type: RequestRedirect
          requestRedirect:
            scheme: https
            statusCode: 301

    You can also combine redirect criteria. For example, you can redirect to a different hostname and port at the same time.

  3. Use path rewrite filters to modify the request path before it reaches the backend. You can replace the full path or replace a prefix:

    apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: rewrite-route
spec:
  parentRefs:
    - name: my-gateway
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /old-path
      filters:
        - type: URLRewrite
          urlRewrite:
            path:
              type: ReplacePrefixMatch
              replacePrefixMatch: /new-path
      backendRefs:
        - name: my-backend
          port: 8080

  4. Use a host rewrite filter to change the host header before the request reaches the backend:

    apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: host-rewrite-route
spec:
  parentRefs:
    - name: my-gateway
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /
      filters:
        - type: URLRewrite
          urlRewrite:
            hostname: new-hostname.example.com
      backendRefs:
        - name: my-backend
          port: 8080

  5. You can add, set, or remove headers on requests and responses. Header modifications can apply at the route level or for specific backends.

    Route-level request header modification:

    apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: header-mod-route
spec:
  parentRefs:
    - name: my-gateway
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /api
      filters:
        - type: RequestHeaderModifier
          requestHeaderModifier:
            add:
              - name: X-Custom-Header
                value: "my-value"
            set:
              - name: X-Existing-Header
                value: "overwritten-value"
            remove:
              - X-Remove-This
      backendRefs:
        - name: my-backend
          port: 8080

    Response header modification:

    filters:
  - type: ResponseHeaderModifier
    responseHeaderModifier:
      add:
        - name: X-Response-Header
          value: "response-value"
      remove:
        - X-Remove-Response-Header

    Note

    You can refer Gateway API GitHub repository for verified examples.

  6. To distribute traffic across multiple backends, assign weights to each backend reference. The following example sends 80% of traffic to backend-v1 and 20% to backend-v2:

    apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: weighted-route
spec:
  parentRefs:
    - name: my-gateway
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /
      backendRefs:
        - name: backend-v1
          port: 8080
          weight: 80
        - name: backend-v2
          port: 8080
          weight: 20

  7. After you apply your HTTPRoute resource, verify that the Gateway accepted it:

    $ kubectl get httproute example-route -o yaml

    Check the status section of the output to confirm that the route is accepted and bound to your Gateway.

Sample stat table and description

kubectl exec -it f5-tmm-fgdc2 -c debug -- tmctl -d blade policy_stat -w 300
policy_name                                                      rule_name                                     action_id obj_name                                    invoked succeeded
---------------------------------------------------------------- --------------------------------------------- --------- ------------------------------------------- ------- ---------
spk-app-1-my-gateway-11.11.11.20-http-80-compiled-traffic-policy spk-app-1-example-route-r0m0-host-example.com         0 spk-app-1-my-gateway-11.11.11.20-http-80-vs       0         0
spk-app-1-my-gateway-11.11.11.20-http-80-compiled-traffic-policy no-match-rule                                         0 spk-app-1-my-gateway-11.11.11.20-http-80-vs       0         0

Traffic Policy Name Structure

Example: spk-app-1-my-gateway-11.11.11.20-http-80-compiled-traffic-policy

Component

Description

spk-app-1

Namespace of the parent Gateway

my-gateway

Name of the parent Gateway

11.11.11.20

IP address of the Gateway

http-80

Listener protocol and port on the Gateway

compiled-traffic-policy

Indicates a compiled traffic policy generated for the Gateway

Rule Name Structure

Example: spk-app-1-example-route-r0m0-host-example.com

Component

Description

spk-app-1

Namespace of the route

example-route

Name of the route

r0

Rule index within the route (r0 = first rule, r1 = second rule, and so on)

m0

Match index within the specified rule

host-example.com

Hostname (example.com) specified in the route

Note

Rule-name in the stat table is limited to 256 characters; longer names are truncated.

Default Rule Behaviour

Item

Description

no-match-rule

A default rule is created for each policy

Match precedence

Lowest precedence

Behaviour

Matched when no other policy rules are matched

Response

TMM returns HTTP status code 404

Policy Statistics and Metadata

Field

Description

action_id

Indices of actions associated with a rule

invoked

Number of HTTP requests that matched a specific rule in the policy

succeeded

Number of successfully processed HTTP requests for a rule that were invoked

Matching precedence

When multiple HTTPRoute rules could match a request, BNK implementation follows the precedence rules defined in the Gateway API. Keep these rules in mind:

  • More specific matches take priority over less specific matches.

  • Exact path matches take priority over prefix matches.

  • Longer path prefixes take priority over shorter ones.

  • When multiple routes are attached to a listener and each route has multiple rules, BNK sorts the rules from all routes and evaluates them in order.

  • If a redirect is configured, the system returns the redirect response code instead of a 500 Internal Server Error.

    • Redirect response code is returned when no backend is configured and a redirect filter is present in the route.

    • 500 Internal Server Error is returned when no backend is configured and no redirect filter is present in the route.

VIP behavior when backends are unavailable

BNK advertises the virtual IP (VIP) and returns a 500 error under the following conditions:

  • A route is attached to a listener, but no backend is configured.

  • A route is attached to a listener with a backend in a different namespace, but a ReferenceGrant is not configured to allow cross-namespace access.

  • A route is attached to a listener with a backend, but no active pool members are available.

In previous versions, BNK removed the virtual server configuration and withdrew the VIP advertisement when no active pool members were available. This behavior has changed to maintain conformance with the Gateway API specification.

HTTP/2 support

BNK supports HTTP/2 cleartext (h2c) protocol through HTTPRoute. You can configure backend protocol support to route HTTP/2 traffic to your services.