> ## Documentation Index
> Fetch the complete documentation index at: https://notes.kodekloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# HTTPRoute Structure and Matching

> Explains Kubernetes Gateway API HTTPRoute resource, its fields, matching rules, and routing backends

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:

1. A GatewayClass (defines controller behavior).
2. A Gateway (instantiated per cluster/namespace).
3. 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

```yaml theme={null}
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`<br />`  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`<br />`  port: 80` |
| `matches.path` | Controls how the request path is evaluated (see match types). | `type: PathPrefix`<br />`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.

<Callout icon="lightbulb" color="#1CB2FE">
  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.
</Callout>

Further reading

* Gateway API docs: [https://gateway-api.sigs.k8s.io/](https://gateway-api.sigs.k8s.io/)
* Kubernetes networking overview: [https://kubernetes.io/docs/concepts/services-networking/](https://kubernetes.io/docs/concepts/services-networking/)

We'll cover advanced traffic management — such as regex matches, weighted backends, and header/query-param based routing — in a later lesson.

That's it for this lesson. I hope you enjoyed it.

<CardGroup>
  <Card title="Watch Video" icon="video" cta="Learn more" href="https://learn.kodekloud.com/user/courses/gateway-api-with-nginx-fabric-gateway/module/4c755491-684e-4113-bddb-c202ad926bff/lesson/5137f925-442d-4ed5-afc4-ca720665d460" />
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.