OSDOCS-16863-4RE: CQA for MetalLB Ingress and Route

microshift_networking/microshift-configuring-routes.adoc

@@ -6,7 +6,10 @@ include::_attributes/attributes-microshift.adoc[]
 
 toc::[]
 
-You can configure routes for services to have {microshift-short} node access.
+[role="_abstract"]
+To enable {microshift-short} node access for services, configure the cluster routes. By using this configuration, you can expose specific applications directly through the network interface of the node.
+
+Secure routes provide the ability to use several types of TLS termination to serve certificates to the client. See the _Additional resources_ section for links to the {OCP} documentation that describe how to create re-encrypt, edge, and passthrough routes with custom certificates.
 
 //OCP module, edit with care; Creating an insecure/http route
 include::modules/microshift-nw-create-http-based-route.adoc[leveloffset=+1]
@@ -50,10 +53,8 @@ include::modules/nw-ingress-edge-route-default-certificate.adoc[leveloffset=+1]
 //OCP module, edit with care
 include::modules/nw-ingress-reencrypt-route-custom-cert.adoc[leveloffset=+1]
 
-[id="microshift-secured-routes_{context}"]
-== Secured routes
-
-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.
+[role="_additional-resources"]
+.Additional resources
 
 * 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]
 

modules/microshift-nw-create-http-based-route.adoc

@@ -6,7 +6,10 @@
 [id="microshift-nw-creating-a-route_{context}"]
 = Creating an HTTP-based route
 
-A route allows you to host your application at a public URL. It can either be secure or unsecured, depending on the network security configuration of your application. An HTTP-based route is an unsecured route that uses the basic HTTP routing protocol and exposes a service on an unsecured application port.
+[role="_abstract"]
+To host your application at a public URL by using the basic HTTP routing protocol, create an HTTP-based route. This configuration exposes a service on an unsecured application port, allowing external access without TLS encryption.
+
+A route can either be secure or unsecured, depending on the network security configuration of your application.
 
 The following procedure describes how to create a simple HTTP-based route to a web application, using the `hello-microshift` application as an example.
 
@@ -38,11 +41,11 @@ $ oc expose svc/hello-microshift --hostname=microshift.com $namespace
 +
 [source,terminal]
 ----
-$ oc get routes -o yaml <name of resource> -n $namespace <1>
+$ oc get routes -o yaml <name of resource> -n $namespace
 ----
-<1> In this example, the route is named `hello-microshift` and the namespace is named `hello-microshift`.
-
-.Sample YAML definition of the created unsecured route:
+* `namespace`: Specifies the route that is named `hello-microshift` and the namespace is named `hello-microshift`.
++
+.Sample YAML definition for the created unsecured route
 [source,yaml]
 ----
 apiVersion: route.openshift.io/v1
@@ -51,17 +54,20 @@ metadata:
   name: hello-microshift
   namespace: hello-microshift
 spec:
-  host: microshift.com <1>
+  host: microshift.com
   port:
-    targetPort: 8080 <2>
+    targetPort: 8080
   to:
     kind: Service
     name: hello-microshift
 ----
-<1> Example hostname.
-<2> `targetPort` is required for the router to map the endpoint port in the service.
++
+where:
++
+`spec.host`:: Specifies the hostname.
+`port.targetPort`:: Specifies the target port for the router to map the endpoint port in the service.
 +
 [NOTE]
 ====
-{microshift-short} does not a use an API that creates a default ingress domain, but instead provides a wildcard for automatically generated domains. Each route can also define a separate hostname.
+{microshift-short} does not use an API that creates a default ingress domain, but instead provides a wildcard for automatically generated domains. Each route can also define a separate hostname.
 ====

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

@@ -6,7 +6,8 @@
 [id="microshift-nw-enforcing-hsts-per-domain_{context}"]
 = Enforcing HTTP Strict Transport Security per-domain
 
-You can configure a route with a compliant HSTS policy annotation. To handle an upgraded node with noncompliant HSTS routes, you can update the manifests at the source and apply the updates.
+[role="_abstract"]
+To enforce secure communication per-domain, configure routes with a compliant HSTS policy annotation. For upgraded nodes with non-compliant routes, ensure consistent enforcement by updating the source manifests to apply the new security policies.
 
 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.
 
@@ -16,28 +17,30 @@ HSTS cannot be applied to insecure, or non-TLS, routes.
 ====
 
 .Prerequisites
+
 * You have root access to the node.
 * You installed the {oc-first}.
 
 .Procedure
 
-* Apply HSTS to all routes in the node by running the following `oc annotate command`:
+* Apply HSTS to all routes in the node by running the following command:
 +
 [source,terminal]
 ----
 $ oc annotate route --all --all-namespaces --overwrite=true "haproxy.router.openshift.io/hsts_header"="max-age=31536000;preload;includeSubDomains"
 ----
-+
-* Apply HSTS to all routes in a particular namespace by running the following `oc annotate command`:
+
+* Apply HSTS to all routes in a particular namespace by running the following command:
 +
 [source,terminal]
 [subs="+quotes"]
 ----
-$ oc annotate route --all -n __<my_namespace>__ --overwrite=true "haproxy.router.openshift.io/hsts_header"="max-age=31536000;preload;includeSubDomains" <1>
+$ oc annotate route --all -n __<my_namespace>__ --overwrite=true "haproxy.router.openshift.io/hsts_header"="max-age=31536000;preload;includeSubDomains"
 ----
-<1> Replace `_<my_namespace>_` with the namespace you want to use.
+* `<my_namespace>`: Specify the namespace that you want to use.
 
 .Verification
+
 * Review the HSTS annotations on all routes by running the following command:
 +
 [source,terminal]

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

@@ -11,7 +11,10 @@
 [id="nw-annotating-a-route-with-a-cookie-name_{context}"]
 = Annotating a route with a cookie
 
-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.
+[role="_abstract"]
+To enable applications to manage session persistence and load distribution, annotate the route with a custom cookie name. Overwriting the default cookie allows the backend application to identify and delete the specific cookie, forcing endpoint re-selection when necessary.
+
+When a server is overloaded, the server tries to remove the requests from the client and redistribute the requests to other endpoints.
 
 .Procedure
 
@@ -22,12 +25,10 @@ You can set a cookie name to overwrite the default, auto-generated one for the r
 $ oc annotate route <route_name> router.openshift.io/cookie_name="<cookie_name>"
 ----
 +
---
 where:
-
++
 `<route_name>`:: Specifies the name of the route.
 `<cookie_name>`:: Specifies the name for the cookie.
---
 +
 For example, to annotate the route `my_route` with the cookie name `my_cookie`:
 +
@@ -43,11 +44,9 @@ $ oc annotate route my_route router.openshift.io/cookie_name="my_cookie"
 $ ROUTE_NAME=$(oc get route <route_name> -o jsonpath='{.spec.host}')
 ----
 +
---
 where:
-
++
 `<route_name>`:: Specifies the name of the route.
---
 
 . Save the cookie, and then access the route:
 +

modules/nw-disabling-hsts.adoc

@@ -6,7 +6,8 @@
 [id="nw-disabling-hsts_{context}"]
 = Disabling HTTP Strict Transport Security per-route
 
-To disable HTTP strict transport security (HSTS) per-route, you can set the `max-age` value in the route annotation to `0`.
+[role="_abstract"]
+To allow unencrypted connections or troubleshoot access issues, disable HTTP Strict Transport Security (HSTS) for a specific route. Setting the `max-age` route annotation to `0` instructs browsers to stop enforcing HTTPS requirements on the route host.
 
 .Prerequisites
 ifndef::microshift[]
@@ -19,7 +20,7 @@ endif::microshift[]
 
 .Procedure
 
-* To disable HSTS, set the `max-age` value in the route annotation to `0`, by entering the following command:
+* To disable HSTS, enter the following to set the `max-age` value in the route annotation to `0`:
 +
 [source,terminal]
 ----

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

@@ -6,7 +6,8 @@
 [id="nw-enabling-hsts-per-route_{context}"]
 = Enabling HTTP Strict Transport Security per-route
 
-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.
+[role="_abstract"]
+To enforce secure HTTPS connections for specific applications, enable HTTP Strict Transport Security (HSTS) on a per-route basis. Applying the `haproxy.router.openshift.io/hsts_header` annotation to edge and re-encrypt routes ensures that browsers reject unencrypted traffic.
 
 .Prerequisites
 ifndef::microshift[]
@@ -21,7 +22,7 @@ endif::microshift[]
 
 * To enable HSTS on a route, add the `haproxy.router.openshift.io/hsts_header` value to the edge-terminated or re-encrypt route. You can use the `oc annotate` tool to do this by running the following command. To properly run the command, ensure that the semicolon (`;`) in the `haproxy.router.openshift.io/hsts_header` route annotation is also surrounded by double quotation marks (`""`).
 +
-.Example `annotate` command that sets the maximum age to `31536000` ms (approximetly 8.5 hours)
+.Example `annotate` command that sets the maximum age to `31536000` ms (approximately 8.5 hours)
 [source,terminal]
 ----
 $ oc annotate route <route_name> -n <namespace> --overwrite=true "haproxy.router.openshift.io/hsts_header=max-age=31536000;\
@@ -35,7 +36,7 @@ apiVersion: route.openshift.io/v1
 kind: Route
 metadata:
   annotations:
-    haproxy.router.openshift.io/hsts_header: max-age=31536000;includeSubDomains;preload <1> <2> <3>
+    haproxy.router.openshift.io/hsts_header: max-age=31536000;includeSubDomains;preload
 # ...
 spec:
   host: def.abc.com
@@ -45,7 +46,9 @@ spec:
   wildcardPolicy: "Subdomain"
 # ...
 ----
-<1> Required. `max-age` measures the length of time, in seconds, that the HSTS policy is in effect. If set to `0`, it negates the policy.
-<2> Optional. When included, `includeSubDomains` tells the client
-that all subdomains of the host must have the same HSTS policy as the host.
-<3> Optional. When `max-age` is greater than 0, you can add `preload` in  `haproxy.router.openshift.io/hsts_header` to allow external services to include this site in their HSTS preload lists. For example, sites such as Google can construct a list of sites that have `preload` set. Browsers can then use these lists to determine which sites they can communicate with over HTTPS, even before they have interacted with the site. Without `preload` set, browsers must have interacted with the site over HTTPS, at least once, to get the header.
++
+where:
++
+`max-age`:: Specifies the measurement of the length of time, in seconds, for the HSTS policy. If set to `0`, it negates the policy.
+`includeSubDomains`:: Specifies that all subdomains of the host must have the same HSTS policy as the host. Optional parameter.
+`preload`:: Specifies that the site is included in the HSTS preload list when `max-age` is greater than `0`. For example, sites such as Google can construct a list of sites that have `preload` set. Browsers can then use these lists to determine which sites they can communicate with over HTTPS, even before they have interacted with the site. Without `preload` set, browsers must have interacted with the site over HTTPS, at least once, to get the header. Optional parameter.

modules/nw-enabling-hsts.adoc

@@ -7,7 +7,8 @@
 [id="nw-enabling-hsts_{context}"]
 = HTTP Strict Transport Security
 
-HTTP Strict Transport Security (HSTS) policy is a security enhancement, which signals to the browser client that only HTTPS traffic is allowed on the route host. HSTS also optimizes web traffic by signaling HTTPS transport is required, without using HTTP redirects. HSTS is useful for speeding up interactions with websites.
+[role="_abstract"]
+To enhance security and optimize website performance, use the HTTP Strict Transport Security (HSTS) policy. This mechanism signals browsers to use only HTTPS traffic on the route host, eliminating the need for HTTP redirects and speeding up user interactions.
 
 When HSTS policy is enforced, HSTS adds a Strict Transport Security header to HTTP and HTTPS responses from the site. You can use the `insecureEdgeTerminationPolicy` value in a route to redirect HTTP to HTTPS. When HSTS is enforced, the client changes all requests from the HTTP URL to HTTPS before the request is sent, eliminating the need for a redirect.
 

modules/nw-http-header-configuration.adoc

@@ -7,12 +7,16 @@
 [id="nw-http-header-configuration_{context}"]
 = HTTP header configuration
 
+[role="_abstract"]
 ifndef::microshift[]
-{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.
-endif::microshift[]
+To customize request and response headers for your applications, configure the Ingress Controller or apply specific route annotations. Understanding the interaction between these configuration methods ensures you effectively manage global and route-specific header policies.
 
+You can also set certain headers by using route annotations. The various ways of configuring headers can present challenges when working together.
+endif::microshift[]
 ifdef::microshift[]
-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.
+To customize request and response headers, modify individual route configurations or apply route annotations. Understanding the interaction between these methods ensures you effectively manage header policies and resolve potential configuration conflicts.
+
+The various ways of configuring headers can present challenges when working together.
 endif::microshift[]
 
 ifndef::microshift[]
@@ -30,8 +34,7 @@ You can only set or delete headers within a `Route` CR. You cannot append header
 endif::microshift[]
 
 ifndef::microshift[]
-[id="nw-http-header-configuration-order_{context}"]
-== Order of precedence
+Order of precedence::
 
 When the same HTTP header is modified both in the Ingress Controller and in a route, HAProxy prioritizes the actions in certain ways depending on whether it is a request or response header.
 
@@ -104,8 +107,7 @@ ifdef::microshift[]
 Any actions defined in a route override values set using route annotations.
 endif::microshift[]
 
-[id="nw-http-header-configuration-special-cases_{context}"]
-== Special case headers
+Special case headers::
 
 The following headers are either prevented entirely from being set or deleted, or allowed under specific circumstances:
 

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

@@ -7,7 +7,8 @@
 [id="nw-ingress-creating-a-route-via-an-ingress_{context}"]
 = Creating a route through an Ingress object
 
-Some ecosystem components have an integration with Ingress resources but not with route resources. To cover this case, {product-title} automatically creates managed route objects when an Ingress object is created. These route objects are deleted when the corresponding Ingress objects are deleted.
+[role="_abstract"]
+To integrate ecosystem components that require Ingress resources, configure an Ingress object. {product-title} automatically manages the lifecycle of the corresponding route objects, creating and deleting them to ensure seamless connectivity.
 
 .Procedure
 
@@ -21,11 +22,11 @@ kind: Ingress
 metadata:
   name: frontend
   annotations:
-    route.openshift.io/termination: "reencrypt" <1>
-    route.openshift.io/destination-ca-certificate-secret: secret-ca-cert <3>
+    route.openshift.io/termination: "reencrypt"
+    route.openshift.io/destination-ca-certificate-secret: secret-ca-cert
 spec:
   rules:
-  - host: www.example.com <2>
+  - host: www.example.com
     http:
       paths:
       - backend:
@@ -41,9 +42,13 @@ spec:
     secretName: example-com-tls-certificate
 ----
 +
-<1> The `route.openshift.io/termination` annotation can be used to configure the `spec.tls.termination` field of the `Route` as `Ingress` has  no field for this. The accepted values are `edge`, `passthrough` and `reencrypt`. All other values are silently ignored. When  the annotation value is unset, `edge` is the default route. The TLS certificate details must be defined in the template file to implement the default edge route.
-<2> When working with an `Ingress` object, you must specify an explicit hostname, unlike when working with routes. You can use the `<host_name>.<cluster_ingress_domain>` syntax, for example `apps.openshiftdemos.com`, to take advantage of the `*.<cluster_ingress_domain>` wildcard DNS record and serving certificate for the cluster. Otherwise, you must ensure that there is a DNS record for the chosen hostname.
+where:
++
+`route.openshift.io/termination`:: Specifies the `route.openshift.io/termination` annotation. You can configure the `spec.tls.termination` parameter of the `Route` because `Ingress` does not have this parameter. The accepted values are `edge`, `passthrough`, and `reencrypt`. All other values are silently ignored. When  the annotation value is unset, `edge` is the default route. The TLS certificate details must be defined in the template file to implement the default edge route.
+`rules.host`:: Specifies an explicit hostname for the `Ingress` object. Mandatory parameter. You can use the `<host_name>.<cluster_ingress_domain>` syntax, for example `apps.openshiftdemos.com`, to take advantage of the `*.<cluster_ingress_domain>` wildcard DNS record and serving certificate for the cluster. Otherwise, you must ensure that there is a DNS record for the chosen hostname.
+`destination-ca-certificate-secret`:: Specifies the `route.openshift.io/destination-ca-certificate-secret` annotation. The annotation can be used on an Ingress object to define a route with a custom destination certificate (CA). The annotation references a kubernetes secret, `secret-ca-cert` that will be inserted into the generated route.
 
++
 .. If you specify the `passthrough` value in the `route.openshift.io/termination` annotation, set `path` to `''` and `pathType` to `ImplementationSpecific` in the spec:
 +
 [source,yaml]
@@ -67,11 +72,8 @@ spec:
 $ oc apply -f ingress.yaml
 ----
 +
-<3> The `route.openshift.io/destination-ca-certificate-secret` can be used on an Ingress object to define a route with a custom destination certificate (CA). The annotation references a kubernetes secret, `secret-ca-cert` that will be inserted into the generated route.
-
 .. To specify a route object with a destination CA from an ingress object, you must create a `kubernetes.io/tls` or `Opaque` type secret with a certificate in PEM-encoded format in the `data.tls.crt` specifier of the secret.
 
-+
 . List your routes:
 +
 [source,terminal]
@@ -87,9 +89,7 @@ NAME             HOST/PORT         PATH    SERVICES    PORT    TERMINATION
 frontend-gnztq   www.example.com           frontend    443     reencrypt/Redirect   None
 ----
 +
-If you inspect this route, it looks this:
-+
-.YAML Definition of an autogenerated route
+.YAML definition example of an autogenerated route
 [source,yaml]
 ----
 apiVersion: route.openshift.io/v1