diff --git a/docs/modules/ROOT/pages/how-tos/ingress/xff-configuration.adoc b/docs/modules/ROOT/pages/how-tos/ingress/xff-configuration.adoc
new file mode 100644
index 00000000..e5740d49
--- /dev/null
+++ b/docs/modules/ROOT/pages/how-tos/ingress/xff-configuration.adoc
@@ -0,0 +1,26 @@
+= Configuring X-Forwarded-For handling
+
+This how-to explains how to configure the ingress' handling of the forwarded headers (`Forwarded` and `X-Forwarded-For`) on a per-route basis. 
+
+== Possible behaviours
+
+* *`append`*: By default, the ingress is configured to append the headers to any existing headers. If `Forwarded` and `X-Forwarded-For` headers are already present when the ingress receives a request, the existing values are preserved, and new values are appended by the ingress.
+* *`replace`*: If forwarded header handling is set to `replace`, any existing forwarded headers are discarded. Only the headers set by the ingress will be available.
+* *`never`*: If forwarded header handling is set to `never`, the ingress will never set these headers, and leave any existing headers untouched.
+* *`if-none`*: If forwarded header handling is set to `if-none`, the ingress will only set the headers if they're not already present. If any headers are present, they're left unchanged.
+
+== Annotating the route
+
+Forwarded header handling is configured by annotating the `Route` object.
+
+[source,console]
+----
+oc annotate route my_route haproxy.router.openshift.io/set-forwarded-headers="replace"
+----
+
+To change the forwarded header handling back to default, simply remove the annotation:
+
+[source,console]
+----
+oc annotate route my_route haproxy.router.openshift.io/set-forwarded-headers-
+----
diff --git a/docs/modules/ROOT/partials/nav.adoc b/docs/modules/ROOT/partials/nav.adoc
index e6f8749a..14a28e9d 100644
--- a/docs/modules/ROOT/partials/nav.adoc
+++ b/docs/modules/ROOT/partials/nav.adoc
@@ -104,6 +104,7 @@
 
 * Ingress
 ** xref:oc4:ROOT:how-tos/ingress/self-signed-ingress-cert.adoc[]
+** xref:oc4:ROOT:how-tos/ingress/xff-configuration.adoc[]
 
 
 * Storage