HTTP query parameter matching

Extended Support Feature: HTTPRouteQueryParamMatching
This feature is part of extended support. For more information on support levels, refer to our conformance guide.
The HTTPRoute resource can be used to match requests based on query parameters. This guide shows how to use this functionality.

Matching requests based on a single query parameter

The following HTTPRoute splits traffic between two backends based on the value of the animal query parameter:

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: query-param-matching
  namespace: gateway-conformance-infra
spec:
  parentRefs:
  - name: same-namespace
  rules:
  - matches:
    - queryParams:
      - name: animal
        value: whale
    backendRefs:
    - name: infra-backend-v1
      port: 8080
  - matches:
    - queryParams:
      - name: animal
        value: dolphin
    backendRefs:
    - name: infra-backend-v2
      port: 8080
  • A request to / with the query parameter animal=whale will be routed to infra-backend-v1.
  • A request to / with the query parameter animal=dolphin will be routed to infra-backend-v2.

Matching requests based on multiple query parameters

A rule can also match on multiple query parameters. The following rule routes traffic to infra-backend-v3 if the query parameters animal=dolphin AND color=blue are present:

  - matches:
    - queryParams:
      - name: animal
        value: dolphin
      - name: color
        value: blue
    backendRefs:
    - name: infra-backend-v3
      port: 8080

ORing matches

If a rule has multiple matches, a request will be routed if it satisfies any of them. The following rule routes traffic to infra-backend-v3 if:

  • The query parameters animal=dolphin AND color=blue are present.
  • OR the query parameter ANIMAL=Whale is present.
  - matches:
    - queryParams:
      - name: animal
        value: dolphin
      - name: color
        value: blue
    - queryParams:
      - name: ANIMAL
        value: Whale
    backendRefs:
    - name: infra-backend-v3
      port: 8080

Combining with other match types

Query parameter matching can be combined with other match types like path and header matching. The following rules demonstrate this:

  - matches:
    - path:
        type: PathPrefix
        value: /path1
      queryParams:
      - name: animal
        value: whale
    backendRefs:
    - name: infra-backend-v1
      port: 8080
  - matches:
    - headers:
      - name: version
        value: one
      queryParams:
      - name: animal
        value: whale
    backendRefs:
    - name: infra-backend-v2
      port: 8080
  - matches:
    - path:
        type: PathPrefix
        value: /path2
      headers:
      - name: version
        value: two
      queryParams:
      - name: animal
        value: whale
    backendRefs:
    - name: infra-backend-v3
      port: 8080