Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add how-to for configuring XFF handling #279

Closed
wants to merge 1 commit into from
Closed

Add how-to for configuring XFF handling #279

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 26 additions & 0 deletions docs/modules/ROOT/pages/how-tos/ingress/xff-configuration.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
This how-to explains how to configure the ingress' handling of the forwarded headers (`Forwarded` and `X-Forwarded-For`) on a per-route basis.
This how-to explains how to customize how the forwarding headers (`Forwarded` and `X-Forwarded-For`) are handled by the OpenShift ingress router 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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
* *`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.
* *`append`*: By default, the OpenShift router is configured to append the headers to any existing headers.
If `Forwarded` and `X-Forwarded-For` headers are already present when the OpenShift router receives a request, the existing values are preserved, and new values are appended by the router.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Consider using the following formatting:

Suggested change
* *`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.
`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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
* *`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.
* *`replace`*: If forwarded header handling is set to `replace`, any existing forwarded headers are discarded.
Only the headers set by the OpenShift router 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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
* *`never`*: If forwarded header handling is set to `never`, the ingress will never set these headers, and leave any existing headers untouched.
* *`never`*: If forwarded header handling is set to `never`, the OpenShift router 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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
* *`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.
* *`if-none`*: If forwarded header handling is set to `if-none`, the OpenShift router 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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Probably makes sense to note that the annotations can also be set on Ingress objects which are managed by the ingresstoroute controller


[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-
----
1 change: 1 addition & 0 deletions docs/modules/ROOT/partials/nav.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down