🚪 Kubernetes Ingress and the Gateway API, Explained for Operators

Getting traffic into a Kubernetes cluster has always been the awkward part. Services give you internal routing; getting an HTTPS request from the internet to the right pod is a separate problem, and for years the answer was Ingress. Now there’s the Gateway API, which fixes Ingress’s real limitations. Let me explain both, when each makes sense, and how to debug the inevitable “why isn’t my route routing” moment.

What Ingress actually is

An Ingress is an L7 routing rule — hostname and path to Service. It does nothing on its own; you need an Ingress controller (NGINX, Traefik, HAProxy, a cloud LB controller) running in the cluster to read Ingress objects and configure the actual proxy.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: api
  annotations:
    nginx.ingress.kubernetes.io/ssl-redirect: "true"
spec:
  ingressClassName: nginx
  rules:
  - host: api.example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: api
            port:
              number: 80
  tls:
  - hosts: [api.example.com]
    secretName: api-tls

That works. The problem is everything beyond basic routing — header manipulation, traffic splitting, rate limits — lives in controller-specific annotations. Your Ingress YAML becomes a pile of nginx.ingress.kubernetes.io/* strings that don’t port to any other controller. That non-portability is Ingress’s original sin.

What the Gateway API fixes

The Gateway API replaces annotations with real, typed Kubernetes resources, and it splits responsibilities by role:

• GatewayClass — the controller implementation (like an IngressClass).
• Gateway — the actual listener: ports, protocols, TLS. Owned by the platform team.
• HTTPRoute (and TCPRoute, GRPCRoute) — the routing rules. Owned by app teams.

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: api
spec:
  parentRefs:
  - name: prod-gateway
  hostnames: ["api.example.com"]
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /
    backendRefs:
    - name: api
      port: 80

The role split is the real win. The platform team owns the Gateway (certs, listeners, the shared load balancer); app teams attach HTTPRoutes without touching shared infrastructure. And things that were annotation hacks — weighted traffic splitting for canaries, header matching, request mirroring — are now first-class typed fields that work identically across implementations.

When to use which

• New cluster? Start with the Gateway API if your controller supports it well (Cilium, Istio, Contour, NGINX Gateway Fabric all do). You’ll avoid the annotation trap.
• Existing Ingress that works? Don’t rip it out for its own sake. Migrate when you hit Ingress’s limits — multiple teams sharing one entry point, canary routing, or annotation sprawl you can’t maintain.
• Need advanced L7 today? Gateway API gives you traffic splitting and header routing without a service mesh.

You can run both side by side during a migration — different hostnames through different paths — so it’s not a big-bang cutover.

Debugging routing that won’t route

When a request 404s or 503s, the cause is almost always one of these, and they’re checkable in order:

1. Does the Service have endpoints? kubectl get endpoints api — empty means your selector doesn’t match running, ready pods. This is the number-one cause and people skip it.
2. Is the controller running and watching your class? Check the controller pod logs and confirm ingressClassName/GatewayClass matches.
3. Does the route attach? For Gateway API, kubectl describe httproute api shows whether it bound to the Gateway — a ResolvedRefs: False condition tells you exactly why not.
4. TLS secret present and valid? A missing or wrong-namespace cert secret silently breaks HTTPS.
5. Path type mismatch. Prefix vs Exact trips people constantly.

Where AI helps

Routing bugs span four or five objects — Service, endpoints, Ingress/HTTPRoute, controller config, TLS secret — and the error is usually a mismatch between them. Paste them all and ask:

“Requests to api.example.com return 503. Here’s the Service, its endpoints, the HTTPRoute, and the Gateway status. Find the mismatch between selectors, ports, and references.”

That cross-object correlation is exactly AI’s strength — it’ll spot that your Service targets port 8080 but the pod listens on 3000 faster than you’ll trace it by hand. Keep a few Kubernetes routing prompts ready.

Don’t forget the boring layers

L7 routing fails for L3/L4 reasons more often than you’d think:

• No external IP on the Gateway/Ingress means your cloud LB controller isn’t provisioning. Check its logs.
• Network Policies can block the controller from reaching backend pods even when routing is correct.
• DNS — the hostname has to actually resolve to the load balancer. Obvious, and yet.

A clean migration path

If you’re moving Ingress to Gateway API:

1. Install the Gateway API CRDs and a supporting controller.
2. Create one Gateway owned by the platform team, with TLS.
3. Convert one Ingress to an HTTPRoute on a test hostname.
4. Verify endpoints, attachment, and TLS before cutting DNS.
5. Migrate route by route, retiring annotations as you go.

Before route changes ship, I run them through the Code Review tool — it catches port mismatches between Service and route, and TLS secrets referenced from the wrong namespace.

Ingress got Kubernetes networking this far, but the Gateway API is where it’s going: typed, portable, and split cleanly between platform and app teams. Whichever you run, the debugging discipline is the same — check endpoints first, work outward, and let AI correlate the objects while you decide what to change.

AI routing analysis is assistive. Always verify endpoints and route status against your cluster before changing DNS.