# Use error pages with NGINX Gateway Fabric 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 custom error backend for [NGINX Gateway Fabric](https://github.com/nginx/nginx-gateway-fabric) (NGF). When any backend routed through the Gateway returns an error status code, an NGINX `SnippetsPolicy` intercepts the response and proxies it to `error-pages`, which returns a styled page in the format the client requested. > [!NOTE] > Unlike ingress-nginx (which has a built-in default backend concept), NGF uses the > [SnippetsPolicy](https://docs.nginx.com/nginx-gateway-fabric/reference/api/#gateway.nginx.org/v1alpha1.SnippetsPolicy) > API to inject raw NGINX configuration directives. `SnippetsPolicy` is an **alpha** feature and must be explicitly > enabled at install time. > > `SnippetsPolicy` is the only available method because neither the Gateway API specification nor NGF provide a > first-class API for custom error pages: > > - [kubernetes-sigs/gateway-api#1998](https://github.com/kubernetes-sigs/gateway-api/issues/1998) > - [kubernetes-sigs/gateway-api#2826](https://github.com/kubernetes-sigs/gateway-api/issues/2826) > - [nginx/nginx-gateway-fabric#4967](https://github.com/nginx/nginx-gateway-fabric/issues/4967) > - The [NGF Snippets documentation](https://docs.nginx.com/nginx-gateway-fabric/traffic-management/snippets/) > explicitly states they should be used "only in cases where Gateway API resources or NGINX extension policies > don't apply" - custom error pages are exactly that case. ## Local cluster setup Follow the [kind guide](install_k8s_kind.md) to install the prerequisites. ## Install NGINX Gateway Fabric ### Install Gateway API CRDs NGF implements the [Gateway API](https://gateway-api.sigs.k8s.io/) standard. Install the Gateway API CRDs first: ```shell $ kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.3.0/standard-install.yaml customresourcedefinition.apiextensions.k8s.io/gatewayclasses.gateway.networking.k8s.io created customresourcedefinition.apiextensions.k8s.io/gateways.gateway.networking.k8s.io created customresourcedefinition.apiextensions.k8s.io/grpcroutes.gateway.networking.k8s.io created customresourcedefinition.apiextensions.k8s.io/httproutes.gateway.networking.k8s.io created customresourcedefinition.apiextensions.k8s.io/referencegrants.gateway.networking.k8s.io created ``` ### Install the NGF controller > [!NOTE] > Get the latest chart version from the [GitHub releases](https://github.com/nginx/nginx-gateway-fabric/releases/latest) > page. ```shell $ helm install ngf oci://ghcr.io/nginx/charts/nginx-gateway-fabric \ --version 2.5.1 \ --namespace nginx-gateway \ --create-namespace \ --set nginxGateway.snippets.enable=true \ --set nginx.service.type=NodePort \ --set 'nginx.container.hostPorts[0].port=80' \ --set 'nginx.container.hostPorts[0].containerPort=80' \ --set 'nginx.pod.tolerations[0].key=node-role.kubernetes.io/master' \ --set 'nginx.pod.tolerations[0].effect=NoSchedule' \ --set 'nginx.pod.tolerations[0].operator=Exists' \ --set 'nginx.pod.tolerations[1].key=node-role.kubernetes.io/control-plane' \ --set 'nginx.pod.tolerations[1].effect=NoSchedule' \ --set 'nginx.pod.tolerations[1].operator=Exists' \ --set-string 'nginx.pod.nodeSelector.ingress-ready=true' \ --wait \ --timeout=90s NAME: ngf LAST DEPLOYED: ... NAMESPACE: nginx-gateway STATUS: deployed REVISION: 1 DESCRIPTION: Install complete ``` Kind-specific settings explained: - `nginxGateway.snippets.enable=true` - enables the `SnippetsPolicy` and `SnippetsFilter` alpha APIs, which are disabled by default. **This is required to inject the error interception NGINX config**. - `nginx.service.type=NodePort` - avoids a `` external IP on the NGINX data plane Service. Traffic reaches NGINX via `hostPort` → `extraPortMappings`, not through the Service. - `nginx.container.hostPorts` - binds port 80 of the NGINX data plane pod directly to the kind node's host port, so that traffic arriving at `localhost:80` reaches NGINX. - `nginx.pod.tolerations` and `nginx.pod.nodeSelector` - allow the NGINX data plane pod to be scheduled on kind's control-plane node, which carries both `node-role.kubernetes.io/master` and `node-role.kubernetes.io/control-plane` taints. The `ingress-ready=true` label is set on the node by the kind cluster config. Verify the controller pod is ready: ```shell $ kubectl get pods --namespace nginx-gateway NAME READY STATUS RESTARTS AGE ngf-nginx-gateway-fabric-7d95c89b7b-xxxxx 1/1 Running 0 60s ``` ### Create a Gateway NGF uses a split control-plane / data-plane architecture. The control plane (`ngf-nginx-gateway-fabric`) is installed at Helm install time, but the NGINX data plane pod is provisioned on demand when you create a `Gateway` resource. Save the following to `gateway.yaml`: ```yaml # File: gateway.yaml apiVersion: gateway.networking.k8s.io/v1 kind: Gateway metadata: name: nginx namespace: default spec: gatewayClassName: nginx listeners: - name: http port: 80 protocol: HTTP ``` ```shell $ kubectl apply -f gateway.yaml gateway.gateway.networking.k8s.io/nginx created ``` Wait for the NGINX data plane pod to appear and become ready: ```shell $ kubectl rollout status deployment/nginx-nginx --namespace default --timeout=90s deployment "nginx-nginx" successfully rolled out $ kubectl get gateway nginx NAME CLASS ADDRESS PROGRAMMED AGE nginx nginx 10.96.96.113 True 30s ``` Verify NGF is reachable on port `80`. There are no HTTPRoutes yet, so NGINX returns its built-in 404: ```shell $ curl -s http://localhost/ | head -n 5 404 Not Found

404 Not Found


nginx
``` ## 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 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: 8080, targetPort: 8080}] --- apiVersion: gateway.networking.k8s.io/v1 kind: HTTPRoute metadata: {name: httpbin} spec: parentRefs: [{name: nginx, namespace: default}] hostnames: [httpbin.localtest.me] rules: - matches: [{path: {type: PathPrefix, value: /}}] backendRefs: [{name: httpbin, port: 8080}] ``` `localtest.me` is a public DNS wildcard: `*.localtest.me` always resolves to `127.0.0.1`, so this works offline and doesn't 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 httproute.gateway.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 to the client as-is. Without `proxy_intercept_errors on`, NGINX proxies the upstream response without modifying it. go-httpbin's `/status/{code}` returns the requested status code with an empty body - no message, no description, nothing useful for an end user: ```shell $ curl -si http://httpbin.localtest.me/status/404 HTTP/1.1 404 Not Found Server: nginx Date: ... Content-Type: text/plain; charset=utf-8 Content-Length: 0 Connection: keep-alive Access-Control-Allow-Credentials: true Access-Control-Allow-Origin: * ``` ```shell $ curl -si http://httpbin.localtest.me/status/503 HTTP/1.1 503 Service Unavailable Server: nginx Date: ... Content-Type: text/plain; charset=utf-8 Content-Length: 0 Connection: keep-alive Access-Control-Allow-Credentials: true Access-Control-Allow-Origin: * ``` ## 🔥 Install error-pages Setting **`config.sendSameHttpCode=true`** is critical for this integration - `error-pages` must return the same HTTP status code as the error it renders, not `200`. Otherwise, NGINX will pass the `200` response to the client and the actual error code will 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 \ --wait \ --timeout=60s NAME: error-pages LAST DEPLOYED: ... NAMESPACE: error-pages STATUS: deployed REVISION: 1 DESCRIPTION: Install complete ``` ## Wire NGINX Gateway Fabric to error-pages NGF does not have a built-in default backend concept. Instead, use a `SnippetsPolicy` to inject raw NGINX configuration into every server block managed by the Gateway. The snippet enables `proxy_intercept_errors` and defines a named location that proxies intercepted errors to `error-pages`. Save the following to `error-pages-policy.yaml`: ```yaml # File: error-pages-policy.yaml apiVersion: gateway.nginx.org/v1alpha1 kind: SnippetsPolicy metadata: name: error-pages namespace: default spec: targetRefs: - group: gateway.networking.k8s.io kind: Gateway name: nginx snippets: - context: http.server value: | proxy_intercept_errors on; error_page 400 401 403 404 405 408 409 410 429 500 502 503 504 = @error_pages; location @error_pages { internal; proxy_intercept_errors off; proxy_pass http://error-pages.error-pages.svc.cluster.local:8080; proxy_set_header X-Code $upstream_status; proxy_set_header Accept $http_accept; proxy_set_header X-Original-URI $request_uri; proxy_set_header Host $host; } ``` ```shell $ kubectl apply -f error-pages-policy.yaml snippetspolicy.gateway.nginx.org/error-pages created ``` Wait for the policy to be accepted: ```shell $ kubectl get snippetspolicy error-pages NAME AGE error-pages 5s $ kubectl get snippetspolicy error-pages -o jsonpath='{.status.ancestors[0].conditions[0].message}' The Policy is accepted ``` A few things in the snippet are worth explaining: * **`proxy_intercept_errors on`** - tells NGINX to intercept upstream responses with error status codes instead of passing them directly to the client. Without this directive, the raw backend error passes through. * **`error_page ... = @error_pages`** - lists the status codes to intercept and redirects them to the `@error_pages` named location. The `=` preserves the status code from the error-pages response. * **`proxy_intercept_errors off`** inside `@error_pages` - prevents NGINX from intercepting the response from `error-pages` itself. Without this, NGINX would try to intercept `error-pages`'s own 4xx/5xx response and loop. * **`proxy_set_header X-Code $upstream_status`** - passes the original error code to `error-pages`. Note that `$upstream_status` (not `$status`) must be used here: in the context of a named location triggered by `error_page`, `$status` is `0`, whereas `$upstream_status` retains the error code from the backend that triggered the interception. ## Verify custom error pages The same requests that previously returned bare NGINX error pages now return styled `error-pages` responses. Plain text (default, curl-friendly): ```shell $ curl -s http://httpbin.localtest.me/status/404 Error 404: Not Found The server can not find the requested page ``` JSON (via `Accept` header): ```shell $ curl -s -H "Accept: application/json" http://httpbin.localtest.me/status/404 { "error": true, "code": 404, "message": "Not Found", "description": "The server can not find the requested page" } ``` ```shell $ curl -s -H "Accept: application/json" http://httpbin.localtest.me/status/500 { "error": true, "code": 500, "message": "Internal Server Error", "description": "The server met an unexpected condition" } ``` XML (via `Accept` header): ```shell $ curl -s -H "Accept: application/xml" http://httpbin.localtest.me/status/503 503 Service Unavailable The server is temporarily overloading or down ``` The HTTP status code of each response matches the intercepted error: ```shell $ curl -s -o /dev/null -w "%{http_code}" http://httpbin.localtest.me/status/500 500 ``` ### Handle requests to unmatched hostnames (optional) By default, requests to hostnames not covered by any HTTPRoute are handled by NGF's auto-generated `default_server` block, which does `return 404` without any snippet - those responses pass through as plain NGINX HTML. To serve styled error pages for those requests too, add a catch-all HTTPRoute with no `hostnames` field. Gateway API routes without a `hostnames` field match any hostname in the listener. NGF creates a dedicated NGINX server block (`server_name ~^;`) for such a route, and `SnippetsPolicy` - which targets the whole Gateway - injects the snippet into it just like any other server block. Because `error-pages` lives in the `error-pages` namespace and the HTTPRoute is in `default`, a `ReferenceGrant` is required to authorize the cross-namespace backend reference. Save the following to `catch-all.yaml`: ```yaml # File: catch-all.yaml apiVersion: gateway.networking.k8s.io/v1beta1 kind: ReferenceGrant metadata: {name: allow-default-to-error-pages, namespace: error-pages} spec: from: [{group: gateway.networking.k8s.io, kind: HTTPRoute, namespace: default}] to: [{group: "", kind: Service, name: error-pages}] --- apiVersion: gateway.networking.k8s.io/v1 kind: HTTPRoute metadata: {name: catch-all, namespace: default} spec: parentRefs: [{name: nginx, namespace: default}] rules: - matches: [{path: {type: PathPrefix, value: /}}] backendRefs: [{name: error-pages, namespace: error-pages, port: 8080}] ``` ```shell $ kubectl apply -f catch-all.yaml referencegrant.gateway.networking.k8s.io/allow-default-to-error-pages created httproute.gateway.networking.k8s.io/catch-all created ``` Requests to unknown hostnames now return a styled 404: ```shell $ curl -s http://unknown.localtest.me/ Error 404: Not Found The server can not find the requested page ``` ```shell $ curl -s -H "Accept: application/json" http://unknown.localtest.me/ { "error": true, "code": 404, "message": "Not Found", "description": "The server can not find the requested page" } ``` Unmatched hostnames always return 404 - there is no backend to produce any other status code. ### Cleanup Delete the kind cluster to remove all resources at once: ```shell kind delete cluster --name error-pages-test-cluster ```