Skip to content
Hands-on IT IT Drills

Day 2: First Gateway and HTTPRoute

Goal: A Gateway in the namespace infra accepts traffic, HTTPRoutes from shop distribute it by path, header and query. · Duration: approx. 60 min · Prerequisite: Day 1

Briefing

  • A Gateway is a list of listeners (port, protocol, optionally hostname and TLS). Envoy Gateway builds one Envoy Deployment plus LoadBalancer Service per Gateway.
  • An HTTPRoute attaches to a Gateway via parentRefs, optionally to exactly one listener via sectionName.
  • Route hostnames and the listener hostname must intersect, otherwise the route is not accepted.
  • Within a rule: conditions in one match entry are AND, multiple match entries are OR.
  • Debugging always starts with status: Gateway Programmed, Route Accepted and ResolvedRefs.
 curl --resolve shop...:80:$GW_IP
        │
        ▼
 kindccm-… (LB IP) ─► Service envoy-infra-web-… ─► Envoy pod   (ns envoy-gateway-system)
                                                      │  config via xDS from the controller
                         Gateway infra/web ◄── parentRefs ── HTTPRoute shop/shop
                                                      │
                                                      ▼
                                               Service shop-v1 / shop-v2

Drill 1: Create the Gateway

cat > ~/gw-lab/code/demo/gateway.yaml <<'EOF'
# Gateway of the platform team (state after Day 2)
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: web
  namespace: infra
spec:
  gatewayClassName: eg
  listeners:
    - name: http
      protocol: HTTP
      port: 80
      allowedRoutes:
        namespaces:
          from: All          # restricted on Day 7
EOF
kubectl apply -f ~/gw-lab/code/demo/gateway.yaml
kubectl -n infra get gateway web -w

Expected (after 20–60 s, the IP may differ; Ctrl+C ends -w):

gateway.gateway.networking.k8s.io/web created
NAME   CLASS   ADDRESS      PROGRAMMED   AGE
web    eg                   False        0s
web    eg      172.18.0.8   True         41s
conds.sh gateway web infra

Expected (messages shortened):

Accepted=True (Accepted): The Gateway has been scheduled by Envoy Gateway
Programmed=True (Programmed): Address assigned to the Gateway, 1/1 envoy replicas …
listener http (attachedRoutes=0):
  Programmed=True (Programmed): Sending translated listener configuration to the …
  Accepted=True (Accepted): Listener has been successfully translated
  ResolvedRefs=True (ResolvedRefs): Listener references have been resolved

Accepted means: the spec is valid. Programmed means: the data plane is ready and has an address. attachedRoutes=0 – no route is attached to the listener yet.

Save your progress? Sign up for free

Drill 2: What Envoy Gateway Builds From It

kubectl -n envoy-gateway-system get deploy,svc \
  -l gateway.envoyproxy.io/owning-gateway-name=web

Expected (shortened, the hash suffix differs):

NAME                                       READY   UP-TO-DATE   AVAILABLE   AGE
deployment.apps/envoy-infra-web-a97fc3bf   1/1     1            1           41s

NAME                               TYPE           EXTERNAL-IP   PORT(S)
service/envoy-infra-web-a97fc3bf   LoadBalancer   172.18.0.8    80:32072/TCP

The Gateway lives in infra, but the proxies live in the controller’s namespace. The name follows the pattern envoy-<namespace>-<gateway>-<hash>. The Service’s external IP is the address in the Gateway status.

export GW_IP=$(gw-ip.sh)
echo "$GW_IP"
curl -si --resolve shop.gw.localtest.me:80:$GW_IP http://shop.gw.localtest.me/ | head -1

Expected:

172.18.0.8
HTTP/1.1 404 Not Found

Envoy already responds – it just doesn’t know any route yet. So a 404 from the Gateway is a good sign: network and listener are working.

Save your progress? Sign up for free

Drill 3: The First HTTPRoute

cat > ~/gw-lab/code/demo/route-shop.yaml <<'EOF'
# Base route of the shop team (state after Day 2)
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: shop
  namespace: shop
spec:
  parentRefs:
    - name: web
      namespace: infra
      sectionName: http
  hostnames:
    - shop.gw.localtest.me
  rules:
    - backendRefs:
        - name: shop-v1
          port: 80
EOF
kubectl apply -f ~/gw-lab/code/demo/route-shop.yaml
kubectl -n shop get httproute
conds.sh httproute shop shop

Expected:

httproute.gateway.networking.k8s.io/shop created
NAME   HOSTNAMES                  AGE
shop   ["shop.gw.localtest.me"]   3s
parent infra/web/http:
  Accepted=True (Accepted): Route is accepted
  ResolvedRefs=True (ResolvedRefs): Resolved all the Object references for the Route
curl -s --resolve shop.gw.localtest.me:80:$GW_IP \
  http://shop.gw.localtest.me/hallo | jq -c '{path, host, service, pod}'
curl -s --resolve shop.gw.localtest.me:80:$GW_IP \
  http://shop.gw.localtest.me/hallo | jq -c '.headers | keys'

Expected:

{"path":"/hallo","host":"shop.gw.localtest.me","service":"shop-v1","pod":"shop-v1-…"}
["Accept","User-Agent","X-Envoy-External-Address","X-Forwarded-For",
"X-Forwarded-Proto","X-Request-Id"]

For routes, the status is recorded per parent in status.parents[] – a route can be attached to several Gateways and be received differently well by each. Envoy adds X-Forwarded-* and an X-Request-Id for tracing (Day 11).

conds.sh gateway web infra | grep attachedRoutes

Expected:

listener http (attachedRoutes=1):

Save your progress? Sign up for free

Drill 4: Matching Paths

cd ~/gw-lab/tag02
cat > shop-matching.yaml <<'EOF'
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: shop
  namespace: shop
spec:
  parentRefs:
    - name: web
      namespace: infra
      sectionName: http
  hostnames:
    - shop.gw.localtest.me
  rules:
    - name: v2-pfad
      matches:
        - path:
            type: PathPrefix
            value: /v2
      backendRefs:
        - name: shop-v2
          port: 80
    - name: v2-optin
      matches:
        - headers:
            - name: x-version
              value: v2
        - queryParams:
            - name: version
              value: v2
      backendRefs:
        - name: shop-v2
          port: 80
    - name: beta
      matches:
        - path:
            type: PathPrefix
            value: /beta
          headers:
            - name: x-beta
              value: "1"
      backendRefs:
        - name: shop-v2
          port: 80
    - name: rest
      backendRefs:
        - name: shop-v1
          port: 80
EOF
kubectl apply -f shop-matching.yaml
for p in / /v2 /v2/warenkorb /v2x; do
  printf '%-15s -> ' "$p"
  curl -s --resolve shop.gw.localtest.me:80:$GW_IP \
    "http://shop.gw.localtest.me$p" | jq -r .service
done

Expected:

httproute.gateway.networking.k8s.io/shop configured
/               -> shop-v1
/v2             -> shop-v2
/v2/warenkorb   -> shop-v2
/v2x            -> shop-v1

PathPrefix compares whole path segments: /v2 matches /v2 and /v2/…, but not /v2x. With ingress-nginx this behavior depends on pathType and regex annotations – here it is specified. A rule without matches (here rest) implicitly gets PathPrefix /.

Save your progress? Sign up for free

Drill 5: Headers, Query and the AND/OR Logic

s() { curl -s --resolve shop.gw.localtest.me:80:$GW_IP "$@" | jq -r .service; }
s -H 'x-version: v2' http://shop.gw.localtest.me/
s -H 'X-Version: v2' http://shop.gw.localtest.me/
s -H 'x-version: V2' http://shop.gw.localtest.me/
s 'http://shop.gw.localtest.me/?version=v2'

Expected:

shop-v2
shop-v2
shop-v1
shop-v2

Header names are case-insensitive, values are not: V2 is not v2. The rule v2-optin has two match entries – header or query is enough.

s http://shop.gw.localtest.me/beta
s -H 'x-beta: 1' http://shop.gw.localtest.me/beta/neu
s -H 'x-beta: 1' http://shop.gw.localtest.me/

Expected:

shop-v1
shop-v2
shop-v1

Rule beta has one match entry with path and header: both have to match.

Tip: Always put URLs containing ? in quotes. Otherwise zsh tries to expand them as glob patterns and aborts with no matches found.

Save your progress? Sign up for free

Drill 6: Second Listener With a Hostname

The platform team gives the API team its own listener that only accepts api.gw.localtest.me.

cat > gateway-api-listener.yaml <<'EOF'
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: web
  namespace: infra
spec:
  gatewayClassName: eg
  listeners:
    - name: http
      protocol: HTTP
      port: 80
      allowedRoutes:
        namespaces:
          from: All
    - name: http-api
      protocol: HTTP
      port: 80
      hostname: api.gw.localtest.me
      allowedRoutes:
        namespaces:
          from: All
EOF
cat > api.yaml <<'EOF'
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: api
  namespace: shop
spec:
  parentRefs:
    - name: web
      namespace: infra
      sectionName: http-api
  rules:
    - matches:
        - path:
            type: Exact
            value: /info
          method: GET
      backendRefs:
        - name: shop-v2
          port: 80
    - backendRefs:
        - name: shop-v1
          port: 80
EOF
kubectl apply -f gateway-api-listener.yaml -f api.yaml
a() { curl -s --resolve api.gw.localtest.me:80:$GW_IP "$@" | jq -r .service; }
a http://api.gw.localtest.me/info
a -X POST http://api.gw.localtest.me/info
a http://api.gw.localtest.me/info/x

Expected:

gateway.gateway.networking.k8s.io/web configured
httproute.gateway.networking.k8s.io/api created
shop-v2
shop-v1
shop-v1

The route api has no hostnames of its own – it inherits the listener’s hostname. Exact only matches /info exactly, method: GET excludes POST. Both listeners share port 80; Envoy tells them apart by the Host header.

Save your progress? Sign up for free

Drill 7: Debugging Status – Three Typical Errors

cat > kaputt.yaml <<'EOF'
# Error 1: route hostname does not match the listener http-api
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: kaputt
  namespace: shop
spec:
  parentRefs:
    - name: web
      namespace: infra
      sectionName: http-api
  hostnames:
    - shop.gw.localtest.me
  rules:
    - backendRefs:
        - name: shop-v1
          port: 80
---
# Error 2: Service does not exist
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: kaputt2
  namespace: shop
spec:
  parentRefs:
    - name: web
      namespace: infra
  hostnames:
    - kaputt.gw.localtest.me
  rules:
    - backendRefs:
        - name: shop-v3
          port: 80
---
# Error 3: parentRef without namespace -> looks for Gateway "web" in "shop"
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: kaputt3
  namespace: shop
spec:
  parentRefs:
    - name: web
  hostnames:
    - kaputt.gw.localtest.me
  rules:
    - backendRefs:
        - name: shop-v1
          port: 80
EOF
kubectl apply -f kaputt.yaml
for r in kaputt kaputt2 kaputt3; do echo "== $r"; conds.sh httproute $r shop; done

Expected (messages shortened):

== kaputt
parent infra/web/http-api:
  Accepted=False (NoMatchingListenerHostname): There were no hostname intersections …
  ResolvedRefs=True (ResolvedRefs): Resolved all the Object references for the Route
== kaputt2
parent infra/web/:
  Accepted=True (Accepted): Route is accepted
  ResolvedRefs=False (BackendNotFound): Failed to process route rule 0 backendRef 0: …
== kaputt3
curl -si --resolve kaputt.gw.localtest.me:80:$GW_IP \
  http://kaputt.gw.localtest.me/ | head -1

Expected:

HTTP/1.1 500 Internal Server Error
Symptom Cause Where you see it
Accepted=False, NoMatchingListenerHostname Hostnames do not intersect Route status
ResolvedRefs=False, BackendNotFound, HTTP 500 Wrong Service/port Route status
no status at all That Gateway does not exist, no controller feels responsible missing status
attachedRoutes stays 0 Route is not attached to the listener Gateway status

kaputt2 is accepted, but broken: the rule exists, its backend does not. That is why Envoy responds with 500 instead of 404 – an important difference when troubleshooting.

kubectl -n shop delete httproute kaputt kaputt2 kaputt3 api
kubectl apply -f ~/gw-lab/code/demo/gateway.yaml -f ~/gw-lab/code/demo/route-shop.yaml

This brings you back to the base state from code/demo that Day 3 builds on.

Save your progress? Sign up for free

Checkpoint

check() { if eval "$2" >/dev/null 2>&1; then echo "✔ $1"; else echo "✘ $1"; fi; }
GW_IP=$(gw-ip.sh)
check "Gateway web Programmed" \
  'kubectl -n infra wait gateway/web --for=condition=Programmed --timeout=5s'
check "Gateway hat Adresse ($GW_IP)" '[ -n "$GW_IP" ]'
check "Route shop akzeptiert" \
  'conds.sh httproute shop shop | grep -q "Accepted=True"'
check "shop.gw.localtest.me -> shop-v1" \
  '[ "$(curl -s --resolve shop.gw.localtest.me:80:$GW_IP \
     http://shop.gw.localtest.me/ | jq -r .service)" = shop-v1 ]'
check "keine Übungs-Routes mehr" \
  '[ "$(kubectl -n shop get httproute --no-headers | wc -l)" -eq 1 ]'

Expected:

✔ Gateway web Programmed
✔ Gateway hat Adresse (172.18.0.8)
✔ Route shop akzeptiert
✔ shop.gw.localtest.me -> shop-v1
✔ keine Übungs-Routes mehr

Challenge

A second team wants to branch off debug traffic without touching the route shop: create a separate HTTPRoute shop-debug for the same hostname that sends requests with the header x-debug: true to shop-v2. Normal requests must continue to land on shop-v1.

Hint: All routes for the same hostname are merged into one routing table; the more specific match wins.

Solution

cat > ~/gw-lab/tag02/shop-debug.yaml <<'EOF'
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: shop-debug
  namespace: shop
spec:
  parentRefs:
    - name: web
      namespace: infra
  hostnames:
    - shop.gw.localtest.me
  rules:
    - matches:
        - headers:
            - name: x-debug
              value: "true"
      backendRefs:
        - name: shop-v2
          port: 80
EOF
kubectl apply -f ~/gw-lab/tag02/shop-debug.yaml
s() { curl -s --resolve shop.gw.localtest.me:80:$GW_IP "$@" | jq -r .service; }
s http://shop.gw.localtest.me/
s -H 'x-debug: true' http://shop.gw.localtest.me/egal
conds.sh gateway web infra | grep attachedRoutes
kubectl -n shop delete httproute shop-debug

Expected:

httproute.gateway.networking.k8s.io/shop-debug created
shop-v1
shop-v2
listener http (attachedRoutes=2):
httproute.gateway.networking.k8s.io "shop-debug" deleted from shop namespace

For equally specific matches, the specification says the older route (creationTimestamp) decides, then the name in alphabetical order.

Save your progress? Sign up for free

Enterprise Note

  • One Gateway per trust zone (external, internal, partner) instead of one Gateway for everything; each gets its own IP, its own Envoy pods and its own policies.
  • allowedRoutes.namespaces.from: All is for the lab only. At the customer: Selector on a namespace label or Same (Day 7).
  • Hostnames belong on the listener as soon as TLS comes into play (Day 4): the listener defines which names the platform team is responsible for certificates for.
  • Include route status in the deployment pipeline: a kubectl apply is only successful once Accepted and ResolvedRefs are True (Day 11).
  • Regex paths (RegularExpression) are implementation-specific – avoid them if you want to be able to switch implementations.