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:

nix
kubectl get ingress web
nix
kubectl get ingress web
output
text
NAME CLASS HOSTS ADDRESS PORTS AGE
web hug example.com 192.0.2.10 80, 443 5m
output
text
NAME CLASS HOSTS ADDRESS PORTS AGE
web 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:

nix
POD=$(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
nix
POD=$(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
output
text
{"level":"DEBUG","msg":"Translated Ingress into synthetic HTTPRoutes","category":"gate"}
output
text
{"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:

nix
kubectl -n haproxy-unified-gateway get pods
nix
kubectl -n haproxy-unified-gateway get pods

During startup, this message is normal while HAProxy starts:

text
check haproxy-ready: waiting (initial probe failed ...)
text
check 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.

nix
POD=$(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_8080
for f in /usr/local/hug/maps/hug_http_8080/path_*.map \
/usr/local/hug/maps/hug_http_8080/listener_route_*.map; do
echo "== $f"
cat "$f"
done
'
nix
POD=$(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_8080
for f in /usr/local/hug/maps/hug_http_8080/path_*.map \
/usr/local/hug/maps/hug_http_8080/listener_route_*.map; do
echo "== $f"
cat "$f"
done
'
output
text
drwxr-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.map
default/ing:gateway_http/example.com default/ing:gateway_http/default/ing:web:0
output
text
drwxr-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.map
default/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:

    nix
    kubectl get ingressclass -o custom-columns=NAME:.metadata.name,CONTROLLER:.spec.controller
    nix
    kubectl get ingressclass -o custom-columns=NAME:.metadata.name,CONTROLLER:.spec.controller

    If the controller name ends in /<suffix>, confirm the current Pod has the matching --ingress-class=<suffix> argument. Use .spec.containers because $POD names a Pod, not a Deployment:

    nix
    kubectl -n haproxy-unified-gateway get "$POD" \
    -o jsonpath='{.spec.containers[0].args}{"\n"}'
    nix
    kubectl -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:

    nix
    kubectl get service web-svc -n default
    kubectl get endpoints web-svc -n default
    nix
    kubectl get service web-svc -n default
    kubectl get endpoints web-svc -n default
  • Confirm that RBAC grants ingresses and ingressclasses, and that --namespaces does 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.

Do you have any suggestions on how we can improve the content of this page? Please leave feedback!