# 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
```