Skip to content

Commit b38fd64

Browse files
ShaunaDiazShaunaDiaz
authored
Merge pull request #76762 from ShaunaDiaz/OSDOCS-9693
OSDOCS-9693: adds route config MicroShift
2 parents 46db037 + c37d42f commit b38fd64

14 files changed

+216
-37
lines changed

‎_topic_maps/_topic_map_ms.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -430,6 +430,8 @@ Topics:
430430
File: microshift-cni-multus
431431
- Name: Configuring and using multiple networks
432432
File: microshift-cni-multus-using
433+
- Name: Configuring routes
434+
File: microshift-configuring-routes
433435
- Name: Firewall configuration
434436
File: microshift-firewall
435437
- Name: Networking settings for fully disconnected hosts

‎microshift_networking/microshift-configuring-routes.adoc

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
:_mod-docs-content-type: ASSEMBLY
2+
[id="microshift-configuring-routes"]
3+
= Configuring routes
4+
include::_attributes/attributes-microshift.adoc[]
5+
:context: microshift-configuring-routes
6+
7+
toc::[]
8+
9+
You can configure routes for {microshift-short} for clusters.
10+
11+
//OCP module, edit with care; Creating an insecure/http route
12+
include::modules/nw-creating-a-route.adoc[leveloffset=+1]
13+
14+
//OCP module, edit with care; HTTP Strict Transport Security
15+
include::modules/nw-enabling-hsts.adoc[leveloffset=+2]
16+
17+
//OCP module, edit with care; Enabling HTTP strict transport security per-route
18+
include::modules/nw-enabling-hsts-per-route.adoc[leveloffset=+2]
19+
20+
//OCP module, edit with care; Disabling HTTP strict transport security per-route
21+
include::modules/nw-disabling-hsts.adoc[leveloffset=+2]
22+
23+
//Enforcing HTTP strict transport security per-domain
24+
include::modules/microshift-nw-enforcing-hsts-per-domain.adoc[leveloffset=+2]
25+
26+
//OCP module, edit with care; Troubleshooting Throughput Issues
27+
include::modules/nw-throughput-troubleshoot.adoc[leveloffset=+1]
28+
29+
//OCP module, edit with care; Using cookies to keep route statefulness
30+
include::modules/nw-using-cookies-keep-route-statefulness.adoc[leveloffset=+1]
31+
32+
//OCP module, edit with care; Using cookies to keep route statefulness
33+
include::modules/nw-annotating-a-route-with-a-cookie-name.adoc[leveloffset=+2]
34+
35+
//OCP module, edit with care
36+
include::modules/nw-path-based-routes.adoc[leveloffset=+1]
37+
38+
//OCP module, edit with care; just use the `Route` CR
39+
include::modules/nw-http-header-configuration.adoc[leveloffset=+1]
40+
41+
//OCP module, edit with care
42+
include::modules/nw-route-set-or-delete-http-headers.adoc[leveloffset=+1]
43+
44+
//OCP module, edit with care
45+
include::modules/nw-ingress-creating-a-route-via-an-ingress.adoc[leveloffset=+1]
46+
47+
//OCP module, edit with care
48+
include::modules/nw-ingress-edge-route-default-certificate.adoc[leveloffset=+1]
49+
50+
//OCP module, edit with care
51+
include::modules/nw-ingress-reencrypt-route-custom-cert.adoc[leveloffset=+1]
52+
53+
[id="microshift-secured-routes_{context}"]
54+
== Secured routes
55+
56+
Secure routes provide the ability to use several types of TLS termination to serve certificates to the client. The following links to the {OCP} documentation describe how to create re-encrypt, edge, and passthrough routes with custom certificates.
57+
58+
* link:https://docs.redhat.com/en/documentation/openshift_container_platform/{ocp-version}/html/networking/configuring-routes#nw-ingress-creating-a-reencrypt-route-with-a-custom-certificate_secured-routes[Creating a re-encrypt route with a custom certificate]
59+
60+
* link:https://docs.redhat.com/en/documentation/openshift_container_platform/4.15/html/networking/configuring-routes#nw-ingress-creating-an-edge-route-with-a-custom-certificate_secured-routes[Creating an edge route with a custom certificate]
61+
62+
* link:https://docs.redhat.com/en/documentation/openshift_container_platform/4.15/html/networking/configuring-routes#nw-ingress-creating-a-passthrough-route_secured-routes[Creating a passthrough route]

‎modules/microshift-nw-enforcing-hsts-per-domain.adoc

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * microshift_networking/microshift-configuring-routes.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="microshift-nw-enforcing-hsts-per-domain_{context}"]
7+
= Enforcing HTTP Strict Transport Security per-domain
8+
9+
You can configure a route with a compliant HSTS policy annotation. To handle upgraded clusters with non-compliant HSTS routes, you can update the manifests at the source and apply the updates.
10+
11+
You cannot use `oc expose route` or `oc create route` commands to add a route in a domain that enforces HSTS because the API for these commands does not accept annotations.
12+
13+
[IMPORTANT]
14+
====
15+
HSTS cannot be applied to insecure, or non-TLS, routes.
16+
====
17+
18+
.Prerequisites
19+
* You have root access to the cluster.
20+
* You installed the {oc-first}.
21+
22+
.Procedure
23+
24+
* Apply HSTS to all routes in the cluster by running the following `oc annotate command`:
25+
+
26+
[source,terminal]
27+
----
28+
$ oc annotate route --all --all-namespaces --overwrite=true "haproxy.router.openshift.io/hsts_header"="max-age=31536000;preload;includeSubDomains"
29+
----
30+
+
31+
* Apply HSTS to all routes in a particular namespace by running the following `oc annotate command`:
32+
+
33+
[source,terminal]
34+
----
35+
$ oc annotate route --all -n <my_namespace> --overwrite=true "haproxy.router.openshift.io/hsts_header"="max-age=31536000;preload;includeSubDomains" <1>
36+
----
37+
<1> Replace _<my_namespace> with the namespace you want to use.
38+
39+
.Verification
40+
* Review the HSTS annotations on all routes by running the following command:
41+
+
42+
[source,terminal]
43+
----
44+
$ oc get route --all-namespaces -o go-template='{{range .items}}{{if .metadata.annotations}}{{$a := index .metadata.annotations "haproxy.router.openshift.io/hsts_header"}}{{$n := .metadata.name}}{{with $a}}Name: {{$n}} HSTS: {{$a}}{{"\n"}}{{else}}{{""}}{{end}}{{end}}{{end}}'
45+
----
46+
+
47+
.Example output
48+
[source,terminal]
49+
----
50+
Name: <_routename_> HSTS: max-age=31536000;preload;includeSubDomains
51+
----

‎modules/nw-annotating-a-route-with-a-cookie-name.adoc

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,12 +5,13 @@
55
// Module included in the following assemblies:
66
//
77
// * networking/configuring-routing.adoc
8+
// * microshift_networking/microshift-configuring-routes.adoc
89

910
:_mod-docs-content-type: PROCEDURE
1011
[id="nw-annotating-a-route-with-a-cookie-name_{context}"]
1112
= Annotating a route with a cookie
1213

13-
You can set a cookie name to overwrite the default, auto-generated one for the route. This allows the application receiving route traffic to know the cookie name. By deleting the cookie it can force the next request to re-choose an endpoint. So, if a server was overloaded it tries to remove the requests from the client and redistribute them.
14+
You can set a cookie name to overwrite the default, auto-generated one for the route. This allows the application receiving route traffic to know the cookie name. Deleting the cookie can force the next request to re-choose an endpoint. The result is that if a server is overloaded, that server tries to remove the requests from the client and redistribute them.
1415

1516
.Procedure
1617

‎modules/nw-disabling-hsts.adoc

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
// Module included in the following assemblies:
22
// * networking/configuring-routing.adoc
3+
// * microshift_networking/microshift-configuring-routes.adoc
34

45
:_mod-docs-content-type: PROCEDURE
56
[id="nw-disabling-hsts_{context}"]
@@ -8,9 +9,13 @@
89
To disable HTTP strict transport security (HSTS) per-route, you can set the `max-age` value in the route annotation to `0`.
910

1011
.Prerequisites
11-
12+
ifndef::microshift[]
1213
* You are logged in to the cluster with a user with administrator privileges for the project.
13-
* You installed the `oc` CLI.
14+
endif::microshift[]
15+
ifdef::microshift[]
16+
* You have root access to the cluster.
17+
endif::microshift[]
18+
* You installed the {oc-first}.
1419

1520
.Procedure
1621

‎modules/nw-enabling-hsts-per-route.adoc

Lines changed: 8 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
// Module included in the following assemblies:
22
// * networking/configuring-routing.adoc
3+
// * microshift_networking/microshift-configuring-routes.adoc
34

45
:_mod-docs-content-type: PROCEDURE
56
[id="nw-enabling-hsts-per-route_{context}"]
@@ -8,9 +9,13 @@
89
HTTP strict transport security (HSTS) is implemented in the HAProxy template and applied to edge and re-encrypt routes that have the `haproxy.router.openshift.io/hsts_header` annotation.
910

1011
.Prerequisites
11-
12+
ifndef::microshift[]
1213
* You are logged in to the cluster with a user with administrator privileges for the project.
13-
* You installed the `oc` CLI.
14+
endif::microshift[]
15+
ifdef::microshift[]
16+
* You have root access to the cluster.
17+
endif::microshift[]
18+
* You installed the {oc-first}.
1419

1520
.Procedure
1621

@@ -21,7 +26,7 @@ HTTP strict transport security (HSTS) is implemented in the HAProxy template and
2126
$ oc annotate route <route_name> -n <namespace> --overwrite=true "haproxy.router.openshift.io/hsts_header"="max-age=31536000;\ <1>
2227
includeSubDomains;preload"
2328
----
24-
<1> In this example, the maximum age is set to `31536000` ms, which is approximately eight and a half hours.
29+
<1> In this example, the maximum age is set to `31536000` ms, which is approximately 8.5 hours.
2530
+
2631
[NOTE]
2732
====

‎modules/nw-enabling-hsts.adoc

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
// Module filename: nw-enabling-hsts.adoc
22
// Module included in the following assemblies:
33
// * networking/configuring-routing.adoc
4+
// * microshift_networking/microshift-configuring-routes.adoc
45

56
[id="nw-enabling-hsts_{context}"]
67
= HTTP Strict Transport Security

‎modules/nw-enforcing-hsts-per-domain.adoc

Lines changed: 10 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
// Module included in the following assemblies:
2+
//
23
// * networking/configuring-routing.adoc
34

45
:_mod-docs-content-type: PROCEDURE
@@ -25,13 +26,12 @@ HSTS cannot be applied to insecure, or non-TLS routes, even if HSTS is requested
2526
====
2627

2728
.Prerequisites
28-
2929
* You are logged in to the cluster with a user with administrator privileges for the project.
30-
* You installed the `oc` CLI.
30+
* You installed the {oc-first}.
3131
3232
.Procedure
3333

34-
. Edit the Ingress config file:
34+
. Edit the Ingress configuration YAML by running the following command and updating fields as needed:
3535
+
3636
[source,terminal]
3737
----
@@ -47,19 +47,19 @@ metadata:
4747
name: cluster
4848
spec:
4949
domain: 'hello-openshift-default.apps.username.devcluster.openshift.com'
50-
requiredHSTSPolicies: <1>
51-
- domainPatterns: <2>
50+
requiredHSTSPolicies: # <1>
51+
- domainPatterns: # <2>
5252
- '*hello-openshift-default.apps.username.devcluster.openshift.com'
5353
- '*hello-openshift-default2.apps.username.devcluster.openshift.com'
54-
namespaceSelector: <3>
54+
namespaceSelector: # <3>
5555
matchLabels:
5656
myPolicy: strict
57-
maxAge: <4>
57+
maxAge: # <4>
5858
smallestMaxAge: 1
5959
largestMaxAge: 31536000
60-
preloadPolicy: RequirePreload <5>
61-
includeSubDomainsPolicy: RequireIncludeSubDomains <6>
62-
- domainPatterns: <2>
60+
preloadPolicy: RequirePreload # <5>
61+
includeSubDomainsPolicy: RequireIncludeSubDomains # <6>
62+
- domainPatterns:
6363
- 'abc.example.com'
6464
- '*xyz.example.com'
6565
namespaceSelector:

‎modules/nw-http-header-configuration.adoc

Lines changed: 57 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -6,14 +6,29 @@
66
:_mod-docs-content-type: CONCEPT
77
[id="nw-http-header-configuration_{context}"]
88
= HTTP header configuration
9-
9+
ifndef::microshift[]
1010
{product-title} provides different methods for working with HTTP headers. When setting or deleting headers, you can use specific fields in the Ingress Controller or an individual route to modify request and response headers. You can also set certain headers by using route annotations. The various ways of configuring headers can present challenges when working together.
11+
endif::microshift[]
12+
13+
ifdef::microshift[]
14+
When setting or deleting headers, you can use an individual route to modify request and response headers. You can also set certain headers by using route annotations. The various ways of configuring headers can present challenges when working together.
15+
endif::microshift[]
1116

17+
ifndef::microshift[]
1218
[NOTE]
1319
====
1420
You can only set or delete headers within an `IngressController` or `Route` CR, you cannot append them. If an HTTP header is set with a value, that value must be complete and not require appending in the future. In situations where it makes sense to append a header, such as the X-Forwarded-For header, use the `spec.httpHeaders.forwardedHeaderPolicy` field, instead of `spec.httpHeaders.actions`.
1521
====
22+
endif::microshift[]
1623

24+
ifdef::microshift[]
25+
[NOTE]
26+
====
27+
You can only set or delete headers within a `Route` CR. You cannot append headers. If an HTTP header is set with a value, that value must be complete and not require appending in the future. In situations where it makes sense to append a header, such as the X-Forwarded-For header, use the `spec.httpHeaders.forwardedHeaderPolicy` field, instead of `spec.httpHeaders.actions`.
28+
====
29+
endif::microshift[]
30+
31+
ifndef::microshift[]
1732
[id="nw-http-header-configuration-order_{context}"]
1833
== Order of precedence
1934

@@ -43,6 +58,7 @@ spec:
4358
----
4459

4560
A route owner sets the same response header that the cluster administrator set in the Ingress Controller, but with the value `SAMEORIGIN` using the following configuration:
61+
endif::microshift[]
4662

4763
.Example `Route` spec
4864
[source,yaml]
@@ -60,10 +76,10 @@ spec:
6076
set:
6177
value: SAMEORIGIN
6278
----
79+
ifndef::microshift[]
80+
When both the `IngressController` spec and `Route` spec are configuring the X-Frame-Options response header, then the value set for this header at the global level in the Ingress Controller takes precedence, even if a specific route allows frames. For a request header, the `Route` spec value overrides the `IngressController` spec value.
6381

64-
When both the `IngressController` spec and `Route` spec are configuring the X-Frame-Options header, then the value set for this header at the global level in the Ingress Controller will take precedence, even if a specific route allows frames.
65-
66-
This prioritzation occurs because the `haproxy.config` file uses the following logic, where the Ingress Controller is considered the front end and individual routes are considered the back end. The header value `DENY` applied to the front end configurations overrides the same header with the value `SAMEORIGIN` that is set in the back end:
82+
This prioritization occurs because the `haproxy.config` file uses the following logic, where the Ingress Controller is considered the front end and individual routes are considered the back end. The header value `DENY` applied to the front end configurations overrides the same header with the value `SAMEORIGIN` that is set in the back end:
6783

6884
[source,text]
6985
----
@@ -81,12 +97,18 @@ backend be_secure:openshift-monitoring:alertmanager-main
8197
----
8298

8399
Additionally, any actions defined in either the Ingress Controller or a route override values set using route annotations.
100+
endif::microshift[]
101+
102+
ifdef::microshift[]
103+
Any actions defined in a route override values set using route annotations.
104+
endif::microshift[]
84105

85106
[id="nw-http-header-configuration-special-cases_{context}"]
86107
== Special case headers
87108

88109
The following headers are either prevented entirely from being set or deleted, or allowed under specific circumstances:
89110

111+
ifndef::microshift[]
90112
.Special case header configuration options
91113
[cols="5*a",options="header"]
92114
|===
@@ -120,3 +142,34 @@ The following headers are either prevented entirely from being set or deleted, o
120142
* the `haproxy.router.openshift.io/cookie_name` route annotation
121143

122144
|===
145+
endif::microshift[]
146+
147+
ifdef::microshift[]
148+
|===
149+
|Header name |Configurable using `Route` spec |Reason for disallowment |Configurable using another method
150+
151+
|`proxy`
152+
|No
153+
|The `proxy` HTTP request header can be used to exploit vulnerable CGI applications by injecting the header value into the `HTTP_PROXY` environment variable. The `proxy` HTTP request header is also non-standard and prone to error during configuration.
154+
|No
155+
156+
|`host`
157+
|Yes
158+
|When the `host` HTTP request header is set using the `IngressController` CR, HAProxy can fail when looking up the correct route.
159+
|No
160+
161+
|`strict-transport-security`
162+
|No
163+
|The `strict-transport-security` HTTP response header is already handled using route annotations and does not need a separate implementation.
164+
|Yes: the `haproxy.router.openshift.io/hsts_header` route annotation
165+
166+
|`cookie` and `set-cookie`
167+
|No
168+
|The cookies that HAProxy sets are used for session tracking to map client connections to particular back-end servers. Allowing these headers to be set could interfere with HAProxy's session affinity and restrict HAProxy's ownership of a cookie.
169+
|Yes:
170+
171+
* the `haproxy.router.openshift.io/disable_cookie` route annotation
172+
* the `haproxy.router.openshift.io/cookie_name` route annotation
173+
174+
|===
175+
endif::microshift[]

‎modules/nw-ingress-creating-a-route-via-an-ingress.adoc

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
// Module included in the following assemblies:
22
//
33
// * networking/routes/route-configuration.adoc
4+
// * microshift_networking/microshift-configuring-routes.adoc
45

56
:_mod-docs-content-type: PROCEDURE
67
[id="nw-ingress-creating-a-route-via-an-ingress_{context}"]

0 commit comments

Comments
 (0)