Day 0: Building the Training Ground
Goal: kind cluster
gw-labis running, LoadBalancer IPs work, the demo apps respond. · Duration: approx. 40 min · Prerequisite: none
Briefing
- Parts A and B run on a kind cluster
gw-labwith 1 control plane node and 1 worker node. cloud-provider-kindassigns real LoadBalancer IPs from the Docker networkkind. That way every Gateway gets its own address – just like later on RKE2 with Cilium LB IPAM.*.gw.localtest.mepublicly points to127.0.0.1. We send requests to the Gateway IP withcurl --resolve; the Host header and SNI stay correct.- All demo apps use a 5 MB image:
echo-basicfrom the Gateway API project. It echoes path, host and headers back as JSON.
Drill 1: Install the Tools
macOS with Homebrew:
brew install kind kubectl helm jq cloud-provider-kind grpcurl
brew list --versions kind kubernetes-cli helm jq cloud-provider-kind grpcurlExpected (versions may differ):
cloud-provider-kind 0.12.0
grpcurl 1.9.4
helm 4.3.0
jq 1.8.2
kind 0.33.0
kubernetes-cli 1.37.1
Linux: kind, kubectl, helm and
grpcurl from the official release pages, jq
via the package manager. cloud-provider-kind is available
as a binary at
https://github.com/kubernetes-sigs/cloud-provider-kind/releases
or via Go:
go install sigs.k8s.io/[email protected]You only need grpcurl on Day 6,
cloud-provider-kind from Drill 5 on.
Save your progress? Sign up for free
Drill 2: Check Versions and Docker
kind version
kubectl version --client | head -1
helm version --short
cloud-provider-kind version
docker version --format '{{.Client.Version}} / {{.Server.Version}}'Expected:
kind v0.33.0 go1.27.0 darwin/arm64
Client Version: v1.37.1
v4.3.0+gbec5b06
cloud-provider-kind 0.12.0
29.9.0 / 29.5.2
docker info --format 'CPUs: {{.NCPU}} RAM: {{.MemTotal}}'Expected (may differ):
CPUs: 4 RAM: 8307167232
4 CPUs and 8 GB of RAM for the Docker VM (Docker Desktop, Colima, OrbStack) are enough. Plan for about 3 GB of disk space for the node image and container images.
Save your progress? Sign up for free
Drill 3: Create the Working Directory
mkdir -p ~/gw-lab/code/demo
mkdir -p ~/gw-lab/tag{01,02,03,04,05,06,07,08,09,10,11,12,13,14}
cd ~/gw-lab && ls -mExpected:
code, tag01, tag02, tag03, tag04, tag05, tag06, tag07, tag08, tag09, tag10,
tag11, tag12, tag13, tag14
Everything that several days need goes into
~/gw-lab/code/demo: cluster configuration, demo apps,
helper scripts. The chapter files live in tagNN.
From Day 4 on, you also apply files that the book does not print in full. They are available free of charge in the companion code on GitHub: https://github.com/thomaszachmann/gateway-api-zum-anfassen. Get it now:
git clone https://github.com/thomaszachmann/gateway-api-zum-anfassen.git \
~/gateway-api-zum-anfassen 2>/dev/null || git -C ~/gateway-api-zum-anfassen pull
cp -R ~/gateway-api-zum-anfassen/* ~/gw-lab/code/
ls ~/gw-lab/codeThe files you write yourself in the drills replace the files of the same name from the companion code. That is intended: their content is identical.
Save your progress? Sign up for free
Drill 4: Build the kind Cluster
cat > ~/gw-lab/code/demo/kind-gw-lab.yaml <<'EOF'
# kind cluster for "Gateway API hands-on" (Part A/B)
kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
name: gw-lab
nodes:
- role: control-plane
- role: worker
EOF
kind create cluster --config ~/gw-lab/code/demo/kind-gw-lab.yaml
kubectl get nodesExpected (shortened, may differ depending on the version):
Creating cluster "gw-lab" ...
✓ Ensuring node image (kindest/node:v1.37.0)
✓ Preparing nodes
...
Set kubectl context to "kind-gw-lab"
NAME STATUS ROLES AGE VERSION
gw-lab-control-plane Ready control-plane 40s v1.37.0
gw-lab-worker Ready <none> 25s v1.37.0
Why no extraPortMappings for 80/443? Every Gateway gets
its own LoadBalancer Service. Fixed host ports would collide with two
Gateways – the LB IPs from cloud-provider-kind do not.
Tip: The Envoy Gateway compatibility matrix lists Kubernetes 1.33–1.36 for v1.9. The book runs with the kind default 1.37.0 without any issues. If you want to stay exactly within the matrix, set
image: kindest/node:v1.36.xper node in the kind config.
Save your progress? Sign up for free
Drill 5: Namespaces and Demo Apps
Three namespaces, three teams: infra belongs to the
platform team (Gateways), shop and payments to
the app teams.
cd ~/gw-lab/code/demo
cat > namespaces.yaml <<'EOF'
# Platform team: infra · App teams: shop, payments
apiVersion: v1
kind: Namespace
metadata:
name: infra
labels:
gw-lab/team: platform
---
apiVersion: v1
kind: Namespace
metadata:
name: shop
labels:
gw-lab/team: shop
---
apiVersion: v1
kind: Namespace
metadata:
name: payments
labels:
gw-lab/team: payments
EOFThe shop in version 1:
cat > shop-v1.yaml <<'EOF'
# Demo shop: echo server, the response JSON contains the service name
apiVersion: apps/v1
kind: Deployment
metadata:
name: shop-v1
namespace: shop
labels: {app: shop, version: v1}
spec:
replicas: 1
selector:
matchLabels: {app: shop, version: v1}
template:
metadata:
labels: {app: shop, version: v1}
spec:
containers:
- name: echo
image: registry.k8s.io/gateway-api/echo-basic:v1.6.0
env:
- name: SERVICE_NAME
value: shop-v1
- name: POD_NAME
valueFrom: {fieldRef: {fieldPath: metadata.name}}
- name: NAMESPACE
valueFrom: {fieldRef: {fieldPath: metadata.namespace}}
ports:
- {name: http, containerPort: 3000}
readinessProbe:
httpGet: {path: /health, port: http}
resources:
requests: {cpu: 10m, memory: 16Mi}
limits: {memory: 64Mi}
---
apiVersion: v1
kind: Service
metadata:
name: shop-v1
namespace: shop
labels: {app: shop, version: v1}
spec:
selector: {app: shop, version: v1}
ports:
- {name: http, port: 80, targetPort: http}
EOF
sed 's/shop-v1/shop-v2/g; s/version: v1/version: v2/g' shop-v1.yaml > shop-v2.yamlThe gRPC service payments – the same image in gRPC mode,
with server reflection:
cat > payments.yaml <<'EOF'
# Demo gRPC service: GrpcEcho with server reflection on port 3000 (h2c)
apiVersion: apps/v1
kind: Deployment
metadata:
name: payments
namespace: payments
labels: {app: payments}
spec:
replicas: 1
selector:
matchLabels: {app: payments}
template:
metadata:
labels: {app: payments}
spec:
containers:
- name: grpc-echo
image: registry.k8s.io/gateway-api/echo-basic:v1.6.0
env:
- name: GRPC_ECHO_SERVER
value: "1"
- name: SERVICE_NAME
value: payments
- name: POD_NAME
valueFrom: {fieldRef: {fieldPath: metadata.name}}
- name: NAMESPACE
valueFrom: {fieldRef: {fieldPath: metadata.namespace}}
ports:
- {name: grpc, containerPort: 3000}
readinessProbe:
tcpSocket: {port: grpc}
resources:
requests: {cpu: 10m, memory: 16Mi}
limits: {memory: 64Mi}
---
apiVersion: v1
kind: Service
metadata:
name: payments
namespace: payments
labels: {app: payments}
spec:
selector: {app: payments}
ports:
- name: grpc
port: 3000
targetPort: grpc
appProtocol: kubernetes.io/h2c
EOF
kubectl apply -f namespaces.yaml -f shop-v1.yaml -f shop-v2.yaml -f payments.yaml
kubectl get pods -A -l 'app in (shop,payments)'Expected (shortened):
NAMESPACE NAME READY STATUS RESTARTS AGE
payments payments-6cfbdd9c64-94c5d 1/1 Running 0 44s
shop shop-v1-78db96c8d9-n4t9k 1/1 Running 0 44s
shop shop-v2-8b7c8fcd7-c7snd 1/1 Running 0 44s
appProtocol: kubernetes.io/h2c later tells the Gateway
that the backend behind the Service speaks HTTP/2 without TLS –
mandatory for gRPC (Day 6).
Save your progress? Sign up for free
Drill 6: Get to Know the Echo Server
kubectl -n shop port-forward svc/shop-v1 8080:80 >/dev/null &
sleep 2
curl -s localhost:8080/halloExpected:
{
"path": "/hallo",
"host": "localhost:8080",
"method": "GET",
"proto": "HTTP/1.1",
"headers": {
"Accept": [
"*/*"
],
"User-Agent": [
"curl/8.7.1"
]
},
"httpPort": "3000",
"namespace": "shop",
"ingress": "",
"service": "shop-v1",
"pod": "shop-v1-78db96c8d9-n4t9k"
}
curl -s localhost:8080/hallo | jq -r .service
curl -s -o /dev/null -w '%{http_code} %{time_total}s\n' 'localhost:8080/x?delay=1s'
kill %1Expected:
shop-v1
200 1.006343s
Remember the special paths: ?delay=3s delays the
response (timeouts, Day 3), /status/503 returns any status
code you like, and /retry/?uuid=…&succeedAfter=N fails
N times before it responds (retries, Day 3).
kubectl -n shop logs shows every request as
Echoing back request made to ….
Save your progress? Sign up for free
Drill 7: Start cloud-provider-kind
Open a second terminal and keep it running during all kind days.
macOS (Docker runs in a VM, hence a tunnel via an lo0
alias – requires sudo):
sudo cloud-provider-kind --gateway-channel disabledLinux (the LB IPs live directly on the Docker bridge):
cloud-provider-kind --gateway-channel disabledExpected (shortened):
I1009 22:44:02.545791 app.go:228] Detect runtime: docker
I1009 22:44:02.751287 controller.go:169] "Connected successfully" cluster="gw-lab" ...
I1009 22:44:02.751299 controller.go:96] "Creating new cloud provider" cluster="gw-lab"
Why --gateway-channel disabled? Without the flag,
cloud-provider-kind installs its own Gateway API CRDs and a GatewayClass
cloud-provider-kind. We want Envoy Gateway (Day 1) – and
exactly one source for the CRDs.
Test in the first terminal:
kubectl -n shop expose deployment shop-v1 --name lb-test \
--type LoadBalancer --port 80 --target-port 3000
kubectl -n shop get svc lb-test -wExpected (after 10–60 s, the IP may differ; Ctrl+C ends
-w):
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
lb-test LoadBalancer 10.96.228.108 <pending> 80:30205/TCP 1s
lb-test LoadBalancer 10.96.228.108 172.18.0.10 80:30205/TCP 12s
LB_IP=$(kubectl -n shop get svc lb-test \
-o jsonpath='{.status.loadBalancer.ingress[0].ip}')
curl -s "http://$LB_IP/lb" | jq -c '{path, service}'
docker ps --filter label=io.x-k8s.cloud-provider-kind.cluster=gw-lab \
--format '{{.Names}} {{.Image}}'
kubectl -n shop delete svc lb-testExpected:
{"path":"/lb","service":"shop-v1"}
kindccm-ee2e011807f7 envoyproxy/envoy:v1.33.2
service "lb-test" deleted from shop namespace
For each LoadBalancer Service, cloud-provider-kind starts a small
Envoy container (kindccm-…) in the Docker network
kind. It gets the external IP and forwards to the
NodePorts.
Warning: cloud-provider-kind serves all kind clusters on your machine. If you have other clusters with LoadBalancer Services, they get IPs as well.
Tip: No
sudopossible? Start with--enable-lb-port-mapping. Thekindccmcontainer then publishes port 80 on a random host port, which you find withdocker port <container> 80/tcp. Instead of--resolve host:80:$GW_IPyou use--connect-to ::127.0.0.1:<port>.
Save your progress? Sign up for free
Drill 8: Helper Scripts and the curl Pattern
From Day 2 on, every Gateway has an address in
status.addresses. This script reads it:
cat > ~/gw-lab/code/demo/gw-ip.sh <<'EOF'
#!/usr/bin/env bash
# Prints the address of a Gateway (status.addresses[0].value).
# Usage: gw-ip.sh [gateway] [namespace] Default: web infra
set -euo pipefail
gw="${1:-web}"
ns="${2:-infra}"
ip=$(kubectl -n "$ns" get gateway "$gw" \
-o jsonpath='{.status.addresses[0].value}' 2>/dev/null || true)
if [ -z "$ip" ]; then
echo "Gateway $ns/$gw hat (noch) keine Adresse – läuft cloud-provider-kind?" >&2
exit 1
fi
echo "$ip"
EOF
chmod +x ~/gw-lab/code/demo/gw-ip.sh
~/gw-lab/code/demo/gw-ip.sh; echo "Exit: $?"Expected (there is no Gateway yet):
Gateway infra/web hat (noch) keine Adresse – läuft cloud-provider-kind?
Exit: 1
The pattern for all following days:
dig +short shop.gw.localtest.meExpected:
127.0.0.1
GW_IP=$(~/gw-lab/code/demo/gw-ip.sh)
curl -s --resolve shop.gw.localtest.me:80:$GW_IP http://shop.gw.localtest.me/
Why --resolve? The name resolves publicly to
127.0.0.1, but the Gateway listens on $GW_IP.
--resolve only bends the name resolution. The Host header
and – from Day 4 on – SNI stay shop.gw.localtest.me. That
is exactly how a real DNS record behaves later.
The companion code under code/demo also contains
up.sh (builds the lab to the state after Day 2) and
down.sh (deletes the cluster). With them you can start any
later day fresh.
Save your progress? Sign up for free
Checkpoint
check() { if eval "$2" >/dev/null 2>&1; then echo "✔ $1"; else echo "✘ $1"; fi; }
check "kind-Cluster gw-lab existiert" 'kind get clusters | grep -qx gw-lab'
check "Kontext kind-gw-lab aktiv" \
'[ "$(kubectl config current-context)" = kind-gw-lab ]'
check "alle Nodes Ready" \
'! kubectl get nodes --no-headers | grep -v " Ready "'
check "shop-v1/v2 verfügbar" \
'kubectl -n shop wait deploy/shop-v1 deploy/shop-v2 --for=condition=Available \
--timeout=5s'
check "payments verfügbar" \
'kubectl -n payments wait deploy/payments --for=condition=Available --timeout=5s'
check "cloud-provider-kind läuft" 'pgrep -f cloud-provider-kind'
check "gw-ip.sh ausführbar" '[ -x ~/gw-lab/code/demo/gw-ip.sh ]'Expected:
✔ kind-Cluster gw-lab existiert
✔ Kontext kind-gw-lab aktiv
✔ alle Nodes Ready
✔ shop-v1/v2 verfügbar
✔ payments verfügbar
✔ cloud-provider-kind läuft
✔ gw-ip.sh ausführbar
Challenge
Scale shop-v2 to two replicas and prove via a
LoadBalancer Service that the responses come from two different pods.
Clean up afterwards.
Hint: The pod field in the response
JSON reveals who responded.
Solution
kubectl -n shop scale deploy shop-v2 --replicas=2
kubectl -n shop rollout status deploy shop-v2
kubectl -n shop expose deployment shop-v2 --name lb-v2 \
--type LoadBalancer --port 80 --target-port 3000
until IP=$(kubectl -n shop get svc lb-v2 \
-o jsonpath='{.status.loadBalancer.ingress[0].ip}') && [ -n "$IP" ]; do sleep 2; done
for i in $(seq 1 20); do curl -s "http://$IP/" | jq -r .pod; done | sort | uniq -c
kubectl -n shop delete svc lb-v2
kubectl -n shop scale deploy shop-v2 --replicas=1Expected (pod names and distribution differ):
10 shop-v2-8b7c8fcd7-c7snd
10 shop-v2-8b7c8fcd7-tvmxw
Save your progress? Sign up for free
Enterprise Note
- kind does not replace a multi-node cluster: no real network between zones, no external DNS. That comes from Day 8 on with RKE2.
- In production, a cloud LB, MetalLB or Cilium LB IPAM with L2/BGP takes over the external IPs instead of cloud-provider-kind (Day 9).
- Demo images from test registries do not belong in production. Real workloads: pin images by digest and pull them from an internal registry.
- You replace internal names like
*.gw.localtest.mewith your own zone with a wildcard record pointing to the Gateway IP (Day 9:*.apps.lab.internal).