Why customize default error pages?

By default, when your service is not reachable or encounters issues, generic error pages are returned to the end user (e.g., "404 Not Found" or "503 Service Unavailable"). These pages are managed by the NGINX Ingress controller, they are functional but lack branding or contextual information, which can be a poor user experience for end-users.

Customizing these error pages provides several benefits:

• Branding Consistency: Custom pages allow you to maintain your brand’s look and feel, even during errors, which is especially important for customer-facing applications.

• Security Improvements: Default error pages often reveal that the server is running NGINX and may disclose other details about the underlying infrastructure. By customizing these pages, you can mask this information, reducing the attack surface and making it harder for potential attackers to exploit vulnerabilities.

Here is an example while having a 404 Nginx error without any customization:

Activate default backend

The default backend in NGINX is a fallback service used to handle requests that do not match any defined ingress rules, usually serving a default response like a 404 error. Enabling the default_backend will replace the standard NGINX error pages with a minimalistic default error page. While it’s a simple improvement, it doesn’t include custom branding or extensive information.

To enable the default_backend provided by NGINX, you need to modify the advanced settings at the cluster level:

1. Set the nginx.default_backend.enabled cluster advanded setting to true. This activates the default backend for your NGINX Ingress Controller.

2. Specify the HTTP error codes that should be redirected to this default backend by modifying the nginx.controller.custom_http_errors cluster advanced setting and service advanced setting. Provide a comma-separated list of error codes you want to handle. For example: "404,500".

3. After applying these changes, you must redeploy the cluster for the settings to take effect.

Here’s an example of what the default error page looks like:

If you define HTTP error codes at the cluster level, it will allow custom pages to be displayed for all URLs within: https://*.z<cluster_shortid>.domain

However, this will not apply to specific paths deployed behind it, such as: https://*.z<cluster_shortid>.domain/notfound

To handle those cases, you can also specify the HTTP error codes at the service level using the advanced setting: network.ingress.nginx_custom_http_errors

Use your own default backend

You also have the option to specify your own Docker image for the default_backend. To do this, update the following cluster advanced settings:

1. nginx.default_backend.image_repository: Provide the name of the Docker image repository. Note that the image must be hosted on a public repository so it can be pulled by the cluster nodes.
2. nginx.default_backend.image_tag: Specify the tag version of the image to be used.

Ensure that the Docker image supports the same architecture as your cluster nodes. For example, if you're using Karpenter with nodes that may run on either AMD64 or ARM64 architectures, the image must be available in both architectures (multi-arch support). By specifying these settings, you can customize the backend to suit your needs while ensuring compatibility with your cluster infrastructure. The port 8080 has to be exposed.

Here’s an example of what the error page looks like: