You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardexpand all lines: docs/examples/customization/custom-errors/README.md
+21-7
Original file line number
Diff line number
Diff line change
@@ -2,11 +2,12 @@
2
2
3
3
This example demonstrates how to use a custom backend to render custom error pages.
4
4
5
-
If you are using Helm Chart, look at [example values](https://github.com/kubernetes/ingress-nginx/blob/main/docs/examples/customization/custom-errors/custom-default-backend.helm.values.yaml) and don't forget to add [configMap](https://github.com/kubernetes/ingress-nginx/blob/main/docs/examples/customization/custom-errors/custom-default-backend-error_pages.configMap.yaml) to your deployment, otherwise continue with [Customized default backend](#customized-default-backend) manual deployment.
5
+
If you are using the Helm Chart, look at [example values](https://github.com/kubernetes/ingress-nginx/blob/main/docs/examples/customization/custom-errors/custom-default-backend.helm.values.yaml) and don't forget to add the [ConfigMap](https://github.com/kubernetes/ingress-nginx/blob/main/docs/examples/customization/custom-errors/custom-default-backend-error_pages.configMap.yaml) to your deployment. Otherwise, continue with [Customized default backend](#customized-default-backend) manual deployment.
6
6
7
7
## Customized default backend
8
8
9
-
First, create the custom `default-backend`. It will be used by the Ingress controller later on.
9
+
First, create the custom `default-backend`. It will be used by the Ingress controller later on.
10
+
10
11
To do that, you can take a look at the [example manifest](https://github.com/kubernetes/ingress-nginx/blob/main/docs/examples/customization/custom-errors/custom-default-backend.yaml)
11
12
in this project's GitHub repository.
12
13
@@ -38,11 +39,11 @@ If you do not already have an instance of the Ingress-Nginx Controller running,
38
39
2. Edit the `ingress-nginx-controller` ConfigMap and create the key `custom-http-errors` with a value of `404,503`.
39
40
40
41
3. Take note of the IP address assigned to the Ingress-Nginx Controller Service.
The `ingress-nginx` Service is of type `ClusterIP` in this example. This may vary depending on your environment.
@@ -85,3 +86,16 @@ Vary: Accept-Encoding
85
86
86
87
To go further with this example, feel free to deploy your own applications and Ingress objects, and validate that the
87
88
responses are still in the correct format when a backend returns 503 (eg. if you scale a Deployment down to 0 replica).
89
+
90
+
## Maintenance page
91
+
92
+
You can also leverage custom error pages to set a **"_Service under maintenance_" page** for the whole cluster, useful to prevent users from accessing your services while you are performing planned scheduled maintenance.
93
+
94
+
When enabled, the maintenance page is served to the clients with an HTTP [**503 Service Unavailable**](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/503) response **status code**.
95
+
96
+
To do that:
97
+
98
+
- Enable a **custom error page for the 503 HTTP error**, by following the guide above
99
+
- Set the value of the `--watch-namespace-selector` flag to the name of some non-existent namespace, e.g. `nonexistent-namespace`
100
+
- This effectively prevents the NGINX Ingress Controller from reading `Ingress` resources from any namespace in the Kubernetes cluster
101
+
- Set your `location-snippet` to `return 503;`, to make the NGINX Ingress Controller always return the 503 HTTP error page for all the requests
0 commit comments