-
Notifications
You must be signed in to change notification settings - Fork 471
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Ability to Customize HAProxy 2.x Error Page
- Loading branch information
Showing
1 changed file
with
146 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,146 @@ | ||
| --- | ||
| title: customize-error-code-pages | ||
| authors: | ||
| - "@miheer" | ||
| reviewers: | ||
| - "@Miciah" | ||
| - "@danehans" | ||
| - "@knobunc" | ||
| approvers: | ||
| - "@Miciah" | ||
| - "@danehans" | ||
| - "@knobunc" | ||
| creation-date: 2021-03-07 | ||
| last-updated: 2020-03-07 | ||
| status: implementable | ||
| see-also: | ||
| replaces: | ||
| superseded-by: | ||
| --- | ||
| # Customize error code paged returned by the haproxy router | ||
| ## Release Signoff Checklist | ||
| - [X] Enhancement is `implementable` | ||
| - [ ] Design details are appropriately documented from clear requirements | ||
| - [X] Test plan is defined | ||
| - [ ] Graduation criteria for dev preview, tech preview, GA | ||
| - [ ] User-facing documentation is created in [openshift-docs](https://github.com/openshift/openshift-docs/) | ||
| ## Summary | ||
| There is no supported method to customize an IngressController's error pages in OCP 4. | ||
| Users may want to customize an IngressController's error pages for branding or other reasons. | ||
| For example, users may want a custom HTTP 503 error page to be returned if no pod is available. | ||
| When the requested URI does not exist, users may want an IngressController to return a custom 404 page. | ||
| ## Motivation | ||
| The primary motivation is that users want to customize the error pages that are returned, for example for branding purposes. | ||
| Secondary motivation is that users say 503 page is served even when the page is not found when it shall serve 404. | ||
| The reason that happens is because we provide only 503 in our haproxy template. | ||
|
|
||
| ### Goals | ||
| Return a distinct HTTP 404 error page when the requested URI does not exist, instead of returning the HTTP 503 error page. | ||
|
|
||
| ### Non-Goal | ||
| Custom error pages for HTTP responses other than 503 and 404. | ||
| Enabling users to configure custom error pages for individual routes. | ||
|
|
||
| ## Proposal | ||
| 0. User creates a custom error code page configmap `my-custom-error-code-pages` in `openshift-config` | ||
| 1. The IngressController API is extended by adding an optional | ||
| `HttpErrorCodePages` field with type string | ||
| ```go | ||
| // httpErrorCodePages specifies a configmap with custom error pages. | ||
| // The administrator must create this configmap in the openshift-config namespace. | ||
| // This configmap should have keys in the format "error-page-<error code>.http", | ||
| // where <error code> is an HTTP error code. | ||
| // For example, "error-page-503.http" defines an error page for HTTP 503 responses. | ||
| // Currently only error pages for 503 and 404 responses can be customized. | ||
| // Each value in the configmap should be the full response, including HTTP headers. | ||
| // If this field is empty, the ingress controller uses the default error pages. | ||
| HttpErrorCodePages configv1.ConfigMapNameReference `json:"httpErrorCodePages,omitempty"` | ||
| ``` | ||
| Using the default, the router uses the default error pages used by haproxy. | ||
| The `HttpErrorCodePages` field enables the cluster administrator to | ||
| specify custom error code pages. | ||
| ```yaml | ||
| apiVersion: operator.openshift.io/v1 | ||
| kind: IngressController | ||
| metadata: | ||
| name: default | ||
| namespace: openshift-ingress-operator | ||
| spec: | ||
| httpErrorCodePage: "my-custom-error-code-pages" // my-custom-error-code-pages is the config map name with custom | ||
| //http error pages, created in openshift-config by cluster-admin. | ||
| ``` | ||
| 2. The configmap keys shall have the format error-page-`<error code>`.http. Right now only error-page-503.http and | ||
| error-page-404.http will be available. | ||
| ```yaml | ||
| $ oc -n openshift-config create configmap my-custom-error-code-pages\ | ||
| --from-file=error-page-503.http\ | ||
| --from-file=error-page-404.http | ||
| $ oc get configmaps my-custom-error-code-pages -o yaml | ||
| apiVersion: v1 | ||
| data: | ||
| error-page-503.http: |- | ||
| <your custom http response page contents> | ||
| error-page-404.http: | | ||
| <your custom http response page contents> | ||
| kind: ConfigMap | ||
| ``` | ||
| 3. `errorfile` stanzas need to be added as per https://www.haproxy.com/blog/serve-dynamic-custom-error-pages-with-haproxy/ | ||
| 4. default error pages will be added in openshift/router for the haproxy. | ||
| 5. A new controller to sync the cluster admin created configmap having custom error pages from `openshift-config` | ||
| to `openshift-ingress`. | ||
| 6. changes to ingress controller's function `desiredRouterDeployment` present in `deployment.go` to mount the configmap to the router. | ||
|
|
||
|
|
||
| ### Validation | ||
| 1. Omitting `spec.httpErrorCodePages` specifies the default behavior i.e serves default error code pages. | ||
| 2. If user specifies an invalid value, then the IngressController ignores the annotation. | ||
| 3. If a user provides incorrect filename than specified format i.e error-page-<error code>.http in | ||
| the keys of the configmap then it will be ignored and default page will be served. | ||
| 4. It is up to the user to ensure that the provided data is a valid HTTP response. | ||
|
|
||
| ### User Stories | ||
|
|
||
| #### As a cluster administrator, I expect to have custom error code pages getting served | ||
| 1. The administrator creates a configmap named http503page in the openshift-config namespace. | ||
| 2. The administrator patches the ingresscontroller to reference the http503page configmap by name. | ||
| 3. The ingress operator copies the http503page configmap from the openshift-config namespace to the | ||
| openshift-ingress namespace. | ||
| 4. The ingress operator configures the router deployment with a volume and volume mount that mounts | ||
| the custom error pages from the http503page configmap on top of the existing error pages in the | ||
| router pods. | ||
|
|
||
| ### Risks and Mitigations | ||
| 1. If a user provides a key that is not of the format `error-page-<error code>.http` in | ||
| the configmap, then the configmap will be ignored, and default error pages will be served. | ||
| 2. It is up to the user to ensure that the provided data is a valid HTTP response. | ||
|
|
||
| ## Design Details | ||
|
|
||
| ### Test Plan | ||
| Unit test cases will be added for the new controller which sync the configmap from `openshift-config` | ||
| to `openshift-ingress`. | ||
| Unit test cases will be added for the ingress controller where the router deployment get a volume mount | ||
| of the custom error code page | ||
|
|
||
| ### Graduation Criteria | ||
| N/A. | ||
|
|
||
| ### Upgrade / Downgrade Strategy | ||
| On upgrade, the default configuration does not perform error code page customization. On | ||
| downgrade, the operator ignores the `spec.httpErrorCodePages` API field. | ||
|
|
||
| ### Version Skew Strategy | ||
| N/A. | ||
|
|
||
| ## Implementation History | ||
| Following are the most salient PRs in the feature's history: | ||
| 1. https://github.com/openshift/api/pull/843 - Adds a field called `httpErrorCodePages` to the ingress controller API to get the custom error page configmap created | ||
| in the `openshift-config` namespace which is then synced to `openshift-ingress` namespace | ||
| 2. https://github.com/openshift/cluster-ingress-operator/pull/571 | ||
| a. Controller to sync configmaps from the `openshift-config` namespace to the `openshift-ingress` namespace ([NE-535](https://issues.redhat.com/browse/NE-535)). | ||
| b. Mount router deployment with the configmap ([NE-543](https://issues.redhat.com/browse/NE-543)). | ||
| ## Alternatives | ||
| N/A. |