Kubernetes Gateway API: The Complete Migration Guide from Ingress

# Kubernetes Gateway API: The Complete Migration Guide from Ingress

Kubernetes Gateway API reached GA in v1.1. If you're still writing Ingress resources, you're building on a foundation the community has moved past.

This isn't just a new API — it's a fundamental rethink of how Kubernetes handles networking.

Why Gateway API Replaces Ingress

Ingress was Kubernetes' first attempt at HTTP routing. It worked, but it had problems:

1. Vendor annotations everywhere — nginx.ingress.kubernetes.io/proxy-body-size is not portable 2. No standard for TCP/UDP — Ingress only handles HTTP(S) 3. Flat permission model — App devs and platform teams edit the same resource 4. No traffic splitting — Canary deployments require controller-specific annotations

Gateway API fixes all of these with a role-oriented design.

Architecture: The Three-Layer Model

Infrastructure Provider → GatewayClass (cluster-scoped)
Platform Team          → Gateway (namespace-scoped)
App Developer          → HTTPRoute / GRPCRoute / TCPRoute

This separation is the killer feature. Platform teams manage Gateways (TLS, listeners, IP allocation). App developers manage Routes (path matching, backends, traffic rules). Neither touches the other's config.

Migration: Ingress to HTTPRoute

Before (Ingress):

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

After (HTTPRoute):

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: my-app
spec:
  parentRefs:
  - name: main-gateway
  hostnames:
  - "app.example.com"
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /api
    backendRefs:
    - name: api-service
      port: 8080

No annotations. No controller-specific syntax. Portable across any Gateway API-compliant implementation.

Traffic Splitting (Built-In)

Canary deployments without annotations or service meshes:

rules:
- backendRefs:
  - name: api-v1
    port: 8080
    weight: 90
  - name: api-v2
    port: 8080
    weight: 10

Supported Implementations

Migration Strategy

1. Install a Gateway API CRD bundle: kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.1.0/standard-install.yaml 2. Deploy a GatewayClass and Gateway 3. Create HTTPRoutes alongside existing Ingress resources (both can coexist) 4. Test routing, then remove Ingress resources 5. Update CI/CD templates

TLS Configuration

Gateway API handles TLS at the Gateway level, not the route level. This is a major improvement — platform teams manage certificates centrally:

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: main-gateway
spec:
  gatewayClassName: envoy
  listeners:
  - name: https
    protocol: HTTPS
    port: 443
    tls:
      mode: Terminate
      certificateRefs:
      - name: wildcard-cert
        kind: Secret
    allowedRoutes:
      namespaces:
        from: All

App developers never touch TLS config. They reference the Gateway in their HTTPRoute and get HTTPS automatically. No more copying cert-manager annotations across 50 Ingress resources.

GRPCRoute: First-Class gRPC Support

Ingress had no native gRPC support — you needed annotations and workarounds. Gateway API has GRPCRoute as a first-class resource:

apiVersion: gateway.networking.k8s.io/v1
kind: GRPCRoute
metadata:
  name: grpc-service
spec:
  parentRefs:
  - name: main-gateway
  rules:
  - matches:
    - method:
        service: myapp.UserService
        method: GetUser
    backendRefs:
    - name: user-service
      port: 9090

Method-level routing for gRPC without any controller-specific hacks.

Real-World Migration: Our Experience

We migrated 12 services from NGINX Ingress Controller to Envoy Gateway in a single afternoon. The process:

1. Hour 1: Installed Gateway API CRDs and deployed Envoy Gateway alongside existing NGINX Ingress 2. Hour 2: Created HTTPRoutes for all 12 services, tested with curl against the new Gateway IP 3. Hour 3: Updated DNS to point to the new Gateway, monitored error rates 4. Hour 4: Removed old Ingress resources after confirming zero errors

The before/after was striking: 247 lines of annotation-heavy Ingress YAML became 89 lines of clean, portable Gateway API config. Zero vendor-specific syntax.

When NOT to Migrate Yet

The migration isn't urgent — but new services should use Gateway API from day one. Running both in parallel is fully supported and low-risk.

What's Coming Next

Gateway API is actively evolving. Features in development:

The momentum is clear: every major ingress controller has either shipped or announced Gateway API support. This is the future of Kubernetes networking.

---

Need help designing your Kubernetes networking architecture? Talk to our platform engineering teamTalk to our platform engineering teamhttps://techsaas.cloud/contact or check our infrastructure servicesinfrastructure serviceshttps://techsaas.cloud/services.