Day 2: First Gateway and HTTPRoute
Goal: A Gateway in the namespace
infraaccepts traffic, HTTPRoutes fromshopdistribute 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 viasectionName. - 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: GatewayProgrammed, RouteAcceptedandResolvedRefs.
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 -wExpected (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 infraExpected (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=webExpected (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 -1Expected:
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 shopExpected:
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 attachedRoutesExpected:
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
doneExpected:
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 withno 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/xExpected:
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; doneExpected (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 -1Expected:
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.yamlThis 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-debugExpected:
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: Allis for the lab only. At the customer:Selectoron a namespace label orSame(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 applyis only successful onceAcceptedandResolvedRefsareTrue(Day 11). - Regex paths (
RegularExpression) are implementation-specific – avoid them if you want to be able to switch implementations.