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

Basic example

Set up basic route delegation between a parent HTTPRoute and two child HTTPRoutes.

Set up basic route delegation between a parent HTTPRoute and two child HTTPRoutes.

Configuration overview

In this guide, you set up route delegation from a parent HTTPRoute to two child HTTPRoutes that forward traffic to an httpbin sample app.

The following image illustrates the route delegation hierarchy:

parent HTTPRoute:

• Delegates traffic as follows:
  • /anything/team1 is delegated to the child HTTPRoute child-team1 in namespace team1.
  • /anything/team2 is delegated to the child HTTPRoute child-team2 in namespace team2.

child-team1 HTTPRoute:

• Matches incoming traffic for the /anything/team1/foo prefix path and routes that traffic to the httpbin app in the team1 namespace.
• Does not select a specific parent in parentRefs. Any parent HTTPRoute in the delegation chain that matches its namespace and name can delegate to it.

child-team2 HTTPRoute:

• Matches incoming traffic for the /anything/team2/bar exact path and routes that traffic to the httpbin app in the team2 namespace.

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. The HTTPRoute specifies two routes:

   • /anything/team1: The routing decision is delegated to a child HTTPRoute in the team1 namespace.
   • /anything/team2: The routing decision is delegated to a child HTTPRoute in the team2 namespace.

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

2. Create the child HTTPRoute for the team1 namespace that matches traffic on the /anything/team1/foo prefix and routes traffic to the httpbin app.

   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/foo
       backendRefs:
       - name: httpbin
         port: 8000
   EOF

3. Create the child HTTPRoute for the team2 namespace that matches traffic on the /anything/team2/bar exact path and routes traffic to the httpbin app. The HTTPRoute selects the parent HTTPRoute in the parentRefs field, so the controller reports status back to that parent.

   kubectl apply -f- <<EOF
   apiVersion: gateway.networking.k8s.io/v1
   kind: HTTPRoute
   metadata:
     name: child-team2
     namespace: team2
   spec:
     parentRefs:
     - name: parent
       namespace: agentgateway-system
       group: gateway.networking.k8s.io
       kind: HTTPRoute
     rules:
     - matches:
       - path:
           type: Exact
           value: /anything/team2/bar
       backendRefs:
       - name: httpbin
         port: 8000
   EOF

4. Inspect the parent and child HTTPRoutes.

   kubectl get httproute parent -n agentgateway-system
   kubectl get httproute child-team1 -n team1
   kubectl get httproute child-team2 -n team2

   Note that only the parent HTTPRoute has the delegation.example hostname.

   NAME     HOSTNAMES                AGE
   parent   ["delegation.example"]   22s
   NAME          HOSTNAMES   AGE
   child-team1               12s
   NAME          HOSTNAMES   AGE
   child-team2               6s   

5. Send a request to the delegation.example domain along the /anything/team1/foo path. Verify that you get a 200 HTTP response.

   Cloud Provider LoadBalancerPort-forward for local testing

   curl -i http://$INGRESS_GW_ADDRESS:8080/anything/team1/foo -H "host: delegation.example"

   curl -i localhost:8080/anything/team1/foo -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

6. Send another request to the delegation.example domain along the /anything/team1/bar path. Verify that you get a 404 HTTP response, because child-team1 only matches the /anything/team1/foo path.

   Cloud Provider LoadBalancerPort-forward for local testing

   curl -i http://$INGRESS_GW_ADDRESS:8080/anything/team1/bar -H "host: delegation.example"

   curl -i localhost:8080/anything/team1/bar -H "host: delegation.example"

   Example output:

   HTTP/1.1 404 Not Found
   content-type: text/plain
   server: agentgateway

7. Send another request to the delegation.example domain along the /anything/team2/bar path that is configured on child-team2. Verify that you get a 200 HTTP response.

   Cloud Provider LoadBalancerPort-forward for local testing

   curl -i http://$INGRESS_GW_ADDRESS:8080/anything/team2/bar -H "host: delegation.example"

   curl -i localhost:8080/anything/team2/bar -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

8. Send another request along the /anything/team2/bar/test path. Verify that you get a 404 HTTP response, because child-team2 matches traffic only on the /anything/team2/bar exact path.

   Cloud Provider LoadBalancerPort-forward for local testing

   curl -i http://$INGRESS_GW_ADDRESS:8080/anything/team2/bar/test -H "host: delegation.example"

   curl -i localhost:8080/anything/team2/bar/test -H "host: delegation.example"

   Example output:

   HTTP/1.1 404 Not Found
   content-type: text/plain
   server: agentgateway

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