[enterprise-4.9] OSDOCS-2456: adding procedure for customizing ingress error pages

modules/nw-customize-ingress-error-pages.adoc

@@ -0,0 +1,111 @@
+// Module filename: nw-customize-ingress-error-pages.adoc
+// Module included in the following assemblies:
+// * networking/ingress-controller-configuration.adoc
+
+[id="nw-customize-ingress-error-pages_{context}"]
+= Customizing HAProxy error code response pages
+
+As a cluster administrator, you can specify a custom error code response page for either 503, 404, or both error pages. The HAProxy router serves a 503 error page when the application pod is not running or a 404 error page when the requested URL does not exist. For example, if you customize the 503 error code response page, then the page is served when the application pod is not running, and the default 404 error code HTTP response page is served by the HAProxy router for an incorrect route or a non-existing route.
+
+Custom error code response pages are specified in a config map then patched to the Ingress Controller. The config map keys have two available file names as follows:
+`error-page-503.http` and `error-page-404.http`.
+
+Custom HTTP error code response pages must follow the link:https://www.haproxy.com/documentation/hapee/latest/configuration/config-sections/http-errors/[HAProxy HTTP error page configuration guidelines]. Here is an example of the default {product-title} HAProxy router link:https://raw.githubusercontent.com/openshift/router/master/images/router/haproxy/conf/error-page-503.http[http 503 error code response page]. You can use the default content as a template for creating your own custom page.
+
+By default, the HAProxy router serves only a 503 error page when the application is not running or when the route is incorrect or non-existent. This default behavior is the same as the behavior on {product-title} 4.8 and earlier. If a config map for the customization of an HTTP error code response is not provided, and you are using a custom HTTP error code response page, the router serves a default 404 or 503 error code response page.
+
+[NOTE]
+====
+If you use the {product-title} default 503 error code page as a template for your customizations, the headers in the file require an editor than can use CRLF line endings.
+====
+
+.Procedure
+
+. Create a config map named `my-custom-error-code-pages` in the `openshift-config` namespace:
++
+[source,terminal]
+----
+$ oc -n openshift-config create configmap my-custom-error-code-pages \
+--from-file=error-page-503.http \
+--from-file=error-page-404.http
+----
+
+. Patch the Ingress Controller to reference the `my-custom-error-code-pages` config map by name:
++
+[source,terminal]
+----
+$ oc patch -n openshift-ingress ingresscontroller/default --patch '{"spec":{"httpErrorCodePages": "my-custom-error-code-pages"}}' --type=merge
+----
++
+The Ingress Operator copies the `my-custom-error-code-pages` config map from the `openshift-config` namespace to the `openshift-ingress` namespace. The Operator names the config map according to the pattern, `<your_ingresscontroller_name>-errorpages`, in the `openshift-ingress` namespace.
+
+. Display the copy:
++
+[source,terminal]
+----
+$ oc get cm default-errorpages -n openshift-ingress
+----
++
+.Example output
+----
+NAME                       DATA   AGE
+default-errorpages         2      25s  <1>
+----
+<1> The example config map name is `default-errorpages` because the `default` Ingress Controller custom resource (CR) was patched.
++
+
+. Confirm that the config map containing the custom error response page mounts on the router volume where the config map key is the filename that has the custom HTTP error code response:
++
+* For 503 custom HTTP custom error code response:
++
+[source,terminal]
+----
+$ oc -n openshift-ingress rsh <router_pod> cat /var/lib/haproxy/conf/error_code_pages/error-page-503.http
+----
++
+* For 404 custom HTTP custom error code response:
++
+[source,terminal]
+----
+$ oc -n openshift-ingress rsh <router_pod> cat /var/lib/haproxy/conf/error_code_pages/error-page-404.http
+----
+
+.Verification
+
+Verify your custom error code HTTP response:
+
+. Create a test project and application:
++
+[source,terminal]
+----
+ $ oc new-project test-ingress
+----
++
+[source,terminal]
+----
+$ oc new-app django-psql-example
+----
+
+. For 503 custom http error code response:
+.. Stop all the pods for the application.
+.. Run the following curl command or visit the route hostname in the browser:
++
+[source,terminal]
+----
+$ curl -vk <route_hostname>
+----
+. For 404 custom http error code response:
+.. Visit a non-existent route or an incorrect route.
+.. Run the following curl command or visit the route hostname in the browser:
++
+[source,terminal]
+----
+$ curl -vk <route_hostname>
+----
+
+. Check if the `errorfile` attribute is properly in the `haproxy.config` file:
++
+[source,terminal]
+----
+$ oc -n openshift-ingress rsh <router> cat /var/lib/haproxy/conf/haproxy.config | grep errorfile
+----

modules/nw-ingress-controller-configuration-parameters.adoc

@@ -161,6 +161,9 @@ These adjustments are only applied to cleartext, edge-terminated, and re-encrypt
 
 For request headers, these adjustments are applied only for routes that have the `haproxy.router.openshift.io/h1-adjust-case=true` annotation. For response headers, these adjustments are applied to all HTTP responses. If this field is empty, no request headers are adjusted.
 
+|`httpErrorCodePages`
+|`httpErrorCodePages` specifies custom HTTP error code response pages. By default, an IngressController uses error pages built into the IngressController image.
+
 |`tuningOptions`
 |`tuningOptions` specifies options for tuning the performance of Ingress Controller pods.
 

networking/ingress-operator.adoc

@@ -77,6 +77,7 @@ include::modules/nw-ingress-configuring-application-domain.adoc[leveloffset=+2]
 
 include::modules/nw-ingress-converting-http-header-case.adoc[leveloffset=+2]
 
+include::modules/nw-customize-ingress-error-pages.adoc[leveloffset=+2]
 //include::modules/nw-ingress-select-route.adoc[leveloffset=+2]
 
 == Additional resources