Merge pull request #32287 from bmcelvee/OSDOCS-2134

OSDOCS-2134 procedure for converting HTTP header case

Author: bmcelvee

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

@@ -146,6 +146,12 @@ By default, the policy is set to `Append`.
 * `IfNone` specifies that the Ingress Controller sets the headers if they are not already set.
 * `Never` specifies that the Ingress Controller never sets the headers, preserving any existing headers.
 
+By setting `headerNameCaseAdjustments`, you can specify case adjustments that can be applied to HTTP header names. Each adjustment is specified as an HTTP header name with the desired capitalization. For example, specifying `X-Forwarded-For` indicates that the `x-forwarded-for` HTTP header should be adjusted to have the specified capitalization.
+
+These adjustments are only applied to cleartext, edge-terminated, and re-encrypt routes, and only when using HTTP/1.
+
+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.
+
 |===
 
 

modules/nw-ingress-converting-http-header-case.adoc

@@ -0,0 +1,89 @@
+// Module included in the following assemblies:
+//
+// * ingress/ingress-operator.adoc
+
+[id="nw-ingress-converting-http-header-case_{context}"]
+= Converting HTTP header case
+
+HAProxy 2.2 lowercases HTTP header names by default, for example, changing `Host: xyz.com` to `host: xyz.com`. If legacy applications are sensitive to the capitalization of HTTP header names, use the Ingress Controller `spec.httpHeaders.headerNameCaseAdjustments` API field for a solution to accommodate legacy applications until they can be fixed.
+
+[IMPORTANT]
+====
+Because {product-title} 4.8 includes HAProxy 2.2, make sure to add the necessary configuration by using `spec.httpHeaders.headerNameCaseAdjustments` before upgrading.
+====
+
+.Prerequisites
+
+* You have installed the OpenShift CLI (`oc`).
+* You have access to the cluster as a user with the `cluster-admin` role.
+
+.Procedure
+
+As a cluster administrator, you can convert the HTTP header case by entering the `oc patch` command or by setting the `HeaderNameCaseAdjustments` field in the Ingress Controller YAML file.
+
+* Specify an HTTP header to be capitalized by entering the `oc patch` command.
+
+. Enter the `oc patch` command to change the HTTP `host` header to `Host`:
++
+[source,terminal]
+----
+$ oc -n openshift-ingress-operator patch ingresscontrollers/default --type=merge --patch='{"spec":{"httpHeaders":{"headerNameCaseAdjustments":["Host"]}}}'
+----
++
+. Annotate the route of the application:
++
+[source,terminal]
+----
+$ oc annotate routes/my-application haproxy.router.openshift.io/h1-adjust-case=true
+----
++
+The Ingress Controller then adjusts the `host` request header as specified.
+
+//Extra example if needed
+////
+* This example changes the HTTP `cache-control` header to `Cache-Control`:
++
+[source,terminal]
+----
+$ oc -n openshift-ingress-operator patch ingresscontrollers/default --type=json --patch='[{"op":"add","path":"/spec/httpHeaders/headerNameCaseAdjustments/-","value":"Cache-Control"}]'
+----
++
+The Ingress Controller adjusts the `cache-control` response header as specified.
+////
+
+* Specify adjustments using the `HeaderNameCaseAdjustments` field by configuring the Ingress Controller YAML file.
+
+. The following example Ingress Controller YAML adjusts the `host` header to `Host` for HTTP/1 requests to appropriately annotated routes:
++
+.Example Ingress Controller YAML
+[source,yaml]
+----
+apiVersion: operator.openshift.io/v1
+kind: IngressController
+metadata:
+  name: default
+  namespace: openshift-ingress-operator
+spec:
+  httpHeaders:
+    headerNameCaseAdjustments:
+    - Host
+----
++
+. The following example route enables HTTP response header name case adjustments using the `haproxy.router.openshift.io/h1-adjust-case` annotation:
++
+.Example route YAML
+[source,yaml]
+----
+apiVersion: route.openshift.io/v1
+kind: Route
+metadata:
+  annotations:
+    haproxy.router.openshift.io/h1-adjust-case: true <1>
+  name: my-application
+  namespace: my-application
+spec:
+  to:
+    kind: Service
+    name: my-application
+----
+<1> Set `haproxy.router.openshift.io/h1-adjust-case` to true.

networking/ingress-operator.adoc

@@ -60,6 +60,8 @@ include::modules/nw-http2-haproxy.adoc[leveloffset=+2]
 
 include::modules/nw-ingress-configuring-application-domain.adoc[leveloffset=+2]
 
+include::modules/nw-ingress-converting-http-header-case.adoc[leveloffset=+2]
+
 //include::modules/nw-ingress-select-route.adoc[leveloffset=+2]
 
 == Additional resources