Skip to content

Commit bb48461

Browse files
skrthomasskrthomas
committed
:OSDOCS-2456: adding procedure for customizing ingress error pages
1 parent c912306 commit bb48461

File tree

3 files changed

+115
-0
lines changed

3 files changed

+115
-0
lines changed

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

Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
1+
// Module filename: nw-customize-ingress-error-pages.adoc
2+
// Module included in the following assemblies:
3+
// * networking/ingress-controller-configuration.adoc
4+
5+
[id="nw-customize-ingress-error-pages_{context}"]
6+
= Customizing HAProxy error code response pages
7+
8+
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.
9+
10+
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:
11+
`error-page-503.http` and `error-page-404.http`.
12+
13+
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.
14+
15+
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.
16+
17+
[NOTE]
18+
====
19+
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.
20+
====
21+
22+
.Procedure
23+
24+
. Create a config map named `my-custom-error-code-pages` in the `openshift-config` namespace:
25+
+
26+
[source,terminal]
27+
----
28+
$ oc -n openshift-config create configmap my-custom-error-code-pages \
29+
--from-file=error-page-503.http \
30+
--from-file=error-page-404.http
31+
----
32+
33+
. Patch the Ingress Controller to reference the `my-custom-error-code-pages` config map by name:
34+
+
35+
[source,terminal]
36+
----
37+
$ oc patch -n openshift-ingress ingresscontroller/default --patch '{"spec":{"httpErrorCodePages": "my-custom-error-code-pages"}}' --type=merge
38+
----
39+
+
40+
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.
41+
42+
. Display the copy:
43+
+
44+
[source,terminal]
45+
----
46+
$ oc get cm default-errorpages -n openshift-ingress
47+
----
48+
+
49+
.Example output
50+
----
51+
NAME DATA AGE
52+
default-errorpages 2 25s <1>
53+
----
54+
<1> The example config map name is `default-errorpages` because the `default` Ingress Controller custom resource (CR) was patched.
55+
+
56+
57+
. 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:
58+
+
59+
* For 503 custom HTTP custom error code response:
60+
+
61+
[source,terminal]
62+
----
63+
$ oc -n openshift-ingress rsh <router_pod> cat /var/lib/haproxy/conf/error_code_pages/error-page-503.http
64+
----
65+
+
66+
* For 404 custom HTTP custom error code response:
67+
+
68+
[source,terminal]
69+
----
70+
$ oc -n openshift-ingress rsh <router_pod> cat /var/lib/haproxy/conf/error_code_pages/error-page-404.http
71+
----
72+
73+
.Verification
74+
75+
Verify your custom error code HTTP response:
76+
77+
. Create a test project and application:
78+
+
79+
[source,terminal]
80+
----
81+
$ oc new-project test-ingress
82+
----
83+
+
84+
[source,terminal]
85+
----
86+
$ oc new-app django-psql-example
87+
----
88+
89+
. For 503 custom http error code response:
90+
.. Stop all the pods for the application.
91+
.. Run the following curl command or visit the route hostname in the browser:
92+
+
93+
[source,terminal]
94+
----
95+
$ curl -vk <route_hostname>
96+
----
97+
. For 404 custom http error code response:
98+
.. Visit a non-existent route or an incorrect route.
99+
.. Run the following curl command or visit the route hostname in the browser:
100+
+
101+
[source,terminal]
102+
----
103+
$ curl -vk <route_hostname>
104+
----
105+
106+
. Check if the `errorfile` attribute is properly in the `haproxy.config` file:
107+
+
108+
[source,terminal]
109+
----
110+
$ oc -n openshift-ingress rsh <router> cat /var/lib/haproxy/conf/haproxy.config | grep errorfile
111+
----

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

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -153,6 +153,9 @@ These adjustments are only applied to cleartext, edge-terminated, and re-encrypt
153153

154154
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.
155155

156+
|`httpErrorCodePages`
157+
|`httpErrorCodePages` specifies custom HTTP error code response pages. By default, an IngressController uses error pages built into the IngressController image.
158+
156159
|`tuningOptions`
157160
|`tuningOptions` specifies options for tuning the performance of Ingress Controller pods.
158161

‎networking/ingress-operator.adoc‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -77,6 +77,7 @@ include::modules/nw-ingress-configuring-application-domain.adoc[leveloffset=+2]
7777

7878
include::modules/nw-ingress-converting-http-header-case.adoc[leveloffset=+2]
7979

80+
include::modules/nw-customize-ingress-error-pages.adoc[leveloffset=+2]
8081
//include::modules/nw-ingress-select-route.adoc[leveloffset=+2]
8182

8283
== Additional resources

0 commit comments

Comments
 (0)