Mastering Kubernetes Gateway API with Istio: A Hands‑On Guide

Kubernetes Gateway API has just reached GA, offering a more standard and powerful set of API resources for exposing cluster services externally. This article introduces the Gateway API resources and uses Istio as an example to show how they interconnect, enabling traffic flow to backend services.

Background

Allowing external communication with services inside a Kubernetes cluster is a fundamental task for administrators. The built‑in Service object provides limited IP‑level functionality and lacks application‑layer routing based on DNS hostnames or HTTP paths, so Kubernetes introduced the Ingress API for such routing.

Ingress, however, has limitations: it focuses only on HTTP traffic, making it unsuitable for UDP/TCP or other protocols, and it mixes infrastructure and application configuration, complicating fine‑grained RBAC. Separating these concerns is crucial for platform engineering.

Setting Up the Test Environment

The example uses K3s with Traefik disabled, installs the Gateway API CRDs, and deploys Istio in minimal profile:

$ curl -sfL https://get.k3s.io | INSTALL_K3S_EXEC="server --disable=traefik" sh -

# Install the CRDs
$ kubectl get crd gateways.gateway.networking.k8s.io &> /dev/null || { kubectl kustomize "github.com/kubernetes-sigs/gateway-api/config/crd?ref=v0.8.0" | kubectl apply -f -; }
# Install Istio
$ istioctl install --set profile=minimal -y

Deploy a simple Nginx workload:

# Deployment.yaml
---
apiVersion: apps/v1
kind: Deployment
metadata:
  labels:
    app: nginx
  name: nginx
spec:
  replicas: 3
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - image: nginx:latest
        name: nginx
---
# Service.yaml
apiVersion: v1
kind: Service
metadata:
  labels:
    app: nginx
  name: nginx
  namespace: default
spec:
  ports:
  - port: 80
    protocol: TCP
    targetPort: 80
  selector:
    app: nginx
  type: ClusterIP

$ kubectl apply -f Deployment.yaml
deployment.apps/nginx created
$ kubectl apply -f Service.yaml
service/nginx created

Understanding Gateway API Resources

Three resource types are essential:

GatewayClass

Gateway

Route resources such as HTTPRoute (GA includes only HTTPRoute)

These resources are decoupled, allowing stronger RBAC and clearer separation of concerns.

Exploring GatewayClass

GatewayClass

is analogous to IngressClass or StorageClass. It defines the type of Gateway that can be created and is typically supplied by the infrastructure platform or an Ingress controller like Istio. Istio provides two classes:

$ kubectl get gatewayclass
NAME           CONTROLLER                    ACCEPTED   AGE
istio-remote   istio.io/unmanaged-gateway    True       19h
istio          istio.io/gateway-controller   True       19h

$ kubectl get gatewayclass istio -o yaml
apiVersion: gateway.networking.k8s.io/v1beta1
kind: GatewayClass
metadata:
  name: istio
spec:
  controllerName: istio.io/gateway-controller
  description: The default Istio GatewayClass
status:
  conditions:
  - type: Accepted
    status: "True"
    reason: Accepted
    message: Handled by Istio controller

Creating a Gateway

A Gateway represents a load‑balancer instance provisioned by the underlying provider. The following example creates a Gateway that listens on port 8080 for *.example.com HTTP requests:

# Gateway.yaml
---
apiVersion: gateway.networking.k8s.io/v1beta1
kind: Gateway
metadata:
  name: tutorial-gw
  namespace: default
spec:
  gatewayClassName: istio
  listeners:
  - name: default
    hostname: "*.example.com"
    port: 8080
    protocol: HTTP
    allowedRoutes:
      namespaces:
        from: All

$ kubectl get pods
NAME                                READY   STATUS    RESTARTS   AGE
tutorial-gw-istio-65bfccf7c-45c4w   1/1     Running   2 (6m31s ago)   18h
$ kubectl get service
tutorial-gw-istio   LoadBalancer   10.43.126.90   192.168.122.10   15021:31348/TCP,8080:31728/TCP   18h

The Gateway does not contain routing rules; those are defined separately, preserving RBAC boundaries.

Creating a Route

Ingress supports only HTTP/HTTPS, while Gateway API adds support for TCP, TLS, GRPC, etc. The GA version currently includes HTTPRoute. The example below attaches an HTTPRoute to the previously created Gateway, routing all traffic to the Nginx service:

# HTTPRoute.yaml
---
apiVersion: gateway.networking.k8s.io/v1beta1
kind: HTTPRoute
metadata:
  name: tutorial-route
  namespace: default
spec:
  parentRefs:
  - group: gateway.networking.k8s.io
    kind: Gateway
    name: tutorial-gw
  rules:
  - backendRefs:
    - group: ""
      kind: Service
      name: nginx
      port: 80
      weight: 1
    matches:
    - path:
        type: PathPrefix
        value: "/"

$ kubectl apply -f HTTPRoute.yaml
httproute.gateway.networking.k8s.io/tutorial-route created
$ kubectl get httproute
NAME             HOSTNAMES   AGE
tutorial-route               6s

Putting It All Together

The Gateway API splits what used to be a single resource into multiple components. The following diagram illustrates their relationships:

Quick Recap

GatewayClass

defines the type of Gateway that can be deployed, usually supplied by the platform (e.g., Istio). Gateway is the concrete load‑balancer instance; it references a GatewayClass and abstracts away infrastructure details. HTTPRoute (or other route resources) contains the actual traffic‑routing rules and attaches to a specific Gateway.

To test the setup, send an HTTP request with the appropriate Host header:

$ curl -H "Host: www.example.com" 192.168.122.10:8080
<!DOCTYPE html>
<html>
<head>
<title>Welcome to nginx!</title>
</head>

You have now successfully configured the first set of resources using the new Gateway API!