阅读中文版本

Kubernetes Ingress 404 — No Rule Matches the Host or Path

Fix Ingress 404s by matching the host header and path rules, checking the ingress class, and verifying backend service and port names.

kubectl describe ingress <ing> | grep -A 10 "Rules"

curl -i -H 'Host: app.example.com' http://<ingress-ip>/api/health

Symptoms

This guide profiles the failure behind “Kubernetes Ingress 404 — No Rule Matches the Host or Path”. It walks through the observable symptoms, a reproducible diagnosis path, the underlying root cause, the concrete fix, and how to verify the change and prevent a regression.

Observed symptoms include:

• Requests hit the ingress controller but return 404
• The app works via port-forward but not through the Ingress
• A path prefix works for / but not /api

Reproduce and Diagnose

Reproduce the failure in isolation before changing any code. Work through the checks below in order; each one narrows the search space.

Step 1: Inspect the ingress rules

kubectl describe ingress <ing> | grep -A 10 "Rules"

The host and path rules show exactly what must be requested to match.

Step 2: Reproduce with the correct Host header

curl -i -H 'Host: app.example.com' http://<ingress-ip>/api/health

A 200 with the right Host and path confirms the rule works; a 404 shows the mismatch.

Likely contributors, in order of frequency:

• The host or path in the request does not match any Ingress rule
• The Ingress uses a class the controller does not serve
• The backend service name or port name is wrong, so routing fails

Root Cause

An ingress controller matches requests by host and path to the declared rules and forwards to the named service port. A request that matches no rule—or a rule whose backend names are wrong—returns 404 or 503 from the controller.

The Fix

Align the request host and path with the rules, set the correct ingressClassName, and match the backend service name and the named port declared on the Service.

Watch out: Using the wrong ingressClassName can silently deploy an ignored ingress; verify the controller picks it up.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: web
spec:
  ingressClassName: nginx            # class the controller serves
  rules:
    - host: app.example.com          # request must send this Host
      http:
        paths:
          - path: /api               # matches /api/...
            pathType: Prefix
            backend:
              service:
                name: web               # must match the Service name
                port:
                  name: http            # named port on the Service

Verify and Prevent

Request the app with the matching host and path and confirm 200; verify kubectl describe ingress shows the expected backend and address.

Once verified, add a regression test that reproduces the original symptom so the failure cannot silently return.

This class of failure is usually environmental rather than pure logic, so capture the exact command, the environment variables, and the working directory in your bug report. Reproduce it in the smallest possible script, then widen the scope only once the minimal case is understood. A short written checklist for this failure mode saves hours the next time it appears.