Kubernetes Gateway API

Introduction

The classic Kubernetes Ingress API has served the community well, but it was never designed for everything we now need from HTTP routing: traffic splitting, header-based routing, gRPC, TLS passthrough, cross-namespace references, or multi-team access controls. Gateway API (gateway.networking.k8s.io) was designed from scratch to solve all of that, and as of v1.5.0 it is the standard way to expose services in Kubernetes.

I made the switch from Ingress to Gateway API about a year ago and I have not looked back. This article covers everything I use day-to-day: GatewayClass, Gateway, HTTPRoute, GRPCRoute, TLSRoute, ReferenceGrant, and policy attachments — all with the Go microservice from the previous article as the backend.

---

Why Replace Ingress?

Capability	Ingress	Gateway API
Role separation (infra vs dev)	No	Yes
Traffic splitting (weight-based)	Annotation hack	Native
Header/method-based routing	Annotation hack	Native
gRPC support	No	GRPCRoute (standard)
TLS termination vs passthrough	Annotation hack	TLSRoute
Cross-namespace routing	No	ReferenceGrant
Multi-protocol (TCP/UDP)	No	TCPRoute/UDPRoute (experimental)
Portable YAML across controllers	No (annotations differ)	Yes

Ingress annotations are implementation-specific. Gateway API is portable across Nginx, Istio, Envoy Gateway, HAProxy, and Cilium.

---

Installing Gateway API CRDs (v1.5.0)

Gateway API CRDs are not included in Kubernetes core — install them separately.

Standard Channel (production-ready)

Standard channel includes: GatewayClass, Gateway, HTTPRoute, GRPCRoute, TLSRoute, ReferenceGrant, BackendTLSPolicy.

# Install standard channel CRDs
kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.5.0/standard-install.yaml

# Verify
kubectl get crd | grep gateway.networking.k8s.io

Expected output:

backendlbpolicies.gateway.networking.k8s.io
backendtlspolicies.gateway.networking.k8s.io
gatewayclasses.gateway.networking.k8s.io
gateways.gateway.networking.k8s.io
grpcroutes.gateway.networking.k8s.io
httproutes.gateway.networking.k8s.io
referencegrants.gateway.networking.k8s.io
tlsroutes.gateway.networking.k8s.io

Experimental Channel (additional resources)

Experimental channel adds TCPRoute, UDPRoute, BackendTrafficPolicy.

kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.5.0/experimental-install.yaml

Install a Gateway Controller

The CRDs define the API. You still need a controller. I use Envoy Gateway for standalone clusters:

helm repo add envoy-gateway https://charts.gateway.envoyproxy.io
helm repo update
helm install envoy-gateway envoy-gateway/gateway-helm \
  --namespace envoy-gateway-system \
  --create-namespace \
  --version v1.4.1
kubectl wait --timeout=5m \
  -n envoy-gateway-system deployment/envoy-gateway --for=condition=Available

For Istio environments, the Istio istiod controller handles Gateway API natively since Istio 1.18.

---

The Role Model

Gateway API is designed around three personas — this maps directly to real team structures:

Persona	Typical Role	Manages
Ian (Infrastructure Provider)	Platform SRE	GatewayClass — defines which controller handles traffic
Chihiro (Cluster Operator)	Cluster Admin	Gateway — defines listeners (port, protocol, TLS certs)
Ana (Developer)	Service Owner	HTTPRoute / GRPCRoute — attaches routes to a Gateway

This separation means developers can configure their own routing without cluster admin access — they just create HTTPRoutes in their namespace.

---

GatewayClass

GatewayClass is a cluster-scoped resource defining the controller type. One per controller implementation.

# gatewayclass.yaml
apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: envoy
spec:
  controllerName: gateway.envoyproxy.io/gatewayclass-controller
  description: "Envoy Gateway — managed by platform team"

kubectl apply -f gatewayclass.yaml
kubectl get gatewayclass
# NAME    CONTROLLER                                             ACCEPTED
# envoy   gateway.envoyproxy.io/gatewayclass-controller         True

---

Gateway

Gateway describes a traffic entry point. Cluster operators create Gateways. Each Gateway has one or more Listeners.

# gateway.yaml
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: production-gateway
  namespace: gateway-system
spec:
  gatewayClassName: envoy
  listeners:
    - name: http
      port: 80
      protocol: HTTP
      allowedRoutes:
        namespaces:
          from: Selector
          selector:
            matchLabels:
              gateway-access: "true"    # only labeled namespaces can attach

    - name: https
      port: 443
      protocol: HTTPS
      tls:
        mode: Terminate
        certificateRefs:
          - kind: Secret
            name: production-tls-cert
            namespace: gateway-system
      allowedRoutes:
        namespaces:
          from: Selector
          selector:
            matchLabels:
              gateway-access: "true"

Label the production namespace so routes can attach:

kubectl label namespace production gateway-access=true

Create the TLS secret:

kubectl create secret tls production-tls-cert \
  --cert=./fullchain.pem \
  --key=./privkey.pem \
  -n gateway-system

---

HTTPRoute

HTTPRoute is the core routing resource for L7 HTTP traffic. Developers create HTTPRoutes in their own namespace.

Basic Path Routing

# httproute-basic.yaml
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: goapp-route
  namespace: production
spec:
  parentRefs:
    - name: production-gateway
      namespace: gateway-system
      sectionName: https            # attach to the https listener only
  hostnames:
    - "api.example.com"
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /api/v1
      backendRefs:
        - name: goapp
          port: 8080
          weight: 100

Header and Method Matching

# httproute-matching.yaml
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: goapp-route-advanced
  namespace: production
spec:
  parentRefs:
    - name: production-gateway
      namespace: gateway-system
      sectionName: https
  hostnames:
    - "api.example.com"
  rules:
    # Route POST requests to a separate write service
    - matches:
        - path:
            type: PathPrefix
            value: /api/v1/items
          method: POST
      backendRefs:
        - name: goapp-write
          port: 8080
    # Route GET requests to the read service
    - matches:
        - path:
            type: PathPrefix
            value: /api/v1/items
          method: GET
      backendRefs:
        - name: goapp-read
          port: 8080
    # Internal API via custom header
    - matches:
        - headers:
            - name: X-Internal-API
              value: "true"
          path:
            type: PathPrefix
            value: /internal
      backendRefs:
        - name: goapp-internal
          port: 9090

Traffic Splitting (Canary Deployment)

# httproute-canary.yaml
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: goapp-canary
  namespace: production
spec:
  parentRefs:
    - name: production-gateway
      namespace: gateway-system
      sectionName: https
  hostnames:
    - "api.example.com"
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /api/v1
      backendRefs:
        - name: goapp         # stable v1.0.0
          port: 8080
          weight: 90          # 90% of traffic
        - name: goapp-canary  # new v1.1.0
          port: 8080
          weight: 10          # 10% of traffic

Gradually shift weight from 90/10 → 50/50 → 0/100 as you gain confidence.

HTTP Redirect

# httproute-redirect.yaml — HTTP → HTTPS redirect
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: http-to-https
  namespace: production
spec:
  parentRefs:
    - name: production-gateway
      namespace: gateway-system
      sectionName: http             # attach to http listener
  hostnames:
    - "api.example.com"
  rules:
    - filters:
        - type: RequestRedirect
          requestRedirect:
            scheme: https
            statusCode: 301

Request/Response Header Manipulation

# httproute-headers.yaml
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: goapp-with-headers
  namespace: production
spec:
  parentRefs:
    - name: production-gateway
      namespace: gateway-system
  hostnames:
    - "api.example.com"
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /api/v1
      filters:
        - type: RequestHeaderModifier
          requestHeaderModifier:
            add:
              - name: X-Request-Source
                value: gateway
            remove:
              - X-Internal-Debug
        - type: ResponseHeaderModifier
          responseHeaderModifier:
            add:
              - name: Strict-Transport-Security
                value: "max-age=31536000; includeSubDomains"
              - name: X-Content-Type-Options
                value: "nosniff"
      backendRefs:
        - name: goapp
          port: 8080

---

GRPCRoute

GRPCRoute handles gRPC traffic (stable since Gateway API v1.1). Here I extend the Go microservice with a gRPC server.

main.go additions for gRPC:

package main

import (
	"context"
	"log/slog"
	"net"
	"os"

	"google.golang.org/grpc"
	"google.golang.org/grpc/reflection"

	// Generated from proto
	pb "github.com/example/goapp/proto/items/v1"
)

type itemsServer struct {
	pb.UnimplementedItemsServiceServer
}

func (s *itemsServer) GetItem(ctx context.Context, req *pb.GetItemRequest) (*pb.GetItemResponse, error) {
	return &pb.GetItemResponse{
		Item: &pb.Item{Id: req.Id, Name: "Widget A", Price: 100},
	}, nil
}

func startGRPC(logger *slog.Logger) {
	lis, _ := net.Listen("tcp", ":9090")
	srv := grpc.NewServer()
	pb.RegisterItemsServiceServer(srv, &itemsServer{})
	reflection.Register(srv)          // enables grpcurl in development
	logger.Info("gRPC server listening", "addr", ":9090")
	if err := srv.Serve(lis); err != nil {
		logger.Error("gRPC server error", "err", err)
		os.Exit(1)
	}
}

GRPCRoute YAML:

# grpcroute.yaml
apiVersion: gateway.networking.k8s.io/v1
kind: GRPCRoute
metadata:
  name: goapp-grpc
  namespace: production
spec:
  parentRefs:
    - name: production-gateway
      namespace: gateway-system
      sectionName: https
  hostnames:
    - "grpc.example.com"
  rules:
    # Route all methods of ItemsService
    - matches:
        - method:
            type: Exact
            service: items.v1.ItemsService
      backendRefs:
        - name: goapp-grpc
          port: 9090
    # Route specific method
    - matches:
        - method:
            type: Exact
            service: items.v1.ItemsService
            method: GetItem
      filters:
        - type: RequestHeaderModifier
          requestHeaderModifier:
            add:
              - name: X-Grpc-Route
                value: get-item
      backendRefs:
        - name: goapp-grpc
          port: 9090
---
# Service for gRPC
apiVersion: v1
kind: Service
metadata:
  name: goapp-grpc
  namespace: production
spec:
  selector:
    app: goapp
  ports:
    - name: grpc
      port: 9090
      targetPort: 9090
      protocol: TCP
  type: ClusterIP

---

TLSRoute

TLSRoute handles TLS passthrough — the Gateway does not terminate TLS, it forwards the TCP stream based on SNI (Server Name Indication).

# gateway-tls-passthrough.yaml — add a TLS passthrough listener to the Gateway
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: production-gateway
  namespace: gateway-system
spec:
  gatewayClassName: envoy
  listeners:
    # ... existing listeners ...
    - name: tls-passthrough
      port: 8443
      protocol: TLS
      tls:
        mode: Passthrough           # do NOT terminate TLS
      allowedRoutes:
        kinds:
          - kind: TLSRoute
        namespaces:
          from: Selector
          selector:
            matchLabels:
              gateway-access: "true"
---
# tlsroute.yaml
apiVersion: gateway.networking.k8s.io/v1alpha2
kind: TLSRoute
metadata:
  name: goapp-tls
  namespace: production
spec:
  parentRefs:
    - name: production-gateway
      namespace: gateway-system
      sectionName: tls-passthrough
  hostnames:
    - "secure.example.com"
  rules:
    - backendRefs:
        - name: goapp-tls
          port: 8443

---

Cross-Namespace References with ReferenceGrant

By default, a Route in namespace production cannot reference a Service in namespace shared-services. ReferenceGrant explicitly allows it.

# referencegrant.yaml — in the shared-services namespace
apiVersion: gateway.networking.k8s.io/v1beta1
kind: ReferenceGrant
metadata:
  name: allow-production-to-shared
  namespace: shared-services
spec:
  from:
    - group: gateway.networking.k8s.io
      kind: HTTPRoute
      namespace: production           # only routes from this namespace
  to:
    - group: ""
      kind: Service                   # can reference Services

# httproute referencing cross-namespace service
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: goapp-shared-cache
  namespace: production
spec:
  parentRefs:
    - name: production-gateway
      namespace: gateway-system
  hostnames:
    - "api.example.com"
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /cache
      backendRefs:
        - name: cache-service
          namespace: shared-services  # cross-namespace reference
          port: 6379
          kind: Service
          group: ""

---

BackendTLSPolicy

BackendTLSPolicy configures TLS from the Gateway to the backend service (not to be confused with TLSRoute which is client-facing).

# backendtlspolicy.yaml
apiVersion: gateway.networking.k8s.io/v1alpha3
kind: BackendTLSPolicy
metadata:
  name: goapp-backend-tls
  namespace: production
spec:
  targetRefs:
    - group: ""
      kind: Service
      name: goapp
  validation:
    caCertificateRefs:
      - kind: ConfigMap
        name: goapp-ca-cert
        group: ""
    hostname: goapp.production.svc.cluster.local

---

Inspecting Gateway API Resources

# Check Gateway status and listeners
kubectl get gateway -n gateway-system production-gateway -o yaml
kubectl describe gateway production-gateway -n gateway-system

# Check HTTPRoute status — shows which parentRef it attached to
kubectl get httproute -n production
kubectl describe httproute goapp-route -n production

# See route conditions
kubectl get httproute goapp-route -n production \
  -o jsonpath='{.status.parents[*].conditions}' | jq .

# Check GatewayClass acceptance
kubectl get gatewayclass envoy -o jsonpath='{.status.conditions}' | jq .

The .status.parents[].conditions field tells you whether the route attached successfully — this is the first place to look when traffic is not flowing.

---

Complete Example: Deploying the Go Microservice

Putting it all together with namespace, Deployment, Service, HTTPRoute:

# 1. Namespace (with gateway-access label)
kubectl apply -f namespace.yaml          # from previous article

# 2. Workloads
kubectl apply -f deployment.yaml         # from previous article

# 3. Service
cat <<'EOF' | kubectl apply -f -
apiVersion: v1
kind: Service
metadata:
  name: goapp
  namespace: production
spec:
  selector:
    app: goapp
  ports:
    - name: http
      port: 8080
      targetPort: 8080
  type: ClusterIP
EOF

# 4. Gateway API resources
kubectl apply -f gatewayclass.yaml
kubectl apply -f gateway.yaml
kubectl apply -f httproute-basic.yaml

# 5. Verify
kubectl wait gateway production-gateway --for=condition=Programmed \
  -n gateway-system --timeout=60s

curl https://api.example.com/api/v1/items

---

Migration from Ingress

If you have existing Ingress resources, migrate iteratively:

1. Install Gateway API CRDs and a controller

2. Create a GatewayClass and Gateway

3. Create equivalent HTTPRoutes alongside existing Ingress

4. Switch DNS to the new Gateway's IP

5. Remove the Ingress resources

There is no automated migration tool — the mapping is straightforward but manual.

Example Ingress → HTTPRoute mapping:

# Old Ingress
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: goapp
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /
spec:
  rules:
    - host: api.example.com
      http:
        paths:
          - path: /api
            pathType: Prefix
            backend:
              service:
                name: goapp
                port:
                  number: 8080

# Equivalent HTTPRoute
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: goapp
spec:
  parentRefs:
    - name: production-gateway
      namespace: gateway-system
  hostnames:
    - "api.example.com"
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /api
      backendRefs:
        - name: goapp
          port: 8080

---

What I Learned

• GatewayClass/Gateway belongs to the platform team; routes belong to app teams — this role separation is the most practical benefit of Gateway API

• Traffic splitting replaces most blue/green tooling — weight: 90/10 on canary is cleaner than maintaining two Ingress resources

• GRPCRoute is zero-config compared to Ingress annotations for gRPC

• Always check .status.parents[].conditions. When routes do not attach, the reason is always there

• ReferenceGrant is explicit security — cross-namespace access requires deliberate consent from the target namespace owner

---

Next

• Kubernetes Cluster API — manage entire cluster lifecycles declaratively from a management cluster