Day 1: From Ingress to the Gateway API
Goal: You know the resource model, have installed Envoy Gateway and read conditions like a pro. · Duration: approx. 45 min · Prerequisite: Day 0
Briefing
- Ingress has one resource for everything. Anything beyond host and path ends up in vendor-specific annotations.
- The Gateway API separates roles: GatewayClass (infrastructure provider), Gateway (platform team), Routes (app teams).
- It is a set of CRDs, not part of Kubernetes itself. Version and channel (Standard or Experimental) are recorded as an annotation on every CRD.
- Every resource reports in
status.conditionswhether it was accepted and programmed. If the status is missing, no controller feels responsible.
Infrastructure provider GatewayClass "eg" (cluster-wide)
│
Platform team Gateway "web" (ns infra) Listener: port, protocol, TLS
│ parentRefs
App teams HTTPRoute (ns shop) ──► Service shop-v1 / shop-v2
GRPCRoute (ns payments) ──► Service payments
Drill 1: Ingress Without a Controller
cd ~/gw-lab/tag01
cat > ingress-shop.yaml <<'EOF'
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: shop
namespace: shop
annotations:
nginx.ingress.kubernetes.io/rewrite-target: /
spec:
rules:
- host: shop.gw.localtest.me
http:
paths:
- path: /v2
pathType: Prefix
backend:
service:
name: shop-v2
port:
number: 80
- path: /
pathType: Prefix
backend:
service:
name: shop-v1
port:
number: 80
EOF
kubectl apply -f ingress-shop.yaml
kubectl -n shop get ingress
kubectl get ingressclassExpected:
ingress.networking.k8s.io/shop created
NAME CLASS HOSTS ADDRESS PORTS AGE
shop <none> shop.gw.localtest.me 80 0s
No resources found
No controller, no address, no error message. The annotation
nginx.ingress.kubernetes.io/rewrite-target is only
understood by ingress-nginx – with Traefik or HAProxy it would have no
effect. This is exactly the problem the Gateway API solves: rewrites,
headers, weights and timeouts are part of the specification.
| Ingress | Gateway API | Who owns it? |
|---|---|---|
| IngressClass | GatewayClass | Infrastructure provider |
| (hidden in the controller) | Gateway with listeners | Platform team |
| Ingress rules | HTTPRoute, GRPCRoute, TLSRoute … | App team |
| Annotations | Filters, policies | App or platform team |
Save your progress? Sign up for free
Drill 2: No Gateway API in the Cluster Yet
kubectl api-resources --api-group=gateway.networking.k8s.io
kubectl get crd | grep -c gateway.networking.k8s.ioExpected:
NAME SHORTNAMES APIVERSION NAMESPACED KIND
0
Kubernetes does not ship the Gateway API. You install the CRDs yourself – or they come with the controller, as they will with Envoy Gateway in a moment.
Save your progress? Sign up for free
Drill 3: Install Envoy Gateway
helm install eg oci://docker.io/envoyproxy/gateway-helm --version v1.9.2 \
-n envoy-gateway-system --create-namespace
kubectl wait --timeout=5m -n envoy-gateway-system \
deployment/envoy-gateway --for=condition=AvailableExpected (shortened):
Pulled: docker.io/envoyproxy/gateway-helm:v1.9.2
NAME: eg
NAMESPACE: envoy-gateway-system
STATUS: deployed
REVISION: 1
DESCRIPTION: Install complete
...
deployment.apps/envoy-gateway condition met
helm list -n envoy-gateway-system
kubectl -n envoy-gateway-system get podsExpected (shortened):
NAME NAMESPACE REVISION STATUS CHART APP VERSION
eg envoy-gateway-system 1 deployed gateway-helm-v1.9.2 v1.9.2
NAME READY STATUS RESTARTS AGE
eg-gateway-helm-certgen-9hmj4 0/1 Completed 0 30s
envoy-gateway-75b559cc4c-8xn4q 1/1 Running 0 27s
The certgen job creates the TLS certificates the
controller uses to talk to the Envoy proxies via xDS. The proxies
themselves are only created once a Gateway exists (Day 2).
Warning: The chart is an OCI artifact. There is no
helm repo addhere; the version should always be pinned with--version.
Save your progress? Sign up for free
Drill 4: CRDs, Versions and Channels
kubectl api-resources --api-group=gateway.networking.k8s.io \
| awk '{printf "%-20s %-30s %s\n", $1, $(NF-2), $NF}'Expected:
NAME APIVERSION KIND
backendtlspolicies gateway.networking.k8s.io/v1 BackendTLSPolicy
gatewayclasses gateway.networking.k8s.io/v1 GatewayClass
gateways gateway.networking.k8s.io/v1 Gateway
grpcroutes gateway.networking.k8s.io/v1 GRPCRoute
httproutes gateway.networking.k8s.io/v1 HTTPRoute
listenersets gateway.networking.k8s.io/v1 ListenerSet
referencegrants gateway.networking.k8s.io/v1 ReferenceGrant
tcproutes gateway.networking.k8s.io/v1 TCPRoute
tlsroutes gateway.networking.k8s.io/v1 TLSRoute
udproutes gateway.networking.k8s.io/v1 UDPRoute
All v1. With Gateway API v1.5, TLSRoute, ListenerSet and
ReferenceGrant v1 moved into the Standard channel, with
v1.6 TCPRoute and UDPRoute.
C='CRD:.metadata.name'
C+=',CHANNEL:.metadata.annotations.gateway\.networking\.k8s\.io/channel'
C+=',BUNDLE:.metadata.annotations.gateway\.networking\.k8s\.io/bundle-version'
kubectl get crd -o custom-columns="$C" | grep -E 'CRD|networking'Expected:
CRD CHANNEL BUNDLE
backendtlspolicies.gateway.networking.k8s.io experimental v1.6.1
gatewayclasses.gateway.networking.k8s.io experimental v1.6.1
gateways.gateway.networking.k8s.io experimental v1.6.1
grpcroutes.gateway.networking.k8s.io experimental v1.6.1
httproutes.gateway.networking.k8s.io experimental v1.6.1
listenersets.gateway.networking.k8s.io experimental v1.6.1
referencegrants.gateway.networking.k8s.io experimental v1.6.1
tcproutes.gateway.networking.k8s.io experimental v1.6.1
tlsroutes.gateway.networking.k8s.io experimental v1.6.1
udproutes.gateway.networking.k8s.io experimental v1.6.1
xbackends.gateway.networking.x-k8s.io experimental v1.6.1
xbackendtrafficpolicies.gateway.networking.x-k8s.io experimental v1.6.1
xmeshes.gateway.networking.x-k8s.io experimental v1.6.1
The Envoy Gateway chart ships the Experimental
channel of Gateway API v1.6.1. It is a superset of the Standard
channel: the same v1 resources plus experimental fields
(e.g. retry in HTTPRoute, Day 3) and x-k8s.io
resources.
| Channel | Content | Use |
|---|---|---|
| Standard | GA resources and fields, stable | Production |
| Experimental | Standard plus alpha fields and x-k8s.io types |
Lab, specific features |
In this book we use only Standard fields – except where a chapter explicitly says “experimental”.
Save your progress? Sign up for free
Drill 5: Ask the API Itself
kubectl explain gateway.spec.listeners | sed -n '/^FIELDS/,$p' | grep -E '^ [a-zA-Z]'
kubectl explain httproute.spec.rules | sed -n '/^FIELDS/,$p' | grep -E '^ [a-zA-Z]'Expected:
allowedRoutes <Object>
hostname <string>
name <string> -required-
port <integer> -required-
protocol <string> -required-
tls <Object>
backendRefs <[]Object>
filters <[]Object>
matches <[]Object>
name <string>
retry <Object>
sessionPersistence <Object>
timeouts <Object>
kubectl explain httproute.spec.rules.filters.type | sed -n '/ENUM/,/^$/p'Expected:
ENUM:
RequestHeaderModifier
ResponseHeaderModifier
RequestMirror
RequestRedirect
URLRewrite
ExtensionRef
CORS
ExternalAuth
This is the list that was scattered across annotations with Ingress.
ExtensionRef is the door for vendor-specific filters (Envoy
Gateway: HTTPRouteFilter, Day 10). You only see
retry, sessionPersistence and
ExternalAuth because the Experimental channel is
installed.
Save your progress? Sign up for free
Drill 6: Create a GatewayClass and Read Its Status
cat > ~/gw-lab/code/demo/gatewayclass.yaml <<'EOF'
# GatewayClass for Envoy Gateway (Day 1)
apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
name: eg
spec:
controllerName: gateway.envoyproxy.io/gatewayclass-controller
EOF
kubectl apply -f ~/gw-lab/code/demo/gatewayclass.yaml
kubectl get gatewayclassExpected:
gatewayclass.gateway.networking.k8s.io/eg created
NAME CONTROLLER ACCEPTED AGE
eg gateway.envoyproxy.io/gatewayclass-controller True 3s
kubectl get gatewayclass eg -o yaml | sed -n '/^status/,$p'Expected:
status:
conditions:
- lastTransitionTime: "2026-10-09T21:09:26Z"
message: Valid GatewayClass
observedGeneration: 1
reason: Accepted
status: "True"
type: Accepted
This is how you read every condition: type (what is
being checked), status (True/False/Unknown),
reason (machine-readable), message (for
humans) and observedGeneration (does the status refer to
the current spec?).
A short form for all the following days – a small helper script:
cat > ~/gw-lab/code/demo/conds.sh <<'EOF'
#!/usr/bin/env bash
# Shows the conditions of a Gateway API resource in compact form.
# Usage: conds.sh <kind> <name> [namespace]
# GatewayClass: own conditions · Gateway: additionally per listener
# Routes/Policies: conditions per parent (status.parents / status.ancestors)
set -euo pipefail
kind="$1"; name="$2"; ns="${3:-default}"
nl='{"\n"}'
c="{range .conditions[*]} {.type}={.status} ({.reason}): {.message}$nl{end}"
top="{range .status.conditions[*]}{.type}={.status} ({.reason}): {.message}$nl{end}"
case "$kind" in
gatewayclass|gc)
kubectl get gatewayclass "$name" -o jsonpath="$top" ;;
gateway|gtw)
lst="{range .status.listeners[*]}listener {.name}"
lst+=" (attachedRoutes={.attachedRoutes}):$nl$c{end}"
kubectl -n "$ns" get gateway "$name" -o jsonpath="$top$lst" ;;
*)
par="{range .status.parents[*]}parent {.parentRef.namespace}/"
par+="{.parentRef.name}/{.parentRef.sectionName}:$nl$c{end}"
anc="{range .status.ancestors[*]}ancestor {.ancestorRef.namespace}/"
anc+="{.ancestorRef.name}/{.ancestorRef.sectionName}:$nl$c{end}"
kubectl -n "$ns" get "$kind" "$name" -o jsonpath="$par$anc" ;;
esac
EOF
chmod +x ~/gw-lab/code/demo/conds.sh
export PATH="$HOME/gw-lab/code/demo:$PATH"
conds.sh gatewayclass egExpected:
Accepted=True (Accepted): Valid GatewayClass
Also add the PATH entry to ~/.zshrc or
~/.bashrc. From now on you call conds.sh and
gw-ip.sh without a path.
Save your progress? Sign up for free
Drill 7: No Status Is an Answer Too
cat <<'EOF' | kubectl apply -f -
apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
name: falsch
spec:
controllerName: example.com/gibt-es-nicht
EOF
kubectl get gatewayclass
kubectl get gatewayclass falsch -o jsonpath='{.status.conditions[*].reason}'; echoExpected:
gatewayclass.gateway.networking.k8s.io/falsch created
NAME CONTROLLER ACCEPTED AGE
eg gateway.envoyproxy.io/gatewayclass-controller True 10m
falsch example.com/gibt-es-nicht Unknown 3s
Pending
Unknown/Pending is the default the API
server enters on creation. No controller has claimed the class – Envoy
Gateway ignores everything that does not carry its
controllerName. This is the most common source of errors
when switching implementations: the wrong class name on the Gateway, and
nothing happens.
kubectl delete gatewayclass falsch
kubectl -n shop delete ingress shopExpected:
gatewayclass.gateway.networking.k8s.io "falsch" deleted
ingress.networking.k8s.io "shop" deleted from shop namespace
Save your progress? Sign up for free
Checkpoint
check() { if eval "$2" >/dev/null 2>&1; then echo "✔ $1"; else echo "✘ $1"; fi; }
check "Envoy Gateway verfügbar" \
'kubectl -n envoy-gateway-system wait deploy/envoy-gateway \
--for=condition=Available --timeout=5s'
check "HTTPRoute-CRD aus Bundle v1.6.x" \
'kubectl get crd httproutes.gateway.networking.k8s.io \
-o jsonpath="{.metadata.annotations}" | grep -q "bundle-version\":\"v1.6"'
check "GatewayClass eg akzeptiert" \
'kubectl wait gatewayclass/eg --for=condition=Accepted --timeout=5s'
check "GatewayClass falsch entfernt" '! kubectl get gatewayclass falsch'
check "conds.sh im PATH" 'command -v conds.sh'Expected:
✔ Envoy Gateway verfügbar
✔ HTTPRoute-CRD aus Bundle v1.6.x
✔ GatewayClass eg akzeptiert
✔ GatewayClass falsch entfernt
✔ conds.sh im PATH
Challenge
All Gateway API resources are served as v1. Find the one
CRD that still stores its objects in etcd in a different version.
Hint: Every version in spec.versions
has a field storage: true|false.
Solution
kubectl get crd -o json | jq -r '.items[]
| select(.spec.group == "gateway.networking.k8s.io")
| "\(.metadata.name) storage=\(.spec.versions[] | select(.storage) | .name)"'Expected:
backendtlspolicies.gateway.networking.k8s.io storage=v1
gatewayclasses.gateway.networking.k8s.io storage=v1
gateways.gateway.networking.k8s.io storage=v1
grpcroutes.gateway.networking.k8s.io storage=v1
httproutes.gateway.networking.k8s.io storage=v1
listenersets.gateway.networking.k8s.io storage=v1
referencegrants.gateway.networking.k8s.io storage=v1beta1
tcproutes.gateway.networking.k8s.io storage=v1
tlsroutes.gateway.networking.k8s.io storage=v1
udproutes.gateway.networking.k8s.io storage=v1
ReferenceGrant has been available as v1 since v1.5, but
it is still stored as v1beta1. That does not matter to you
as a user – but during the CRD upgrade (Day 12) it is exactly the spot
where a storage migration may become due.
Save your progress? Sign up for free
Enterprise Note
- In production, the Gateway API CRDs belong to the platform team and
are managed separately from the controller (Envoy Gateway: chart
gateway-crds-helm, in the main chartcrds.enabled=false). Several implementations share the same CRDs. - Prefer the Standard channel. Since v1.5, the
ValidatingAdmissionPolicy
safe-upgrades.gateway.networking.k8s.ioprevents switching from Standard to Experimental and downgrades below v1.5. - Always check the version against the controller’s compatibility matrix: Envoy Gateway v1.9 is built for Gateway API v1.6.1.
- Cut RBAC along roles: GatewayClass only for cluster admins, Gateways only for the platform team, Routes for app teams in their namespaces (Day 7).