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,
effectively a bare http.ListenAndServe
at its core.
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 Accept
ed 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 totext/html
.STATUS_CODE_MAPPING
: in the format ofSRC_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 incustom-http-errors
while the destination status codes will be used to look up error responses.