Skip to content
Hands-on IT IT Drills

Day 0: Building the Training Ground

Goal: kind cluster gw-lab is 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-lab with 1 control plane node and 1 worker node.
  • cloud-provider-kind assigns real LoadBalancer IPs from the Docker network kind. That way every Gateway gets its own address – just like later on RKE2 with Cilium LB IPAM.
  • *.gw.localtest.me publicly points to 127.0.0.1. We send requests to the Gateway IP with curl --resolve; the Host header and SNI stay correct.
  • All demo apps use a 5 MB image: echo-basic from 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 grpcurl

Expected (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 -m

Expected:

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/code

The 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 nodes

Expected (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.x per 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
EOF

The 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.yaml

The 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/hallo

Expected:

{
 "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 %1

Expected:

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 disabled

Linux (the LB IPs live directly on the Docker bridge):

cloud-provider-kind --gateway-channel disabled

Expected (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 -w

Expected (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-test

Expected:

{"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 sudo possible? Start with --enable-lb-port-mapping. The kindccm container then publishes port 80 on a random host port, which you find with docker port <container> 80/tcp. Instead of --resolve host:80:$GW_IP you 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.me

Expected:

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=1

Expected (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.me with your own zone with a wildcard record pointing to the Gateway IP (Day 9: *.apps.lab.internal).