Docs: Add guide on how to set a Maintenance Page. (#12525)

Co-authored-by: dmotte <[email protected]>

Author: k8s-infra-cherrypick-robot

docs/examples/customization/custom-errors/README.md

@@ -2,11 +2,12 @@
 
 This example demonstrates how to use a custom backend to render custom error pages.
 
-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.
+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.
 
 ## Customized default backend
 
-First, create the custom `default-backend`. It will be used by the Ingress controller later on.  
+First, create the custom `default-backend`. It will be used by the Ingress controller later on.
+
 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)
 in this project's GitHub repository.
 
@@ -38,11 +39,11 @@ If you do not already have an instance of the Ingress-Nginx Controller running,
 2. Edit the `ingress-nginx-controller` ConfigMap and create the key `custom-http-errors` with a value of `404,503`.
 
 3. Take note of the IP address assigned to the Ingress-Nginx Controller Service.
-    ```
-    $ kubectl get svc ingress-nginx
-    NAME            TYPE        CLUSTER-IP  EXTERNAL-IP   PORT(S)          AGE
-    ingress-nginx   ClusterIP   10.0.0.13   <none>        80/TCP,443/TCP   10m
-    ```
+   ```
+   $ kubectl get svc ingress-nginx
+   NAME            TYPE        CLUSTER-IP  EXTERNAL-IP   PORT(S)          AGE
+   ingress-nginx   ClusterIP   10.0.0.13   <none>        80/TCP,443/TCP   10m
+   ```
 
 !!! note
     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
 
 To go further with this example, feel free to deploy your own applications and Ingress objects, and validate that the
 responses are still in the correct format when a backend returns 503 (eg. if you scale a Deployment down to 0 replica).
+
+## Maintenance page
+
+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.
+
+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**.
+
+To do that:
+
+- Enable a **custom error page for the 503 HTTP error**, by following the guide above
+- Set the value of the `--watch-namespace-selector` flag to the name of some non-existent namespace, e.g. `nonexistent-namespace`
+  - This effectively prevents the NGINX Ingress Controller from reading `Ingress` resources from any namespace in the Kubernetes cluster
+- Set your `location-snippet` to `return 503;`, to make the NGINX Ingress Controller always return the 503 HTTP error page for all the requests