For the complete documentation index, see llms.txt. Markdown versions of all docs pages are available by appending .md to any docs URL.

Native Gateway API policies

Learn how Kubernetes Gateway API policies, such as request timeouts, are inherited and overridden along the route delegation chain.

Learn how policy inheritance and overrides work for Kubernetes Gateway API-native policies in a route delegation setup.

About policy inheritance

Kubernetes Gateway API policies that can be defined on an HTTPRoute, such as timeouts and retries, are inherited as follows:

• Policies that are defined on a parent HTTPRoute are automatically inherited by all child or grandchild HTTPRoutes.
• If the child or grandchild HTTPRoute defines a policy, this policy takes precedence and overrides the policy that is set on the parent.

Configuration overview

In this guide, you set up a route delegation chain where a child HTTPRoute inherits or overrides a timeout that is set on the parent HTTPRoute. The child routes use a URLRewrite filter to expose httpbin’s /delay/N endpoint, which holds a request open for N seconds. You verify the inherited or overridden timeout by sending a request that takes longer than the timeout to complete.

The following image illustrates the route delegation hierarchy and policy inheritance:

parent HTTPRoute:

• Delegates traffic as follows:
  • /anything/team1 is delegated to the child HTTPRoute child-team1 in namespace team1. The rule defines a 1s request timeout.
  • /anything/team2 is delegated to the child HTTPRoute child-team2 in namespace team2. The rule also defines a 1s request timeout.

child-team1 HTTPRoute:

• Matches incoming traffic for the /anything/team1/delay prefix path. Rewrites the prefix to /delay and routes traffic to the httpbin app in the team1 namespace.
• Does not define a timeout, so it inherits the 1s timeout from the parent’s /anything/team1 rule.

child-team2 HTTPRoute:

• Matches incoming traffic for the /anything/team2/delay prefix path. Rewrites the prefix to /delay and routes traffic to the httpbin app in the team2 namespace.
• Defines a custom 5s request timeout that overrides the 1s timeout from the parent’s /anything/team2 rule.

Before you begin

1. Follow the Get started guide to install agentgateway.

2. Follow the Sample app guide to create the agentgateway-proxy Gateway with an HTTP listener.

3. Get the external address of the agentgateway proxy and save it in an environment variable.

   Cloud Provider LoadBalancerPort-forward for local testing

   export INGRESS_GW_ADDRESS=$(kubectl get svc -n agentgateway-system agentgateway-proxy -o jsonpath="{.status.loadBalancer.ingress[0]['hostname','ip']}")
   echo $INGRESS_GW_ADDRESS

   kubectl port-forward deployment/agentgateway-proxy -n agentgateway-system 8080:80

4. Create the namespaces for team1 and team2.

   kubectl create namespace team1
   kubectl create namespace team2

5. Deploy the httpbin app into both namespaces. The httpbin app exposes endpoints such as /anything/..., /headers, and /delay/N that are useful for verifying routing and policy behavior.

   curl -sL https://raw.githubusercontent.com/kgateway-dev/kgateway/main/examples/httpbin.yaml \
     | awk 'BEGIN{skip=0} /^kind: Namespace$/{skip=1} skip==0{print} /^---$/{skip=0}' \
     | sed 's/namespace: httpbin/namespace: team1/g' \
     | kubectl apply -f -
   
   curl -sL https://raw.githubusercontent.com/kgateway-dev/kgateway/main/examples/httpbin.yaml \
     | awk 'BEGIN{skip=0} /^kind: Namespace$/{skip=1} skip==0{print} /^---$/{skip=0}' \
     | sed 's/namespace: httpbin/namespace: team2/g' \
     | kubectl apply -f -

6. Verify that the httpbin apps are up and running.

   kubectl get pods -n team1
   kubectl get pods -n team2

   Example output:

   NAME                       READY   STATUS    RESTARTS   AGE
   httpbin-6bc5b79755-xlvjf   3/3     Running   0          7s
   NAME                       READY   STATUS    RESTARTS   AGE
   httpbin-6bc5b79755-twxq9   3/3     Running   0          6s

Setup

1. Create the parent HTTPRoute that matches incoming traffic on the delegation.example domain. Each rule defines a 1s request timeout.

   kubectl apply -f- <<EOF
   apiVersion: gateway.networking.k8s.io/v1
   kind: HTTPRoute
   metadata:
     name: parent
     namespace: agentgateway-system
   spec:
     parentRefs:
     - name: agentgateway-proxy
     hostnames:
     - "delegation.example"
     rules:
     - matches:
       - path:
           type: PathPrefix
           value: /anything/team1
       backendRefs:
       - group: gateway.networking.k8s.io
         kind: HTTPRoute
         name: child-team1
         namespace: team1
       timeouts:
         request: 1s
     - matches:
       - path:
           type: PathPrefix
           value: /anything/team2
       backendRefs:
       - group: gateway.networking.k8s.io
         kind: HTTPRoute
         name: child-team2
         namespace: team2
       timeouts:
         request: 1s
   EOF

2. Create the child-team1 HTTPRoute. The HTTPRoute matches /anything/team1/delay and uses a URLRewrite filter to forward traffic to httpbin’s /delay endpoint. The route does not define a timeout, so the 1s timeout from the parent is inherited.

   kubectl apply -f- <<EOF
   apiVersion: gateway.networking.k8s.io/v1
   kind: HTTPRoute
   metadata:
     name: child-team1
     namespace: team1
   spec:
     rules:
     - matches:
       - path:
           type: PathPrefix
           value: /anything/team1/delay
       filters:
       - type: URLRewrite
         urlRewrite:
           path:
             type: ReplacePrefixMatch
             replacePrefixMatch: /delay
       backendRefs:
       - name: httpbin
         port: 8000
   EOF

3. Create the child-team2 HTTPRoute. The HTTPRoute matches /anything/team2/delay, forwards to httpbin’s /delay endpoint, and defines a custom 5s request timeout that overrides the parent’s 1s timeout.

   kubectl apply -f- <<EOF
   apiVersion: gateway.networking.k8s.io/v1
   kind: HTTPRoute
   metadata:
     name: child-team2
     namespace: team2
   spec:
     rules:
     - matches:
       - path:
           type: PathPrefix
           value: /anything/team2/delay
       filters:
       - type: URLRewrite
         urlRewrite:
           path:
             type: ReplacePrefixMatch
             replacePrefixMatch: /delay
       backendRefs:
       - name: httpbin
         port: 8000
       timeouts:
         request: 5s
   EOF

4. Send a request to the delegation.example domain along the /anything/team1/delay/3 path. The httpbin app holds the request open for 3 seconds, but the inherited 1s timeout cuts the request short. You get a 504 HTTP response after about 1 second.

   Cloud Provider LoadBalancerPort-forward for local testing

   time curl -i --max-time 8 http://$INGRESS_GW_ADDRESS:8080/anything/team1/delay/3 \
     -H "host: delegation.example"

   time curl -i --max-time 8 localhost:8080/anything/team1/delay/3 \
     -H "host: delegation.example"

   Example output:

   HTTP/1.1 504 Gateway Timeout
   content-type: text/plain
   server: agentgateway
   
   curl ...  total 1.034

5. Send a request along the /anything/team2/delay/3 path. The child-team2 route’s 5s timeout overrides the parent’s 1s timeout, so the 3-second httpbin delay completes. You get a 200 HTTP response after about 3 seconds.

   Cloud Provider LoadBalancerPort-forward for local testing

   time curl -i --max-time 8 http://$INGRESS_GW_ADDRESS:8080/anything/team2/delay/3 \
     -H "host: delegation.example"

   time curl -i --max-time 8 localhost:8080/anything/team2/delay/3 \
     -H "host: delegation.example"

   Example output:

   HTTP/1.1 200 OK
   access-control-allow-credentials: true
   access-control-allow-origin: *
   content-type: application/json; encoding=utf-8
   server: agentgateway
   
   curl ...  total 3.032

Cleanup

kubectl delete httproute parent -n agentgateway-system
kubectl delete httproute child-team1 -n team1
kubectl delete httproute child-team2 -n team2
kubectl delete namespaces team1 team2