Skip to content
Hands-on IT IT Drills

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.conditions whether 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 ingressclass

Expected:

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.io

Expected:

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

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

Expected (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 add here; 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 gatewayclass

Expected:

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 eg

Expected:

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}'; echo

Expected:

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 shop

Expected:

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 chart crds.enabled=false). Several implementations share the same CRDs.
  • Prefer the Standard channel. Since v1.5, the ValidatingAdmissionPolicy safe-upgrades.gateway.networking.k8s.io prevents 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).