Ingress
Troubleshoot Ingress resources
Use the Ingress status, controller logs, route maps, and common problems table to diagnose a route. Before you troubleshoot, confirm that you enabled Ingress support and configured the Ingress resources.
Check the Ingress status Jump to heading
Retrieve the details of the Ingress object to check its status:
nixkubectl get ingress web
nixkubectl get ingress web
outputtextNAME CLASS HOSTS ADDRESS PORTS AGEweb hug example.com 192.0.2.10 80, 443 5m
outputtextNAME CLASS HOSTS ADDRESS PORTS AGEweb hug example.com 192.0.2.10 80, 443 5m
The ADDRESS field is the standard Ingress status.loadBalancer.ingress field. HAProxy Unified Gateway fills it with the address of its own Service. If the Service type is LoadBalancer, this is the external address your cloud provider assigned to that Service. If the load balancer is still provisioning, or the Service is NodePort or ClusterIP, the field can stay empty or contain node addresses.
Check the controller logs Jump to heading
Set the controller’s log level to debug to see the translation steps. For details, see Manage HAProxy Unified Gateway logs.
Then view the controller logs from the current Pod:
nixPOD=$(kubectl -n haproxy-unified-gateway get pods \-l run=haproxy-unified-gateway \--sort-by=.metadata.creationTimestamp \-o name | tail -1)kubectl -n haproxy-unified-gateway logs "$POD" --tail=200 | grep -i ingress
nixPOD=$(kubectl -n haproxy-unified-gateway get pods \-l run=haproxy-unified-gateway \--sort-by=.metadata.creationTimestamp \-o name | tail -1)kubectl -n haproxy-unified-gateway logs "$POD" --tail=200 | grep -i ingress
outputtext{"level":"DEBUG","msg":"Translated Ingress into synthetic HTTPRoutes","category":"gate"}
outputtext{"level":"DEBUG","msg":"Translated Ingress into synthetic HTTPRoutes","category":"gate"}
At debug level, the controller logs messages such as Injecting synthetic ingress gateway, Translated Ingress into synthetic HTTPRoutes, and Skipping Ingress backend. The last message includes the reason a backend was skipped, such as a named port that doesn’t exist.
kubectl logs deploy/... can select a terminating Pod when more than one Pod is present. List the Pods and log the current one:
nixkubectl -n haproxy-unified-gateway get pods
nixkubectl -n haproxy-unified-gateway get pods
During startup, this message is normal while HAProxy starts:
textcheck haproxy-ready: waiting (initial probe failed ...)
textcheck haproxy-ready: waiting (initial probe failed ...)
Wait for hug: ready before investigating. If a rollout logs panic: validation error: signal: terminated, confirm which Pod produced it. The terminating Pod can log a shutdown panic while the new Pod is healthy.
Check the route maps Jump to heading
HAProxy Unified Gateway writes the translated routes to maps in the controller Pod. The maps show whether it created a route for the Ingress.
nixPOD=$(kubectl -n haproxy-unified-gateway get pods \-l run=haproxy-unified-gateway \--sort-by=.metadata.creationTimestamp \-o name | tail -1)kubectl -n haproxy-unified-gateway exec "$POD" -- sh -c 'ls -ld /usr/local/hug/maps/hug_http_8080for f in /usr/local/hug/maps/hug_http_8080/path_*.map \/usr/local/hug/maps/hug_http_8080/listener_route_*.map; doecho "== $f"cat "$f"done'
nixPOD=$(kubectl -n haproxy-unified-gateway get pods \-l run=haproxy-unified-gateway \--sort-by=.metadata.creationTimestamp \-o name | tail -1)kubectl -n haproxy-unified-gateway exec "$POD" -- sh -c 'ls -ld /usr/local/hug/maps/hug_http_8080for f in /usr/local/hug/maps/hug_http_8080/path_*.map \/usr/local/hug/maps/hug_http_8080/listener_route_*.map; doecho "== $f"cat "$f"done'
outputtextdrwxr-xr-x 3 haproxy haproxy 4096 /usr/local/hug/maps/hug_http_8080== /usr/local/hug/maps/hug_http_8080/path_prefix.map/ default/ing:gateway_http/default/ing:web:0== /usr/local/hug/maps/hug_http_8080/listener_route_exact_match.mapdefault/ing:gateway_http/example.com default/ing:gateway_http/default/ing:web:0
outputtextdrwxr-xr-x 3 haproxy haproxy 4096 /usr/local/hug/maps/hug_http_8080== /usr/local/hug/maps/hug_http_8080/path_prefix.map/ default/ing:gateway_http/default/ing:web:0== /usr/local/hug/maps/hug_http_8080/listener_route_exact_match.mapdefault/ing:gateway_http/example.com default/ing:gateway_http/default/ing:web:0
The map contents depend on the Ingress hosts and paths. Use these observations to narrow down the failure:
| Observation | Meaning |
|---|---|
No hug_http_8080 directory |
Ingress support is not enabled, or the controller has not created the HTTP frontend. Check --enable-ingress and the controller logs. |
| Listener maps present, path maps empty | The controller created the listener but no Ingress route. Check the IngressClass, backend Service, RBAC, and namespace scope. |
| Path map contains the route | The route exists. Check the Host header, request path, and application response. |
HAProxy log shows backend_not_found |
No route matched the request. |
For HTTPS, check the maps under hug_https_8443.
If the path maps are empty, check the IngressClass and backend Service:
-
Check the IngressClass controller name:
nixkubectl get ingressclass -o custom-columns=NAME:.metadata.name,CONTROLLER:.spec.controllernixkubectl get ingressclass -o custom-columns=NAME:.metadata.name,CONTROLLER:.spec.controllerIf the controller name ends in
/<suffix>, confirm the current Pod has the matching--ingress-class=<suffix>argument. Use.spec.containersbecause$PODnames a Pod, not a Deployment:nixkubectl -n haproxy-unified-gateway get "$POD" \-o jsonpath='{.spec.containers[0].args}{"\n"}'nixkubectl -n haproxy-unified-gateway get "$POD" \-o jsonpath='{.spec.containers[0].args}{"\n"}' -
Confirm that the backend Service exists in the Ingress namespace and has endpoints:
nixkubectl get service web-svc -n defaultkubectl get endpoints web-svc -n defaultnixkubectl get service web-svc -n defaultkubectl get endpoints web-svc -n default -
Confirm that RBAC grants
ingressesandingressclasses, and that--namespacesdoes not exclude the Ingress namespace.
Common problems Jump to heading
Here are some common issues you may encounter and what you should check to resolve them.
| Symptom | What to check |
|---|---|
| No address on the Ingress | Confirm that --enable-ingress is set, RBAC grants ingresses and ingressclasses, the IngressClass exists, and the namespace isn’t excluded by --namespaces. A LoadBalancer Service that is still provisioning, or a NodePort or ClusterIP Service, can leave the address empty. |
| 404 responses | Check the route maps. If they contain the route, the Host header or path doesn’t match, or the application returned 404. |
| 404 and empty route maps | The IngressClass controller doesn’t match the controller, including a /<suffix> name without --ingress-class, the IngressClass is missing, the backend Service is missing, or RBAC or --namespaces excludes the Ingress. |
| 404 for both route types | The Ingress frontend shares a port with a Gateway listener. Use separate ports. See Expose the Ingress ports. |
| 503 responses | The route matches, but the backend has no available servers. Check the Service port and its Endpoints. HAProxy Unified Gateway logs no Port found on Service <namespace>/<service> matching Port <port> when the Ingress names a port that the Service doesn’t expose. |
| Connection refused | The port-forward isn’t running, or the Service doesn’t expose the port. Start a port-forward to the current Pod. The HTTPS port appears after a managed Ingress declares a TLS Secret. |
| HTTPS connection failures | Confirm that the Ingress has a tls section, the Secret exists in the same namespace, and the controller published port 8443. Check for Skipping invalid listener and Frontend [DELETE] hug_https_8443. One Ingress with a missing Secret removes HTTPS for every managed Ingress. |
| Ingress address changes | Another controller updates the same Ingress status. Add --disable-ingress-status-update while both controllers run, or remove the old controller. |
| An annotation has no effect | Most annotations have no effect. HAProxy Unified Gateway reads the cr-backend annotation for backend settings; it ignores other HAProxy Kubernetes Ingress Controller and NGINX annotations. Use a Backend CR or Gateway API filters. |
| Backend settings ignored | Use cr-backend on the Ingress for an ingress.v3.haproxy.org Backend. Use gate.v3.haproxy.org/cr-backend on the Service for a gate.v3.haproxy.org Backend. A wrong CRD group or annotation location, or a cross-namespace Backend, is ignored. See Use an HAProxy Unified Gateway Backend CR. |
If the route still fails, review the Ingress limitations or return to Configure Ingress resources.