</code></pre></div><p>This should have created a Deployment and a Service with the name <code>nginx-errors</code>.</p><divclass=highlight><pre><span></span><code>$ kubectl get deploy,svc
</code></pre></div><h2id=ingress-controller-configuration>Ingress controller configuration<aclass=headerlinkhref=#ingress-controller-configurationtitle="Permanent link"> ¶</a></h2><p>If you do not already have an instance of the Ingress-Nginx Controller running, deploy it according to the <ahref=../../../deploy/>deployment guide</a>, then follow these steps:</p><ol><li><p>Edit the <code>ingress-nginx-controller</code> Deployment and set the value of the <code>--default-backend-service</code> flag to the name of the newly created error backend.</p></li><li><p>Edit the <code>ingress-nginx-controller</code> ConfigMap and create the key <code>custom-http-errors</code> with a value of <code>404,503</code>.</p></li><li><p>Take note of the IP address assigned to the Ingress-Nginx Controller Service. <divclass=highlight><pre><span></span><code>$ kubectl get svc ingress-nginx
</code></pre></div></p></li></ol><divclass="admonition note"><pclass=admonition-title>Note</p><p>The <code>ingress-nginx</code> Service is of type <code>ClusterIP</code> in this example. This may vary depending on your environment. Make sure you can use the Service to reach NGINX before proceeding with the rest of this example.</p></div><h2id=testing-error-pages>Testing error pages<aclass=headerlinkhref=#testing-error-pagestitle="Permanent link"> ¶</a></h2><p>Let us send a couple of HTTP requests using cURL and validate everything is working as expected.</p><p>A request to the default backend returns a 404 error with a custom message:</p><divclass=highlight><pre><span></span><code>$ curl -D- http://10.0.0.13/
</code></pre></div><p>A request with a custom <code>Accept</code> header returns the corresponding document type (JSON):</p><divclass=highlight><pre><span></span><code>$ curl -D- -H 'Accept: application/json' http://10.0.0.13/
</code></pre></div><p>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).</p><h2id=maintenance-page>Maintenance page<aclass=headerlinkhref=#maintenance-pagetitle="Permanent link"> ¶</a></h2><p>You can also leverage custom error pages to set a <strong>"<em>Service under maintenance</em>" page</strong> for the whole cluster, useful to prevent users from accessing your services while you are performing planned scheduled maintenance.</p><p>When enabled, the maintenance page is served to the clients with an HTTP <ahref=https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/503><strong>503 Service Unavailable</strong></a> response <strong>status code</strong>.</p><p>To do that:</p><ul><li>Enable a <strong>custom error page for the 503 HTTP error</strong>, by following the guide above</li><li>Set the value of the <code>--watch-namespace-selector</code> flag to the name of some non-existent namespace, e.g. <code>nonexistent-namespace</code></li><li>This effectively prevents the NGINX Ingress Controller from reading <code>Ingress</code> resources from any namespace in the Kubernetes cluster</li><li>Set your <code>location-snippet</code> to <code>return 503;</code>, to make the NGINX Ingress Controller always return the 503 HTTP error page for all the requests</li></ul></article></div></div></main><footerclass=md-footer><divclass="md-footer-meta md-typeset"><divclass="md-footer-meta__inner md-grid"><divclass=md-copyright> Made with <ahref=https://squidfunk.github.io/mkdocs-material/target=_blankrel=noopener> Material for MkDocs </a></div></div></div></footer></div><divclass=md-dialogdata-md-component=dialog><divclass="md-dialog__inner md-typeset"></div></div><scriptid=__configtype=application/json>{"base":"../../..","features":["navigation.tabs","navigation.tabs.sticky","navigation.instant","navigation.sections"],"search":"../../../assets/javascripts/workers/search.f886a092.min.js","translations":{"clipboard.copied":"Copied to clipboard","clipboard.copy":"Copy to clipboard","search.result.more.one":"1 more on this page","search.result.more.other":"# more on this page","search.result.none":"No matching documents","search.result.one":"1 matching document","search.result.other":"# matching documents","search.result.placeholder":"Type to start searching","search.result.term.missing":"Missing","select.version":"Select version"}}</script><scriptsrc=../../../assets/javascripts/bundle.aecac24b.min.js></script></body></html>
