HTTPRoute Structure and Matching

This lesson explains the HTTPRoute resource from the Kubernetes Gateway API and how it declares how your application is exposed. Typically you create three resources in this order before an HTTPRoute becomes active:

A GatewayClass (defines controller behavior).
A Gateway (instantiated per cluster/namespace).
An HTTPRoute that attaches to the Gateway and defines hostnames, matches, and backends.

An HTTPRoute:

References the Gateway (and optionally a specific listener) that should parent the route.
Declares which hostnames (FQDNs) it should serve.
Defines one or more rules that match incoming requests and forward them to Kubernetes Services via backendRefs.

Common HTTPRoute manifest

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: tea-route
  namespace: tea-ns
spec:
  parentRefs:
  - name: gateway
    namespace: default
  hostnames:
  - "tea.example.com"
  rules:
  - backendRefs:
    - name: tea
      port: 80
    matches:
    - path:
        type: PathPrefix
        value: /tea

Quick reference: main spec sections

Field	Purpose	Example
`spec.parentRefs`	Identifies the Gateway resource that should accept (parent) this route. When the Gateway lives in a different namespace, include `namespace`.	`- name: gateway` `namespace: default`
`spec.hostnames`	One or more DNS names the route will accept (FQDNs).	`- "tea.example.com"`
`spec.rules`	Each rule contains one or more `matches` and one or more `backendRefs`.	See manifest above
`backendRefs`	References Kubernetes Services (and port) that should receive traffic for matched requests.	`- name: tea` `port: 80`
`matches.path`	Controls how the request path is evaluated (see match types).	`type: PathPrefix` `value: /tea`

How matches.path behaves

PathPrefix — routes when the request path starts with the prefix. Example: /tea matches /tea, /tea/green, /tea/info.
Exact — routes only when the path equals the provided value exactly (no trailing segments).
RegularExpression — use a regex for complex matching and capture groups.
queryParams — match on specific query parameter names/values (useful for canary or blue/green routing).

Match types table

Match type	Description	Typical use case
`PathPrefix`	Matches requests whose path begins with the specified prefix.	Route an entire subtree, e.g. `/api/v1`
`Exact`	Matches only when the full path exactly matches the value.	Static assets or exact endpoint routing
`RegularExpression`	Uses a regex to match and optionally capture parts of the path.	Complex routing rules, parameter extraction
`queryParams`	Matches based on query parameter presence or value.	Versioning or A/B tests using `?version=green`

Best practices and tips

Use PathPrefix for grouping related endpoints (APIs, microservice endpoints). Use Exact for endpoint-specific rules where trailing segments would break behavior.
Combine path matches with header or query-parameter matches for advanced traffic shaping (covered in a later lesson).
Prefer explicit namespace in parentRefs when the Gateway is not in the same namespace as the HTTPRoute to avoid lookup failures.

When the Gateway and the HTTPRoute live in different namespaces, be sure to set the namespace field inside the parentRefs item so the controller can resolve the parent Gateway.

Introduction & Why Gateway API

Core Gateway API Resources

Advanced Traffic Management

TLS and Cross-Namespace Security

Troubleshooting and Best Practices

HTTPRoute Structure and Matching

Watch Video