Mastering Kubernetes Gateway API on GKE: A Step‑by‑Step Guide

Gateway API

(formerly Service API) is an open‑source project managed by the SIG‑NETWORK community ( gateway-api.sigs.k8s.io ). It was created because the traditional Ingress resource cannot satisfy many networking requirements, and extensions via annotations or CRDs are cumbersome. Gateway API introduces a role‑oriented, extensible interface for service networking.

Gateway API defines a set of Kubernetes API resources, including GatewayClass, Gateway, HTTPRoute, TCPRoute, and Service, which together model a wide range of network use cases.

Gateway API Value and Positioning

Provides a cross‑namespace Ingress mechanism, allowing services in multiple namespaces to share a single L7 LoadBalancer.

Enables multi‑tenant Ingress by separating HTTPRoute from Gateway, so route designers can share an L7 LoadBalancer.

Supports blue‑green and canary deployments within the same namespace via simple definitions in HTTPRoute.

Allows A/B testing based on hostname, header, or sub‑path.

Gateway API Introduction

The API is organized around three main roles: GatewayClass – provided by the cloud provider or Kubernetes. Gateway – instantiated by the network platform using a specific GatewayClass. HTTPRoute – selected by application teams to connect services to a gateway.

GKE currently offers four gateway classes: gke-l7-rilb – regional internal HTTP(S) load balancer (single‑cluster). gke-l7-gxlb – global external HTTP(S) load balancer (single‑cluster). gke-l7-rilb-mc – multi‑cluster regional internal load balancer. gke-l7-gxlb-mc – multi‑cluster global external load balancer.

Gateway Deployment

GKE versions 1.20+ support Gateway API in the RAPID channel. Public beta is available in the following regions: us‑west1, us‑east1, us‑central1, europe‑west4, europe‑west3, europe‑west2, europe‑west1, asia‑southeast1.

First, create a private GKE cluster (adjust shawn.tfvars and the bucket name in config.tf for remote GCS state). The cluster uses an internal load balancer and a proxy‑only subnet for Envoy.

Deploy Gateway CRDs

kubectl kustomize "github.com/kubernetes-sigs/gateway-api/config/crd?ref=v0.3.0" | kubectl apply -f -
# Verify installed GatewayClasses
kubectl get gatewayclass

Sample output:

NAME          CONTROLLER                     AGE
gke-l7-gxlb   networking.gke.io/gateway      23h
gke-l7-rilb   networking.gke.io/gateway      23h

Deploy a Gateway

kind: Gateway
apiVersion: networking.x-k8s.io/v1alpha1
metadata:
  name: internal-http
spec:
  gatewayClassName: gke-l7-rilb
  listeners:
  - protocol: HTTP
    port: 80
    routes:
      kind: HTTPRoute
      selector:
        matchLabels:
          gateway: internal-http
      namespaces:
        from: "All"

The gateway can be associated with routes by kind, label selector, or namespaces.from. To enable cross‑namespace sharing, set namespaces.from to All.

After applying, verify:

kubectl describe gateway internal-http

Deploy Services and HTTPRoutes

Two example services are deployed: store in the default namespace and site in the site namespace.

store HTTPRoute (default namespace)

kind: HTTPRoute
apiVersion: networking.x-k8s.io/v1alpha1
metadata:
  name: store
  labels:
    gateway: internal-http
spec:
  hostnames:
  - "store.example.com"
  rules:
  - forwardTo:
    - serviceName: store-v1
      port: 8080
      weight: 50
    - serviceName: store-v2
      port: 8080
      weight: 50
  - matches:
    - headers:
        type: Exact
        values:
          env: canary
      forwardTo:
      - serviceName: store-v2
        port: 8080
  - matches:
    - path:
        type: Prefix
        value: /de
      forwardTo:
      - serviceName: store-german
        port: 8080

This route demonstrates hostname routing, header‑based canary routing, prefix‑based routing, and weighted default routing.

site HTTPRoute (site namespace)

kind: HTTPRoute
apiVersion: networking.x-k8s.io/v1alpha1
metadata:
  name: site
  namespace: site
  labels:
    gateway: internal-http
spec:
  gateways:
    allow: FromList
    gatewayRefs:
    - name: internal-http
      namespace: default
  hostnames:
  - "site.example.com"
  rules:
  - forwardTo:
    - serviceName: site-v1
      port: 8080

Because the HTTPRoute resides in a different namespace from the Gateway, a gatewayRefs entry is required.

Testing the Deployment

Obtain the internal load balancer IP:

kubectl get gateway internal-http -o jsonpath='{.status.addresses[0].value}'
# Example output: 10.81.68.140

From a GCE VM in the same VPC, issue curl commands:

# Hostname routing to the site service
curl -H "host: site.example.com" 10.81.68.140

# Header‑based canary routing for store
curl -H "host: store.example.com" -H "env: canary" 10.81.68.140

# Prefix routing to German store
curl -H "host: store.example.com" 10.81.68.140/de

# Default weighted routing
curl -H "host: store.example.com" 10.81.68.140

Each request returns JSON showing the selected pod, confirming that hostname, header, prefix, and weighted routing work as expected.

Original article: Medium – k8s‑gateway‑api‑contour‑progress‑version