Detailed Overview of Kubernetes Gateway API

Gateway Development

Initially Kubernetes exposed services using LoadBalancer and NodePort, which became insufficient as clusters grew. Ingress API was introduced to standardize HTTP exposure, but it has limitations such as supporting only HTTP/HTTPS and requiring annotations for advanced routing. Third‑party gateways like Istio and APISIX added rich traffic management features, prompting the creation of the next‑generation Gateway API in Kubernetes 1.19.

Surrounding Ecosystem

Several projects have announced or plan support for Gateway API, including:

Istio (experimental support in v1.9)

Linkerd (support in v2.10)

Contour (support in v1.14.0)

Flagger (support in v0.25)

HAProxy Ingress Controller

Traefik (support from v2.5)

Apache APISIX

Major cloud providers are also tracking Gateway API progress, indicating its growing adoption despite being in early development.

Use Cases

Gateway API can be used to implement API gateways, traffic control, and network security (TLS termination, OAuth2, JWT, etc.) by managing inbound and internal traffic with a unified configuration.

Gateway API Detailed Overview

Role‑Based Design

Gateway API separates concerns by role: infrastructure owners define GatewayClass , platform admins create Gateway objects, and developers configure HTTPRoute , TCPRoute , etc. This decouples configuration and allows shared gateways across teams while preserving control boundaries.

A GatewayClass defines a set of shared configurations and is associated with a controller. The controller watches GatewayClass and Gateway objects and creates or updates the underlying gateway infrastructure.

kind: GatewayClass
apiVersion: gateway.networking.k8s.io/v1beta1
metadata:
  name: istio
spec:
  controllerName: istio.io/gateway-controller  # associate with Istio controller

Gateway

A Gateway represents an entry point for external traffic. It references a GatewayClass and defines listeners (hostname, port, protocol, TLS settings, allowed routes).

GatewayClassName : required reference to a GatewayClass .

Listeners : define hostnames, ports, protocols, TLS configuration, and which routes can bind.

Addresses : optional external addresses (IP, hostname, load balancer).

TLS

Two TLS modes are supported:

Terminate : decrypts traffic at the gateway and forwards plaintext.

Passthrough : forwards encrypted traffic unchanged.

Listener Protocol

TLS Mode

Route Type

TLS

Passthrough

TLSRoute

TLS

Terminate

TCPRoute

HTTPS

Terminate

HTTPRoute

apiVersion: gateway.networking.k8s.io/v1beta1
kind: Gateway
metadata:
  name: gateway-istio
spec:
  gatewayClassName: istio
  listeners:
  - name: foo-https
    protocol: HTTPS
    port: 443
    hostname: tls.example.com
    tls:
      mode: Terminate
      certificateRefs:
      - kind: Secret
        name: foo-example-com-cert

ReferenceGrant

Enables cross‑namespace references, allowing a Gateway or HTTPRoute in one namespace to reference a Secret or Service in another.

apiVersion: gateway.networking.k8s.io/v1beta1
kind: HTTPRoute
metadata:
  name: foo
  namespace: foo
spec:
  rules:
  - matches:
    - path: /bar
    backendRefs:
    - name: bar
      namespace: bar
---
apiVersion: gateway.networking.k8s.io/v1beta1
kind: ReferenceGrant
metadata:
  name: bar
  namespace: bar
spec:
  from:
  - group: gateway.networking.k8s.io
    kind: HTTPRoute
    namespace: foo
  to:
  - group: ""
    kind: Service

Route Types

A Gateway can bind multiple routes. Supported route resources are HTTPRoute , TLSRoute , TCPRoute , and GRPCRoute .

HTTPRoute

Used for HTTP/HTTPS traffic, supporting hostnames, path matching, header matching, weight‑based traffic splitting, request/response header modification, redirects, and more.

apiVersion: gateway.networking.k8s.io/v1beta1
kind: HTTPRoute
metadata:
  name: httproute-example
spec:
  parentRefs:
  - name: gateway-istio
  hostnames:
  - "zcy.cai-inc.com"
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /monitor
    backendRefs:
    - name: monitor-center1
      port: 6099
      weight: 90
    - name: monitor-center2
      port: 6099
      weight: 10
  - matches:
    - headers:
      - name: env
        type: Exact
        value: prod
      path:
        type: PathPrefix
        value: "/api2/otel"
    filters:
    - type: RequestHeaderModifier
      requestHeaderModifier:
        add:
        - name: cookie
          value: test1
    - type: ResponseHeaderModifier
      responseHeaderModifier:
        add:
        - name: X-Header-Add-1
          value: header-add-1
        - name: X-Header-Add-2
          value: header-add-2
    - type: RequestRedirect
      requestRedirect:
        scheme: https
        statusCode: 301
    backendRefs:
    - name: otel-dashboard
      port: 7099

TLSRoute

Routes TLS connections based on SNI without HTTP‑level processing.

TCPRoute

Routes raw TCP traffic, useful for protocols like MySQL or Redis. It binds to listeners with protocol TCP.

apiVersion: gateway.networking.k8s.io/v1beta1
kind: Gateway
metadata:
  name: tcp-gateway
spec:
  gatewayClassName: istio
  listeners:
  - name: foo
    protocol: TCP
    port: 8080
    allowedRoutes:
      kinds:
      - kind: TCPRoute
---
apiVersion: gateway.networking.k8s.io/v1alpha2
kind: TCPRoute
metadata:
  name: tcp-app-1
spec:
  parentRefs:
  - name: tcp-gateway
    sectionName: foo
  rules:
  - backendRefs:
    - name: foo-service
      port: 6000

GRPCRoute

Routes gRPC traffic, matching on service, method, and headers. Requires HTTP/2 support on the gateway.

apiVersion: gateway.networking.k8s.io/v1alpha2
kind: GRPCRoute
metadata:
  name: grpcroute
spec:
  parentRefs:
  - name: gateway-istio
  hostnames:
  - my.example.com
  rules:
  - matches:
    - method:
        service: com.example.User
        method: Login
      headers:
      - type: Exact
        name: version
        value: "2"
    backendRefs:
    - name: foo-svc
      port: 50051

Route Binding

Routes bind to gateways via the parentRefs field. Gateways define allowedRoutes to restrict which route kinds, namespaces, or selectors may attach. Binding is bidirectional: both gateway owner and route owner must agree.

Binding Models

One‑to‑one: a dedicated gateway for a single team.

One‑to‑many: a shared gateway used by multiple teams.

Many‑to‑one: a route attached to multiple gateways for multi‑cloud exposure.

Getting Started with Gateway API

Install the CRDs

$ wget https://github.com/kubernetes-sigs/gateway-api/releases/download/v0.6.1/standard-install.yaml
$ kubectl apply -f standard-install.yaml
# Verify CRDs
$ kubectl get crd | grep networking.k8s.io

Install a Gateway API controller (e.g., Istio)

# Download Istio 1.17.2
$ wget https://github.com/istio/istio/releases/download/1.17.2/istio-1.17.2-linux-amd64.tar.gz
$ tar -zxvf istio-1.17.2-linux-amd64.tar.gz
$ cd istio-1.17.2
$ export PATH=$PWD/bin:$PATH
$ istioctl install --set profile=minimal -y
# Verify GatewayClass
$ kubectl get gatewayclass
NAME    CONTROLLER                 ACCEPTED   AGE
istio   istio.io/gateway-controller   True      6s

Configure a Gateway and HTTPRoute

apiVersion: v1
kind: Namespace
metadata:
  name: istio-ingress
---
apiVersion: gateway.networking.k8s.io/v1beta1
kind: Gateway
metadata:
  name: gateway
  namespace: istio-ingress
spec:
  gatewayClassName: istio
  listeners:
  - name: default
    hostname: "*.example.com"
    port: 80
    protocol: HTTP
    allowedRoutes:
      namespaces:
        from: All
---
apiVersion: gateway.networking.k8s.io/v1beta1
kind: HTTPRoute
metadata:
  name: http
  namespace: default
spec:
  parentRefs:
  - name: gateway
    namespace: istio-ingress
  hostnames:
  - "httpbin.example.com"
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /get
    backendRefs:
    - name: httpbin
      port: 8000

After applying the manifests, the gateway creates a Service and Deployment automatically. Verify the resources and obtain the external address:

$ kubectl get gateway -n istio-ingress
NAME      CLASS   ADDRESS                                 PROGRAMMED   AGE
gateway   istio   gateway.istio-ingress.svc.cluster.local:80   26s

$ kubectl get svc -n istio-ingress
NAME      TYPE           CLUSTER-IP      EXTERNAL-IP   PORT(S)                         AGE
gateway   LoadBalancer   10.96.0.36
15021:31764/TCP,80:32701/TCP   36s

# Wait for the load balancer IP
$ export INGRESS_HOST=$(kubectl get gateways.gateway.networking.k8s.io gateway -n istio-ingress -o jsonpath='{.status.addresses[*].value}')

Test the routing:

$ curl -s -I -H Host:httpbin.example.com "http://$INGRESS_HOST/get"
HTTP/1.1 200 OK
...

Additional Features – Horizontal Pod Autoscaling

Gateway pods can be scaled with an HPA by adding resource requests/limits to the generated Deployment and creating an HPA that targets it.

apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: gateway
  namespace: istio-ingress
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: gateway
  minReplicas: 2
  maxReplicas: 5
  metrics:
  - type: Resource
    resource:
      name: cpu
      target:
        type: Utilization
        averageUtilization: 50
---
apiVersion: policy/v1
kind: PodDisruptionBudget
metadata:
  name: gateway
  namespace: istio-ingress
spec:
  minAvailable: 1
  selector:
    matchLabels:
      istio.io/gateway-name: gateway

Recruitment Notice

The Zero technology team in Hangzhou is looking for passionate engineers to join a fast‑growing group working on cloud‑native, blockchain, AI, low‑code platforms, middleware, big data, and more. If you are interested, please contact zcy‑tc@cai‑inc.com.