HTTPRoute

An HTTPRoute is a Gateway API resource that tells a Gateway where to send HTTP requests. It connects one or more parent Gateways to backend Services and can select requests by hostname and other HTTP properties. Unlike an Ingress, a Gateway keeps routing rules in separate Route objects; an application developer can manage a route while a cluster administrator manages the Gateway. section 13.3 section 13.1.1

apiVersion: gateway.networking.k8s.io/v1      #1
kind: HTTPRoute                       #1       
metadata:
  name: kiada     #2
spec:
  parentRefs:            #3
  - name: kiada          #3
  hostnames:                #4
  - kiada.example.com       #4
  rules:                  #5
  - backendRefs:          #5
    - name: kiada         #5
      port: 80            #5

Start with this small manifest: parentRefs names the Gateway, hostnames selects the requested host, and the rule’s backendRefs names the Service and port. section 13.3.1

Apply the manifest with `kubectl apply -f httproute.kiada.yaml`, then check it with `kubectl get httproutes`. To test without changing DNS, use `curl --resolve kiada.example.com:80:172.18.255.200 http://kiada.example.com`, replacing the address with your Gateway’s IP. A browser instead needs the hostname to resolve to that IP. The example uses `gateway.networking.k8s.io/v1`; the Gateway, route, and Service need not share a name. section 13.3.1

Add rules when the simple hostname-to-Service route is not enough:

• Set multiple backendRefs and weights to divide requests between Services. Weights 9 and 1 send approximately 90% to one backend and 10% to another; omitted weights split traffic evenly. section 13.3.2
• Use matches for HTTP method, headers, path, or query parameters. For example, send POST requests to a new Service and other requests to a catch-all rule’s stable Service. section 13.3.3
• Use filters to change request or response headers, rewrite a URL, redirect a client, or mirror a request to another Service. section 13.3.4

A route must also attach successfully. A Gateway listener’s status reports its supported route kinds and attachedRoutes count; a listener with no routes can return 404. Check the HTTPRoute’s parent status too: Accepted reports whether the parent accepted it, while ResolvedRefs reports whether its references could be resolved. section 13.2.3 section 13.3.1

Routes can cross namespace boundaries only with permission. To reference a Gateway in another namespace, set its namespace in parentRefs and ensure the listener’s allowedRoutes permits that route’s namespace. To reference a Service in another namespace, set its namespace in backendRefs and create a ReferenceGrant in the Service’s namespace. A missing grant makes ResolvedRefs false. section 13.6.1 section 13.6.2

An HTTPRoute also works behind a Gateway that terminates HTTPS: the Gateway decrypts the request before routing it to the HTTP backend. In this configuration, the Gateway-to-backend request is unencrypted. section 13.4.1

Do not confuse this Gateway API resource with a Citrix ingress controller’s separate `citrix.com` HTTPRoute custom object. That object is referenced as an Ingress resource backend, and its routing-rule format is not specified here. section 12.6.1