-
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
130 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,130 @@ | ||
| --- | ||
| 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 and reasonable method to customize the HAProxy 2.x error page in OCP 4.x | ||
| It's also important that the right page as per user requirements is served at the right moment. | ||
| Example - 503 error page shall be returned if no pod is available. | ||
| But when the URI is wrong/does not exist, we should return 404 or a customized 404 page as per user requirements. | ||
| Using this feature, user can provide custom http pages for 503 and 404 for the haproxy router by adding these pages | ||
| in a configmap using --file attribute. | ||
| ## Motivation | ||
| 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 | ||
| 1. Enable the cluster administrator to specify custom error code pages for haproxy router to serve them at the right moment. | ||
|
|
||
| ### Non-Goal | ||
| TBD | ||
|
|
||
| ## Proposal | ||
| 0. User creates a custom error code page configmap `http503page` 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 string `json:"httpErrorCodePages,omitempty"` | ||
| ``` | ||
| Using the default, the router uses the default error pages used by haproxy. | ||
| The `HttpErrorCodePage` 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. | ||
| 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.httpErrorCodePage` 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 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. | ||
| 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 an field called `httpErrorCodePages` to the ingress controller API to get the custom error page configmap created | ||
| in 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 openshift config namespace to openshift-ingress namespace NE-535 | ||
| b. Mount router deployment with the configmap NE-543 | ||
| ## Alternatives | ||
| N/A. |