nginx-errors

This is a minimal and robust custom error backend for NGINX Ingress Controller based on the official example.

Example

First, turn on custom-http-errors in your controller, e.g. custom-http-errors: 404,494,500,529.

FROM hexcles/nginx-errors:latest

# Map some non-standard status codes to their standard counterparts.
ENV STATUS_CODE_MAPPING="494:400,529:503"

# Customize HTML response for 404.
COPY 404.html /www/404.html

# Customize JSON response for 5xx.
COPY 5xx.json /www/5xx.json

Design

The main design goal is minimalism, through which we also achieve robustness (the priority is in that order). It uses only Go standard libraries, and tries to do as much during init() as possible, including reading all response files into memory. Once it starts, it is effectively a simple http.ListenAndServe serving bytes from memory.

The binary is statically built with CGO disabled. The Docker image is also minimal (built from scratch) without a shell or even the usual FHS.

Customization

Customization is done through building another Docker image on top of this one, where you can set environment variables to configure behaviours and/or overlay some files to customize the error responses.

Custom error responses

You can put [code].[ext] in /www of the container to customize the responses for certain status codes and Accepted MIME types as requested by the client.

• The [code] portion of the file name can be either a specific status code (e.g. 404), or a range of codes in the form of e.g. 4xx.
• The [ext] portion of the file name should correspond to the included /etc/mime.types (you can also overlay this file in your Docker image if you need a MIME type that is not included).

The image includes default error responses for 404, 4xx, 500 and 5xx in HTML and JSON respectively.

ENV Configurations

• DEBUG: turn on debug logging and response headers. (Do NOT use in production.)
• DEFAULT_RESPONSE_FORMAT: set the default response format when the there is no requested MIME type or it cannot be recognized. Default to text/html.
• STATUS_CODE_MAPPING: in the format of SRC_A:DST_A,SRC_B:DST_B,... mapping source status codes (returned by your backend application) to destination status codes (seen by the client). Note that you should put the source status codes in custom-http-errors while the destination status codes will be used to look up error responses.