HTTPRoute — the application developer resource

HTTPRoute is the resource that defines the HTTP routing. The application developer creates the HTTPRoute. This lesson walks the HTTPRoute, the parentRefs, and the operational discipline.

The HTTPRoute

The HTTPRoute is the namespaced resource that defines the HTTP routing:

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: billing
  namespace: prod-app
spec:
  parentRefs:
    - name: prod-gateway
      sectionName: https
  hostnames:
    - billing.example.com
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /
          method: GET
      backendRefs:
        - name: billing
          port: 80

The HTTPRoute references the Gateway and defines the routing rules.

flowchart LR
    A[HTTPRoute billing] --> B[parentRefs: prod-gateway]
    A --> C[hostnames: billing.example.com]
    A --> D[rules]
    D --> E[match: path /, method GET]
    D --> F[backendRefs: billing:80]

The HTTPRoute is the application developer’s contract with the cluster’s HTTP gateway.

The parentRefs

The parentRefs field references the Gateway:

parentRefs:
  - name: prod-gateway
    namespace: prod-app
    sectionName: https

The sectionName field is the listener’s name. The HTTPRoute is attached to the listener.

The cross-namespace parentRefs require a ReferenceGrant:

apiVersion: gateway.networking.k8s.io/v1beta1
kind: ReferenceGrant
metadata:
  name: allow-app-routes
  namespace: prod-app
spec:
  from:
    - group: gateway.networking.k8s.io
      kind: HTTPRoute
      namespace: another-app
  to:
    - group: gateway.networking.k8s.io
      kind: Gateway
      name: prod-gateway

The ReferenceGrant is the cluster operator’s approval for the cross-namespace reference.

The rules

The HTTPRoute’s rules define the routing:

rules:
  - matches:
      - path:
          type: PathPrefix
          value: /
      headers:
        - name: X-Custom-Header
          value: custom-value
    backendRefs:
      - name: billing
        port: 80

The match types:

• PathPrefix: matches the URL path prefix.
• Exact: matches the exact URL path.
• RegularExpression: matches a regular expression.

The match fields include path, method, headers, and queryParams.

The filters

The HTTPRoute’s filters transform the request:

rules:
  - matches:
      - path:
          type: PathPrefix
          value: /
    filters:
      - type: RequestRedirect
        requestRedirect:
          scheme: https
          statusCode: 301

The filter types:

• RequestRedirect: redirect the request to a different URL.
• URLRewrite: rewrite the URL before forwarding.
• RequestHeaderModifier: add, set, or remove request headers.
• ResponseHeaderModifier: add, set, or remove response headers.
• RequestMirror: mirror the request to a different backend.

The backendRefs

The backendRefs reference the Service:

backendRefs:
  - name: billing
    port: 80
    weight: 100
  - name: billing-canary
    port: 80
    weight: 0

The weight field is used for traffic splitting. The HTTPRoute can split traffic between multiple backends for canary deployments.

The failure modes

The HTTPRoute’s failure modes:

• Path mismatch: the path type is wrong. The fix is to verify the path type.
• Host mismatch: the host is wrong. The fix is to verify the host.
• Backend not ready: the backend Service has no Pods. The fix is to verify the backend.
• ReferenceGrant missing: the cross-namespace reference is denied. The fix is to add the ReferenceGrant.
• Filter misconfigured: the filter is wrong. The fix is to verify the filter.

The operational discipline

The HTTPRoute’s operational discipline:

• Document the HTTPRoute. The HTTPRoute is the cluster’s HTTP routing configuration.
• Audit the HTTPRoute at every change. The HTTPRoute is critical configuration.
• Test the HTTPRoute in staging. The HTTPRoute must work for the workload.
• Monitor the HTTPRoute’s status. The status is the leading indicator.
• Plan the HTTPRoute’s evolution. The HTTPRoute can be replaced with Gateway API.
• Document the troubleshooting. The troubleshooting is the cluster’s operational reference.

Quiz

Production discipline

• The HTTPRoute is the application developer’s contract. The application developer must understand the HTTPRoute’s role.
• Document the HTTPRoute. The HTTPRoute is the cluster’s HTTP routing configuration.
• Audit the HTTPRoute at every change. The HTTPRoute is critical configuration.
• Test the HTTPRoute in staging. The HTTPRoute must work for the workload.
• Monitor the HTTPRoute’s status. The status is the leading indicator.
• Plan the HTTPRoute’s evolution. The HTTPRoute can be replaced with Gateway API.
• Document the troubleshooting. The troubleshooting is the cluster’s operational reference.
• Train the application developers on the HTTPRoute. The HTTPRoute is the application developer’s contract.
• Use a CI check for the HTTPRoute. The CI check can catch the HTTPRoute error at every change.