Quick take

A broken Ingress is almost always one of seven things, and they fail loudly enough to spot in under five minutes. The bug is rarely in the Ingress object itself. It is usually in the Service selector, the Endpoints, the controller, or DNS. Here is the seven-step checklist I run every time, in order, before opening a ticket.

If you only remember three things, remember these:

• Read the Ingress controller pod logs first. Half the time, the answer is there.
• kubectl get endpoints <service> tells you instantly if the Service is even pointing at pods.
• curl from inside the cluster before debugging external DNS or load balancer issues.

Step zero: the diagnostic stack

The Ingress request path has five layers. Most failures live in exactly one of them.

1. DNS resolves the host to a load balancer or controller IP.
2. The external load balancer (ALB, GCLB, Azure Application Gateway) forwards to the Ingress controller.
3. The Ingress controller pod (nginx, Traefik, Contour, AWS Load Balancer Controller) matches the Ingress rule.
4. The controller forwards to a Service.
5. The Service forwards to a backend Pod via Endpoints.

Diagnose from the bottom up. Start with the Pod and walk back to DNS. Working downstream from the user (DNS first, then LB) wastes time because you cannot rule out the inner layers until you have proven them healthy.

1. Is the Pod actually healthy?

The first check, always. A 502 or empty response is often "the Pod is not Ready" wearing different clothes.

• kubectl get pods -l app=<your-app>: are all pods in Running state with READY 1/1?
• kubectl describe pod <pod>: any failing readiness probes?
• kubectl logs <pod>: is the app actually serving on the port you think?

A pod that crashes on startup or fails readiness will be silently removed from the Service's Endpoints list, and Ingress will route to nothing. This is the single most common root cause.

2. Do the Service selectors match the Pod labels?

This is the bug that takes the longest to find because nothing in the error message hints at it.

Run kubectl get endpoints <service-name>. If the ENDPOINTS column is empty or says <none>, the Service selector does not match any Pod labels.

Common selector traps:

• Pod label is app.kubernetes.io/name: payments, Service selector is app: payments. They are different keys.
• A Helm upgrade changed the label key from app to app.kubernetes.io/name. The Service still has the old selector.
• The Service is in a different namespace than the Pods.

Fix by matching the selector exactly to a label that is actually on the Pods.

3. Does the Service port map to the Pod port?

The Service has a port (what callers hit) and a targetPort (what the Pod listens on). Get these wrong and you see "connection refused" or empty 502 responses.

kubectl describe service <name> shows both. The targetPort must match the containerPort in the Pod's container spec, or match a named port defined in that spec.

A surprisingly common bug in 2026: the app was changed from listening on 8080 to 3000, but the Service still points at 8080. The container is up, healthy, and serving on the wrong port.

4. Is the Ingress controller running and watching this Ingress?

The Ingress object is just a configuration entry. Without a controller pod watching for it, nothing routes.

Two checks:

• kubectl get pods -n <ingress-controller-namespace> (commonly ingress-nginx, kube-system, or traefik). Are the controller pods Running?
• kubectl get ingress <name> -o yaml | grep ingressClassName. Does the value match the IngressClass the controller is configured to watch?

The ingressClassName mismatch is the most common cause when a brand-new Ingress just sits there with no ADDRESS populated. Default IngressClass changed in K8s 1.22 from an annotation to a spec field. Older manifests using the annotation are silently ignored by newer controllers.

5. Are the host and path rules correct?

The Ingress matches on host and path. Both are easier to get wrong than they look.

• host: api.example.com is exact match by default. If your request comes in as Host: API.example.com (uppercase) or Host: api.example.com:443 (with port), the rule may not match on some controllers.
• pathType: Exact vs pathType: Prefix: Exact matches the full path. Prefix matches anything starting with the path. A rule for /api with Exact will not match /api/users.
• Path order matters in some controllers. /api/v1 before /api is important if both rules exist, because longest-prefix usually wins, but not always.

Test with curl -H "Host: api.example.com" http://<controller-ip>/your/path from inside the cluster to bypass DNS and the external load balancer.

6. Are the controller annotations doing something unexpected?

Annotations are where the Ingress spec hides its complexity. Three to check.

• nginx.ingress.kubernetes.io/rewrite-target: if set, the path your backend receives is not the path the user sent. A wrong rewrite causes the app to return 404 even though the Ingress matched.
• nginx.ingress.kubernetes.io/ssl-redirect: "true": an HTTP request to a TLS-enabled Ingress gets a 308 redirect. If your test client does not follow redirects, you see "no response."
• nginx.ingress.kubernetes.io/backend-protocol: HTTPS: if your backend speaks HTTP but the annotation says HTTPS, you get TLS handshake errors deep in the controller logs.

Strip annotations one at a time and re-test until the request flows.

7. Is DNS or the external load balancer broken?

Last layer to check. The reason it is last is that you cannot rule out the inner layers until you have proven them healthy.

• dig <your-host> or nslookup. Does the host resolve at all? Does it resolve to the LB you expect?
• Hit the LB directly with the Host header: curl -H "Host: api.example.com" http://<lb-ip>/. If this works and the DNS-based request does not, your DNS is wrong.
• LB health checks: if the load balancer marks the controller pods unhealthy (wrong health check path, wrong port), it stops routing to them. Check the LB's target group health.

On AWS, the AWS Load Balancer Controller sometimes provisions the ALB with a default health check at / that returns 404 from your app, marking everything unhealthy. Set alb.ingress.kubernetes.io/healthcheck-path explicitly.

Common pitfalls I keep seeing

• Empty Endpoints list ignored. The output says <none> and the team assumes it's fine. It is never fine.
• NetworkPolicy blocking the controller. A namespace-level deny-all NetworkPolicy will block the ingress-nginx pod from reaching the Service. Allow ingress from the controller namespace explicitly.
• TLS cert not provisioned. cert-manager failed to issue, the secret is empty, and the controller serves a default cert that browsers reject. Check kubectl describe certificate.
• IngressClass deleted but Ingress still referencing it. Happens during cluster migrations. The Ingress just sits there with no controller picking it up.

Where this checklist still falls short

The honest part.

Service mesh interception. If Istio, Linkerd, or another mesh sidecar is in play, the traffic path is more complex than five layers. The mesh may strip headers, redirect TLS, or apply its own routing rules. Disable the mesh sidecar in a test namespace to isolate.

Multi-cluster gateways. Gateway API in 2026 supports cross-cluster routing. If your Gateway is in cluster A and the Service is in cluster B, none of the single-cluster debugging steps apply. Inspect the Gateway controller's cross-cluster mesh state.

WebSocket and gRPC. Plain HTTP works but the upgrade fails. The Ingress controller needs explicit annotation support (nginx.ingress.kubernetes.io/upstream-protocol: grpc for gRPC, longer timeouts for WebSocket). Same five-step checklist applies, but the path is more subtle.

Frequently asked questions

Why does kubectl get ingress show no ADDRESS?
Almost always the IngressClass mismatch from Step 4. The controller is not picking up the Ingress because the class does not match.

Why is my Ingress returning 502 Bad Gateway?
Three usual suspects: empty Endpoints (Step 2), wrong port mapping (Step 3), or the Pod is up but the app crashes on requests (Step 1, but check the logs).

Why does the Ingress work for /foo but not /foo/bar?
pathType: Exact is set when you wanted Prefix. Switch to Prefix and re-test.

Does any of this change with Gateway API?
The diagnostic shape is the same: HTTPRoute selectors, backend Service health, controller pod status. The names differ but the failure modes are nearly identical to classic Ingress.

What was the last Ingress incident that took too long to diagnose?

If a 502 burned half a sprint last quarter, the question worth asking is which of the seven steps would have caught it in five minutes. Drop the symptom in the comments. I will tell you the step I would have run first.