# Use error pages with HAProxy Ingress in Kubernetes > [!IMPORTANT] > I am not a Kubernetes expert. This guide is **not a production-ready solution** - it is a working starting point > and a cheat sheet for `error-pages` users. Everything described here has been tested and works, but every real > deployment is different: validate the configuration, review the security implications, and adapt it to your own > environment before using it in production. > > Contributions and improvements are very welcome - feel free to open a PR and I will happily accept it. > [!WARNING] > **HAProxy Ingress handles unmatched routes only**. Unlike ingress-nginx or Traefik, HAProxy Ingress does not have > a built-in mechanism to intercept HTTP error responses from backends and replace them transparently. The > `defaultBackendService` option wires `error-pages` as the fallback for **unmatched routes only** - requests to > host/path combinations not covered by any Ingress rule. Errors returned by matched backends (for example, a > deployment that responds with 500) pass through to the client unchanged. This guide wires `error-pages` as the **default backend** of HAProxy Ingress. When a request arrives that no Ingress rule matches, the controller forwards it to `error-pages`, which returns a styled page in the format the client requested (HTML, JSON, XML, or plain text). ## Local cluster setup Follow the [kind guide](install_k8s_kind.md) to install the prerequisites. ## Install HAProxy Ingress ```shell $ helm repo add haproxy-ingress https://haproxy-ingress.github.io/charts && helm repo update ...Successfully got an update from the "haproxy-ingress" chart repository Update Complete. ⎈Happy Helming!⎈ ``` Install the controller as a `DaemonSet` so it binds ports `80` and `443` directly via `hostPort` on the kind node: > [!NOTE] > Get the latest chart version from the [GitHub releases](https://github.com/haproxy-ingress/charts/releases) page. ```shell $ helm upgrade --install haproxy-ingress haproxy-ingress/haproxy-ingress \ --version 0.16.0 \ --namespace ingress-controller \ --create-namespace \ --set controller.kind=DaemonSet \ --set controller.daemonset.useHostPort=true \ --set controller.service.type=ClusterIP \ --set controller.ingressClassResource.enabled=true \ --set-string 'controller.nodeSelector.ingress-ready=true' \ --set 'controller.tolerations[0].key=node-role.kubernetes.io/master' \ --set 'controller.tolerations[0].effect=NoSchedule' \ --set 'controller.tolerations[0].operator=Exists' \ --set 'controller.tolerations[1].key=node-role.kubernetes.io/control-plane' \ --set 'controller.tolerations[1].effect=NoSchedule' \ --set 'controller.tolerations[1].operator=Exists' \ --wait \ --timeout=90s Release "haproxy-ingress" does not exist. Installing it now. NAME: haproxy-ingress LAST DEPLOYED: ... NAMESPACE: ingress-controller STATUS: deployed REVISION: 1 DESCRIPTION: Install complete ``` A few kind-specific settings worth explaining: * `controller.kind=DaemonSet` + `controller.daemonset.useHostPort=true` - the DaemonSet pod binds port 80 on the kind node directly via `hostPort`. Combined with the `extraPortMappings` in the kind cluster config, traffic flows: `localhost:80` → kind node port 80 → HAProxy Ingress pod port 80. * `controller.service.type=ClusterIP` - the Service external IP is not needed here because traffic enters via `hostPort`, not through a LoadBalancer. * `controller.ingressClassResource.enabled=true` - creates the `haproxy` IngressClass resource so that Ingress objects using `ingressClassName: haproxy` are picked up by this controller. * `controller.nodeSelector.ingress-ready=true` - targets only nodes labelled `ingress-ready=true`, which is the label set in the kind cluster config for the control-plane node. Verify the controller pod is ready: ```shell $ kubectl get pods --namespace ingress-controller NAME READY STATUS RESTARTS AGE haproxy-ingress-xxxxx 1/1 Running 0 30s ``` Verify HAProxy Ingress is reachable on port `80`. There are no Ingress rules yet, so the controller returns its own built-in 404 - that is expected at this stage: ```shell $ curl -si http://localhost/ HTTP/1.1 404 Not Found content-type: text/html cache-control: no-cache content-length: 83

404 Not Found

The requested URL was not found. ``` ## Deploy a test application [go-httpbin](https://github.com/mccutchen/go-httpbin) is a small HTTP testing service. Its `/status/{code}` endpoint returns any requested status code, which makes it handy for testing error page behaviour. Save the following to `httpbin.yaml`: ```yaml # File: httpbin.yaml apiVersion: apps/v1 kind: Deployment metadata: {name: httpbin} spec: replicas: 1 selector: {matchLabels: {app: httpbin}} template: metadata: {labels: {app: httpbin}} spec: {containers: [{name: httpbin, image: ghcr.io/mccutchen/go-httpbin:2.22, ports: [{containerPort: 8080}]}]} --- apiVersion: v1 kind: Service metadata: {name: httpbin} spec: selector: {app: httpbin} ports: [{port: 80, targetPort: 8080}] --- apiVersion: networking.k8s.io/v1 kind: Ingress metadata: {name: httpbin} spec: ingressClassName: haproxy rules: - host: httpbin.localtest.me http: {paths: [{path: /, pathType: Prefix, backend: {service: {name: httpbin, port: {number: 80}}}}]} ``` `localtest.me` is a public DNS wildcard: `*.localtest.me` always resolves to `127.0.0.1`, so this works offline and does not require an `/etc/hosts` entry. ```shell $ kubectl apply -f httpbin.yaml && kubectl rollout status deployment/httpbin --timeout=60s deployment.apps/httpbin created service/httpbin created ingress.networking.k8s.io/httpbin created deployment "httpbin" successfully rolled out ``` Verify the application responds normally: ```shell $ curl -s http://httpbin.localtest.me/get { "args": {}, "headers": { "Accept": [ "*/*" ], "Host": [ "httpbin.localtest.me" ], "...": ["..."] }, "method": "GET", "origin": "172.20.0.1", "url": "http://httpbin.localtest.me/get" } ``` ## Default error pages Before `error-pages` is wired in, requests to unknown hosts are served by HAProxy Ingress's built-in fallback: ```shell $ curl -si http://unknown.localtest.me/ HTTP/1.1 404 Not Found content-type: text/html content-length: 83 cache-control: no-cache

404 Not Found

The requested URL was not found. ``` Backend errors from matched routes pass through unmodified - go-httpbin's `/status/{code}` returns the requested status code with an empty body: ```shell $ curl -si http://httpbin.localtest.me/status/503 HTTP/1.1 503 Service Unavailable access-control-allow-credentials: true access-control-allow-origin: * content-type: text/plain; charset=utf-8 date: ... content-length: 0 ``` ## 🔥 Install error-pages Setting **`config.sendSameHttpCode=true`** is required - `error-pages` must return the original error status code (e.g. `404`) rather than `200`. Without it, HAProxy Ingress would forward the `200` response to the client and the error code would be lost. > [!NOTE] > Get the latest chart version from [ArtifactHub](https://artifacthub.io/packages/helm/error-pages/error-pages) > or the [GitHub releases](https://github.com/tarampampam/error-pages/releases) page. ```shell $ helm install error-pages oci://ghcr.io/tarampampam/error-pages/charts/error-pages \ --version X.Y.Z \ --namespace error-pages \ --create-namespace \ --set config.sendSameHttpCode=true \ --set config.htmlTemplate.name=l7 \ --wait \ --timeout=60s NAME: error-pages LAST DEPLOYED: ... NAMESPACE: error-pages STATUS: deployed REVISION: 1 DESCRIPTION: Install complete ``` ## Wire HAProxy Ingress to error-pages Set `controller.defaultBackendService` to route all unmatched requests to `error-pages`. Changing this value triggers a DaemonSet rollout: ```shell $ helm upgrade haproxy-ingress haproxy-ingress/haproxy-ingress \ --version 0.16.0 \ --namespace ingress-controller \ --reuse-values \ --set controller.defaultBackendService=error-pages/error-pages \ --wait \ --timeout=90s Release "haproxy-ingress" has been upgraded. Happy Helming! NAME: haproxy-ingress LAST DEPLOYED: ... NAMESPACE: ingress-controller STATUS: deployed REVISION: 2 DESCRIPTION: Upgrade complete ``` ## Verify custom error pages Requests to unknown hosts now return styled pages from `error-pages`. HAProxy Ingress forwards the request - including the original `Accept` header - to `error-pages`, which selects the appropriate format automatically: ```shell $ curl -si -H "Accept: text/html" http://unknown.localtest.me/ | head -n 15 HTTP/1.1 404 Not Found content-length: 52980 content-type: text/html; charset=utf-8 x-robots-tag: noindex, nofollow, nosnippet, noarchive date: ... Not Found ``` ```shell $ curl -si -H "Accept: application/json" http://unknown.localtest.me/ HTTP/1.1 404 Not Found content-length: 124 content-type: application/json; charset=utf-8 x-robots-tag: noindex, nofollow, nosnippet, noarchive date: ... { "error": true, "code": 404, "message": "Not Found", "description": "The server can not find the requested page" } ``` Backend errors from matched routes remain unchanged: ```shell $ curl -si http://httpbin.localtest.me/status/503 HTTP/1.1 503 Service Unavailable access-control-allow-credentials: true access-control-allow-origin: * content-type: text/plain; charset=utf-8 date: ... content-length: 0 (empty body - HAProxy Ingress does not intercept backend error responses) ``` ## Cleanup Delete the kind cluster to remove all resources at once: ```shell kind delete cluster --name error-pages-test-cluster ```