# Use error-pages with Traefik 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. This guide wires `error-pages` as the global error handler for Traefik when used as a Kubernetes Ingress controller. When any backend returns a status code in the `400–599` range, Traefik's [errors middleware](https://doc.traefik.io/traefik/middlewares/http/errorpages/) intercepts the response and forwards it to `error-pages`, which returns a styled page in the format requested by the client. The middleware is attached at the **entrypoint level**: a single configuration change automatically covers every route on the `web` entrypoint, with no per-Ingress annotation required. Traefik also supports two narrower opt-in approaches - see the alternatives below before starting if you prefer per-service wiring. ## Alternative approaches This guide uses the entrypoint approach - the closest equivalent to ingress-nginx's `custom-http-errors`, where a single change applies to all backends at once. Traefik also supports two narrower alternatives that scope the middleware to individual routes. ### Per-Ingress annotation Attach the middleware to a single standard `Ingress` resource via annotation. Only that specific route gets styled error pages; everything else remains unaffected: ```yaml apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: httpbin annotations: # format: {middleware-namespace}-{middleware-name}@kubernetescrd traefik.ingress.kubernetes.io/router.middlewares: "error-pages-error-pages@kubernetescrd" spec: ingressClassName: traefik rules: - host: httpbin.localtest.me http: paths: - path: / pathType: Prefix backend: {service: {name: httpbin, port: {number: 80}}} ``` No `helm upgrade` for Traefik is required - Traefik picks up the annotation immediately. The trade-off is that every Ingress that should use `error-pages` must explicitly include the annotation. > [!NOTE] > Both alternatives reference a `Middleware` from the `error-pages` namespace within resources that live in a > different namespace. This requires `providers.kubernetesCRD.allowCrossNamespace=true` in Traefik - add > `--set providers.kubernetesCRD.allowCrossNamespace=true` to the initial `helm upgrade --install traefik` > command if you plan to use either approach. See the [Kubernetes Ingress routing reference](https://doc.traefik.io/traefik/routing/providers/kubernetes-ingress/) for the full list of supported annotations. ### IngressRoute CRD Traefik's native `IngressRoute` CRD lets you reference a `Middleware` CRD directly in the route definition, without annotations. This approach exposes more of Traefik's routing capabilities (priority, TCP/UDP routes, TLS options) but requires authoring Traefik-specific CRDs instead of standard Kubernetes `Ingress` resources: ```yaml apiVersion: traefik.io/v1alpha1 kind: IngressRoute metadata: name: httpbin namespace: default spec: entryPoints: [web] routes: - match: Host(`httpbin.localtest.me`) kind: Rule middlewares: - name: error-pages namespace: error-pages # cross-namespace ref; requires allowCrossNamespace: true on Traefik services: [{name: httpbin, port: 80}] ``` The `Middleware` CRD created by the error-pages Helm chart (`traefikMiddleware.enabled=true`) works with both approaches - no extra configuration of `error-pages` is required regardless of which routing style you choose. See the [IngressRoute CRD reference](https://doc.traefik.io/traefik/routing/providers/kubernetes-crd/) and the [errors middleware reference](https://doc.traefik.io/traefik/middlewares/http/errorpages/) for full details. ## Local cluster setup Follow the [kind guide](install_k8s_kind.md) to install the prerequisites. ## Install Traefik Add the Helm repository and install Traefik as a DaemonSet with kind-compatible settings: ```shell $ helm repo add traefik https://traefik.github.io/charts && helm repo update traefik ...Successfully got an update from the "traefik" chart repository Update Complete. ⎈Happy Helming!⎈ ``` > [!NOTE] > Get the latest chart version from the [GitHub releases](https://github.com/traefik/traefik-helm-chart/releases/latest) > page. ```shell $ helm upgrade --install traefik traefik/traefik \ --version 39.0.8 \ --namespace traefik \ --create-namespace \ --set deployment.kind=DaemonSet \ --set 'updateStrategy.rollingUpdate.maxSurge=0' \ --set 'updateStrategy.rollingUpdate.maxUnavailable=1' \ --set-string 'nodeSelector.ingress-ready=true' \ --set 'tolerations[0].key=node-role.kubernetes.io/control-plane' \ --set 'tolerations[0].operator=Exists' \ --set 'tolerations[0].effect=NoSchedule' \ --set 'ports.web.hostPort=80' \ --set 'ports.websecure.hostPort=443' \ --set service.type=NodePort \ --wait \ --timeout=90s Release "traefik" does not exist. Installing it now. NAME: traefik LAST DEPLOYED: ... NAMESPACE: traefik STATUS: deployed REVISION: 1 DESCRIPTION: Install complete ``` A few kind-specific flags worth noting: * `deployment.kind=DaemonSet` - runs exactly one Traefik pod per node; in a single-node kind cluster, this means one pod total. `hostPort` binding on a Deployment would also work, but a DaemonSet is the idiomatic choice when you want exactly one instance per node. * `updateStrategy.rollingUpdate.maxSurge=0` / `maxUnavailable=1` - the Traefik chart defaults to `maxSurge=1`, which tries to start a new pod before stopping the old one. In kind, both pods would compete for the same host port, and the new pod would get stuck in `Pending`. Setting `maxSurge=0` ensures the old pod is stopped first. * `ports.web.hostPort=80` - binds port 80 directly on the kind node. Combined with `extraPortMappings`, this makes Traefik reachable on `localhost:80`. Verify the DaemonSet pods are running: ```shell $ kubectl get pods --namespace traefik NAME READY STATUS RESTARTS AGE traefik-8zvhf 1/1 Running 0 84s ``` Verify Traefik is reachable on port 80. There are no Ingress rules yet, so it returns its built-in 404: ```shell $ curl -so /dev/null -w "%{http_code}" http://localhost/ 404 $ curl -s http://localhost/ 404 page 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 - handy for testing error page interception. 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: traefik 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 requires no `/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 app responds normally: ```shell $ curl -s http://httpbin.localtest.me/get { "args": {}, "headers": { "Accept": [ "*/*" ], "Host": [ "httpbin.localtest.me" ], "User-Agent": [ "curl/8.11.1" ], "...": ["..."] }, "method": "GET", "origin": "172.20.0.1", "url": "http://httpbin.localtest.me/get" } ``` ## Default error pages Before `error-pages` is wired in, backend errors pass through as raw HTTP responses. go-httpbin's `/status/{code}` returns the requested status code with an empty body - no message, no description: ```shell $ curl -si http://httpbin.localtest.me/status/404 HTTP/1.1 404 Not Found Access-Control-Allow-Credentials: true Access-Control-Allow-Origin: * Content-Length: 0 Content-Type: text/plain; charset=utf-8 Date: ... ``` ```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-Length: 0 Content-Type: text/plain; charset=utf-8 Date: ... ``` Requests that match no Ingress rule at all are served by Traefik's built-in 404 page: ```shell $ curl -s http://unknown.localtest.me/ | head -n 5 404 page not found ``` ## 🔥 Install error-pages Install error-pages with `traefikMiddleware.enabled=true` - this creates a `Middleware` CRD in the `error-pages` namespace that Traefik will use to intercept error responses: > [!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.htmlTemplate.name=l7 \ --set traefikMiddleware.enabled=true \ --wait \ --timeout=60s NAME: error-pages LAST DEPLOYED: ... NAMESPACE: error-pages STATUS: deployed REVISION: 1 DESCRIPTION: Install complete ``` Verify the `Middleware` CRD was created: ```shell $ kubectl get middleware --namespace error-pages NAME AGE error-pages 10s ``` > [!NOTE] > Unlike ingress-nginx, `config.sendSameHttpCode=true` is **not** required here. Traefik's errors middleware > preserves the original backend status code and only replaces the response body - it does not use the status > code returned by the error service. ## Wire Traefik to error-pages Attach the `Middleware` CRD to Traefik's `web` entrypoint as a static argument. Every route using this entrypoint will then automatically have its 4xx/5xx responses intercepted and styled: ```shell $ helm upgrade traefik traefik/traefik \ --version 39.0.8 \ --namespace traefik \ --reuse-values \ --set 'additionalArguments[0]=--entrypoints.web.http.middlewares=error-pages-error-pages@kubernetescrd' \ --wait \ --timeout=60s Release "traefik" has been upgraded. Happy Helming! NAME: traefik LAST DEPLOYED: ... NAMESPACE: traefik STATUS: deployed REVISION: 2 DESCRIPTION: Upgrade complete ``` The middleware identifier format is `{namespace}-{name}@kubernetescrd`: namespace `error-pages`, name `error-pages`, provider `kubernetescrd`. ## Verify custom error pages The same requests that previously returned empty responses now return styled error pages: ```shell $ curl -s -H "Accept: text/html" http://httpbin.localtest.me/status/404 | head -n 15