add http header modification feature

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

@@ -199,6 +199,12 @@ 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.
 
+`actions` specifies options for performing certain actions on headers. This option only applies to cleartext, or unencrypted, HTTP connections and to secure HTTP connections for which the Ingress Controller terminates encryptions. Headers cannot be set or deleted for TLS passthrough connections. The `actions` subfield field has additional subfields `spec.httpHeader.actions.response` and `spec.httpHeader.actions.request`
+
+* The `response` subfield specifies a list of HTTP response headers to set or delete.
+
+* The `request` subfield specifies a list of HTTP request headers to set or delete.
+
 |`httpCompression`
 |`httpCompression` defines the policy for HTTP traffic compression.
 

modules/nw-ingress-set-or-delete-http-headers.adoc

@@ -0,0 +1,57 @@
+// Module included in the following assemblies:
+//
+// * networking/ingress-operator.adoc
+
+:_content-type: PROCEDURE
+[id="nw-ingress-set-or-delete-http-headers_{context}"]
+= Setting or deleting HTTP request and response headers in an Ingress Controller
+
+Certain HTTP request and response headers might need to be set or deleted for compliance purposes or other reasons. You can set or delete these headers either for all routes served by an Ingress Controller or for specific routes.
+
+For example, you might want to migrate an application running on your cluster to use mutual TLS, which requires that your application check for an X-Forwarded-Client-Cert request header, but the {product-title} default Ingress Controller provides an X-SSL-Client-Der request header.
+
+The following procedure modifies the Ingress Controller to set the X-Forwarded-Client-Cert request header, and delete the X-SSL-Client-Der request header.
+
+.Prerequisites
+. You have installed the OpenShift CLI (`oc`).
+. You have access to an {product-title} cluster as a user with the `cluster-admin` role.
+
+.Procedure
+. Edit the Ingress Controller resource:
++
+[source,terminal]
+----
+$ oc -n openshift-ingress-operator edit ingresscontroller/default
+----
+
+. Replace the X-SSL-Client-Der HTTP request header with the X-Forwarded-Client-Cert HTTP request header:
++
+[source,yaml]
+----
+apiVersion: operator.openshift.io/v1
+kind: IngressController
+metadata:
+  name: default
+  namespace: openshift-ingress-operator
+spec:
+  httpHeaders:
+    actions: <1>
+      request: <2>
+      - name: X-Forwarded-Client-Cert <3>
+        action:
+          type: Set <4>
+          set:
+           value: "%{+Q}[ssl_c_der,base64]" <5>
+      - name: X-SSL-Client-Der
+        action:
+          type: Delete
+----
+<1> The list of actions you want to perform on the HTTP headers.
+<2> The type of header you want to change. In this case, a request header.
+<3> The name of the header you want to change. For a list of available headers you can set or delete, see xxx.
+<4> The type of action being taken on the header. This field can have the value `Set` or `Delete`.
+<5> When setting HTTP headers, you must provide a `value`. The value can be a string from a list of available directives for that header, for example `DENY`, or it can be a dynamic value that will be interpreted using HAProxy's dynamic value syntax. In this case, a dynamic value is added.
+
+. Save the file to apply the changes.
+
+Modifying HTTP headers using the Ingress Controller is a global change that will affect all routes served by the Ingress Controller.

modules/nw-route-set-or-delete-http-headers.adoc

@@ -0,0 +1,58 @@
+// Module included in the following assemblies:
+//
+// * networking/route-configuration.adoc
+
+:_content-type: PROCEDURE
+[id="nw-route-set-or-delete-http-headers_{context}"]
+= Setting or deleting HTTP request and response headers in a route
+
+Certain HTTP request and response headers might need to be set or deleted for compliance purposes or other reasons. You can set or delete these headers either for all routes served by an Ingress Controller or for specific routes.
+
+For example, you might want to enable a web application to serve content in alternate locations for specific routes if that content is written in multiple languages, even if there is a default global location specified by the Ingress Controller serving the routes.
+
+The following procedure creates a route that sets the Content-Location HTTP request header so that the URL associated with the application, `\https://app.example.com`, directs to the location `\https://app.example.com/lang/en-us` that way anyone using that specific route is accessing web content written in American English.
+
+.Prerequisites
+. You have installed the OpenShift CLI (`oc`).
+. You are logged into an {product-title} cluster as a project administrator.
+. You have an web application that exposes a port and an HTTP or TLS endpoint listening for traffic on the port.
+
+.Procedure
+. Create a route definition, `app-example-route.yaml`:
++
+.YAML definition of the created route with HTTP header directives
+[source,yaml]
+----
+apiVersion: route.openshift.io/v1
+kind: Route
+...
+spec:
+  host: app.example.com
+  tls:
+    termination: edge
+  to:
+    kind: Service
+    name: app-example
+  httpHeaders:
+    actions: <1>
+      response: <2>
+      - name: Content-Location <3>
+      action:
+        type: Set <4>
+        set:
+          value: /lang/en-us <5>
+----
+<1> The list of actions you want to perform on the HTTP headers.
+<2> The type of header you want to change. In this case, a response header.
+<3> The name of the header you want to change. For a list of available headers you can set or delete, see xxx.
+<4> The type of action being taken on the header. This field can have the value `Set` or `Delete`.
+<5> When setting HTTP headers, you must provide a `value`. The value can be a string from a list of available directives for that header, for example `DENY`, or it can be a dynamic value that will be interpreted using HAProxy's dynamic value syntax. Int this case, the value is set to the relative location of the content.
+
+. Create a route to your existing web application using the newly created route definition:
++
+[source,terminal]
+----
+$ oc -n app-example create -f app-example-route.yaml
+----
+
+For HTTP request headers, the actions specified in the route definitions are executed after any actions performed on HTTP request headers in the Ingress Controller. This means that any values set for those request headers in a route will take precedence over the ones set in the Ingress Controller. For more information on the processing order of HTTP headers, see _HTTP header configuration_.

networking/ingress-operator.adoc

@@ -79,6 +79,8 @@ include::modules/nw-route-admission-policy.adoc[leveloffset=+2]
 
 include::modules/using-wildcard-routes.adoc[leveloffset=+2]
 
+include::modules/nw-ingress-set-or-delete-http-headers.adoc[leveloffset=+2]
+
 include::modules/nw-using-ingress-forwarded.adoc[leveloffset=+2]
 
 include::modules/nw-http2-haproxy.adoc[leveloffset=+2]

networking/routes/route-configuration.adoc

@@ -53,6 +53,8 @@ include::modules/nw-annotating-a-route-with-a-cookie-name.adoc[leveloffset=+2]
 
 include::modules/nw-path-based-routes.adoc[leveloffset=+1]
 
+include::modules/nw-route-set-or-delete-http-headers.adoc[leveloffset=+1]
+
 include::modules/nw-route-specific-annotations.adoc[leveloffset=+1]
 
 ifndef::openshift-rosa,openshift-dedicated[]