diff --git a/microshift_networking/microshift-configuring-routes.adoc b/microshift_networking/microshift-configuring-routes.adoc index c9a94b024acc..4002b0dbb9cc 100644 --- a/microshift_networking/microshift-configuring-routes.adoc +++ b/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] diff --git a/modules/microshift-nw-create-http-based-route.adoc b/modules/microshift-nw-create-http-based-route.adoc index 784bc26852bd..171d5c2b8a54 100644 --- a/modules/microshift-nw-create-http-based-route.adoc +++ b/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 -n $namespace <1> +$ oc get routes -o yaml -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. ==== diff --git a/modules/microshift-nw-enforcing-hsts-per-domain.adoc b/modules/microshift-nw-enforcing-hsts-per-domain.adoc index 0e7a32bf942b..2116e84ab75f 100644 --- a/modules/microshift-nw-enforcing-hsts-per-domain.adoc +++ b/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 ____ --overwrite=true "haproxy.router.openshift.io/hsts_header"="max-age=31536000;preload;includeSubDomains" <1> +$ oc annotate route --all -n ____ --overwrite=true "haproxy.router.openshift.io/hsts_header"="max-age=31536000;preload;includeSubDomains" ---- -<1> Replace `__` with the namespace you want to use. +* ``: Specify the namespace that you want to use. .Verification + * Review the HSTS annotations on all routes by running the following command: + [source,terminal] diff --git a/modules/nw-annotating-a-route-with-a-cookie-name.adoc b/modules/nw-annotating-a-route-with-a-cookie-name.adoc index a4666281a4f5..01066e4567c6 100644 --- a/modules/nw-annotating-a-route-with-a-cookie-name.adoc +++ b/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 router.openshift.io/cookie_name="" ---- + --- where: - ++ ``:: Specifies the name of the route. ``:: 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 -o jsonpath='{.spec.host}') ---- + --- where: - ++ ``:: Specifies the name of the route. --- . Save the cookie, and then access the route: + diff --git a/modules/nw-disabling-hsts.adoc b/modules/nw-disabling-hsts.adoc index d659a5b68976..525e80864c66 100644 --- a/modules/nw-disabling-hsts.adoc +++ b/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] ---- @@ -32,7 +33,10 @@ You can alternatively apply the following YAML to create the config map: .Example of disabling HSTS per-route [source,yaml] + ---- +kind: Route +apiVersion: route.openshift.io/v1 metadata: annotations: haproxy.router.openshift.io/hsts_header: max-age=0 diff --git a/modules/nw-enabling-hsts-per-route.adoc b/modules/nw-enabling-hsts-per-route.adoc index d84ff7342924..a814e2dee826 100644 --- a/modules/nw-enabling-hsts-per-route.adoc +++ b/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 -n --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. \ No newline at end of file diff --git a/modules/nw-enabling-hsts.adoc b/modules/nw-enabling-hsts.adoc index 4a9fa66846b7..43d3217abc97 100644 --- a/modules/nw-enabling-hsts.adoc +++ b/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. diff --git a/modules/nw-http-header-configuration.adoc b/modules/nw-http-header-configuration.adoc index ee56eb00a443..a8a2dc385bc7 100644 --- a/modules/nw-http-header-configuration.adoc +++ b/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: diff --git a/modules/nw-ingress-creating-a-route-via-an-ingress.adoc b/modules/nw-ingress-creating-a-route-via-an-ingress.adoc index a70a4926f7d8..bebdb83b8e6c 100644 --- a/modules/nw-ingress-creating-a-route-via-an-ingress.adoc +++ b/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: @@ -39,15 +40,23 @@ spec: - hosts: - www.example.com 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 `.` syntax, for example `apps.openshiftdemos.com`, to take advantage of the `*.` 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 `.` syntax, for example `apps.openshiftdemos.com`, to take advantage of the `*.` 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] ---- +apiVersion: networking.k8s.io/v1 +kind: Ingress +# ... spec: rules: - host: www.example.com @@ -60,6 +69,7 @@ spec: name: frontend port: number: 443 +# ... ---- + [source,terminal] @@ -67,11 +77,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 +94,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 diff --git a/modules/nw-ingress-edge-route-default-certificate.adoc b/modules/nw-ingress-edge-route-default-certificate.adoc index 9dd9c76b7fc9..ac5acac4559d 100644 --- a/modules/nw-ingress-edge-route-default-certificate.adoc +++ b/modules/nw-ingress-edge-route-default-certificate.adoc @@ -7,16 +7,17 @@ [id="nw-ingress-edge-route-default-certificate_{context}"] = Creating a route using the default certificate through an Ingress object -If you create an Ingress object without specifying any TLS configuration, {product-title} generates an insecure route. To create an Ingress object that generates a secure, edge-terminated route using the default ingress certificate, you can specify an empty TLS configuration as follows. +[role="_abstract"] +To generate a secure, edge-terminated route that uses the default ingress certificate, specify an empty TLS configuration in the Ingress object. This configuration overrides the default behavior, preventing the creation of an insecure route. .Prerequisites * You have a service that you want to expose. -* You have access to the OpenShift CLI (`oc`). +* You have access to the {oc-first}. .Procedure -. Create a YAML file for the Ingress object. In this example, the file is called `example-ingress.yaml`: +. Create a YAML file for the Ingress object. In the following example, the file is called `example-ingress.yaml`: + .YAML definition of an Ingress object [source,yaml] @@ -30,10 +31,12 @@ spec: rules: ... tls: - - {} <1> + - {} ---- + -<1> Use this exact syntax to specify TLS without specifying a custom certificate. +where: ++ +`spec.tls`:: Specifies the TLS configuration. Use the exact syntax shown to specify TLS without specifying a custom certificate. . Create the Ingress object by running the following command: + @@ -59,15 +62,18 @@ items: - apiVersion: route.openshift.io/v1 kind: Route metadata: - name: frontend-j9sdd <1> - ... + name: frontend-j9sdd +# ... spec: ... - tls: <2> + tls: insecureEdgeTerminationPolicy: Redirect - termination: edge <3> - ... + termination: edge +# ... ---- -<1> The name of the route includes the name of the Ingress object followed by a random suffix. -<2> In order to use the default certificate, the route should not specify `spec.certificate`. -<3> The route should specify the `edge` termination policy. ++ +where: ++ +`metadata.name`:: Specifies the name of the route, which includes the name of the Ingress object followed by a random suffix. +`spec.tls`:: To use the default certificate, the route should not specify `spec.certificate`. +`tls.termination`:: Specifies the termination policy for the route. The route should specify the `edge` termination policy. diff --git a/modules/nw-ingress-reencrypt-route-custom-cert.adoc b/modules/nw-ingress-reencrypt-route-custom-cert.adoc index 0c065a84d43c..b0bc4b2a18f6 100644 --- a/modules/nw-ingress-reencrypt-route-custom-cert.adoc +++ b/modules/nw-ingress-reencrypt-route-custom-cert.adoc @@ -7,13 +7,15 @@ [id="nw-ingress-re-encrypt-route-custom-cert_{context}"] = Creating a route using the destination CA certificate in the Ingress annotation -The `route.openshift.io/destination-ca-certificate-secret` annotation can be used on an Ingress object to define a route with a custom destination CA certificate. +[role="_abstract"] +To define a route with a custom destination CA certificate, apply the `route.openshift.io/destination-ca-certificate-secret` annotation to an Ingress object. This configuration ensures the Ingress Controller uses the specified secret to verify the identity of the destination service. .Prerequisites -* You may have a certificate/key pair in PEM-encoded files, where the certificate is valid for the route host. -* You may have a separate CA certificate in a PEM-encoded file that completes the certificate chain. -* You must have a separate destination CA certificate in a PEM-encoded file. -* You must have a service that you want to expose. + +* You have a certificate/key pair in PEM-encoded files, where the certificate is valid for the route host. +* You have a separate CA certificate in a PEM-encoded file that completes the certificate chain. +* You have a separate destination CA certificate in a PEM-encoded file. +* You have a service that you want to expose. .Procedure @@ -47,13 +49,15 @@ metadata: name: frontend annotations: route.openshift.io/termination: "reencrypt" - route.openshift.io/destination-ca-certificate-secret: secret-ca-cert <1> + route.openshift.io/destination-ca-certificate-secret: secret-ca-cert ... ---- -<1> The annotation references a kubernetes secret. - + -. The secret referenced in this annotation will be inserted into the generated route. +where: ++ +`destination-ca-certificate-secret`:: Specifies the `route.openshift.io/destination-ca-certificate-secret` annotation. The annotation references a Kubernetes secret. ++ +The Ingress Controller inserts a secret that is referenced in the annotation into the generated route. + .Example output [source,yaml] diff --git a/modules/nw-metallb-collecting-data.adoc b/modules/nw-metallb-collecting-data.adoc index 8a9f462e732b..ddd4977bac71 100644 --- a/modules/nw-metallb-collecting-data.adoc +++ b/modules/nw-metallb-collecting-data.adoc @@ -6,23 +6,22 @@ [id="nw-metallb-collecting-data_{context}"] = About collecting MetalLB data -You can use the `oc adm must-gather` CLI command to collect information about your cluster, your MetalLB configuration, and the MetalLB Operator. -The following features and objects are associated with MetalLB and the MetalLB Operator: +[role="_abstract"] +To collect diagnostic data for debugging or support analysis, execute the `oc adm must-gather` CLI command. This utility captures essential information regarding the cluster, the MetalLB configuration, and the MetalLB Operator state. -* The namespace and child objects that the MetalLB Operator is deployed in +The following list details features and objects related to MetalLB and the MetalLB Operator: +* The namespace and child objects where you deploy the MetalLB Operator * All MetalLB Operator custom resource definitions (CRDs) -The `oc adm must-gather` CLI command collects the following information from FRRouting (FRR) that Red Hat uses to implement BGP and BFD: +The command collects the following information from FRRouting (FRR), which Red{nbsp} Hat uses to implement BGP and BFD: * `/etc/frr/frr.conf` * `/etc/frr/frr.log` * `/etc/frr/daemons` configuration file * `/etc/frr/vtysh.conf` -The log and configuration files in the preceding list are collected from the `frr` container in each `speaker` pod. - -In addition to the log and configuration files, the `oc adm must-gather` CLI command collects the output from the following `vtysh` commands: +The command collects log and configuration files from the `frr` container that exists in each `speaker` pod. Additionally, the command collects the output from the following `vtysh` commands: * `show running-config` * `show bgp ipv4` @@ -30,4 +29,4 @@ In addition to the log and configuration files, the `oc adm must-gather` CLI com * `show bgp neighbor` * `show bfd peer` -No additional configuration is required when you run the `oc adm must-gather` CLI command. +No additional configuration is required when you run the command. diff --git a/modules/nw-metallb-levels.adoc b/modules/nw-metallb-levels.adoc index 55322b345966..1537b4ca2942 100644 --- a/modules/nw-metallb-levels.adoc +++ b/modules/nw-metallb-levels.adoc @@ -3,11 +3,13 @@ // * networking/metallb/metallb-troubleshoot-support.adoc :_mod-docs-content-type: REFERENCE - [id="frr-log-levels_{context}"] = FRRouting (FRR) log levels -The following table describes the FRR logging levels. +[role="_abstract"] +To control the verbosity of network logs for troubleshooting or monitoring, refer to the FRRouting (FRR) logging levels. + +The following values define the severity of recorded events, so that you can use them to filter output based on operational requirements: .Log levels [cols="30%,70%",options="header"] diff --git a/modules/nw-metallb-loglevel.adoc b/modules/nw-metallb-loglevel.adoc index 77e30b1850d9..05e2aa44c69e 100644 --- a/modules/nw-metallb-loglevel.adoc +++ b/modules/nw-metallb-loglevel.adoc @@ -7,15 +7,15 @@ [id="nw-metallb-setting-metalb-logging-levels_{context}"] = Setting the MetalLB logging levels -MetalLB uses FRRouting (FRR) in a container with the default setting of `info` generates a lot of logging. You can control the verbosity of the logs generated by setting the `logLevel` as illustrated in this example. +[role="_abstract"] +To manage log verbosity for the FRRouting (FRR) container, configure the `logLevel` specification. By adjusting this setting, you can reduce log volume from the default info level or increase detail for troubleshooting MetalLB configuration issues. -Gain a deeper insight into MetalLB by setting the `logLevel` to `debug` as follows: +Gain a deeper insight into MetalLB by setting the `logLevel` to `debug`. .Prerequisites * You have access to the cluster as a user with the `cluster-admin` role. - -* You have installed the OpenShift CLI (`oc`). +* You have installed the {oc-first}. .Procedure @@ -34,7 +34,7 @@ spec: node-role.kubernetes.io/worker: "" ---- -. Apply the configuration: +. Apply the configuration by entering the following command: + [source,terminal] ---- @@ -43,7 +43,7 @@ $ oc replace -f setdebugloglevel.yaml + [NOTE] ==== -Use `oc replace` as the understanding is the `metallb` CR is already created and here you are changing the log level. +Use the `oc replace` command because the `metallb` CR was already created and you need to change only the log level. ==== . Display the names of the `speaker` pods: diff --git a/modules/nw-metallb-metrics.adoc b/modules/nw-metallb-metrics.adoc index 9f01e7d21b2e..346350e474a2 100644 --- a/modules/nw-metallb-metrics.adoc +++ b/modules/nw-metallb-metrics.adoc @@ -6,7 +6,8 @@ [id="nw-metallb-metrics_{context}"] = MetalLB metrics for BGP and BFD -{product-title} captures the following Prometheus metrics for MetalLB that relate to BGP peers and BFD profiles. +[role="_abstract"] +To monitor network connectivity and diagnose routing states, refer to the Prometheus metrics for MetalLB. These metrics provide visibility into the status of BGP peers and BFD profiles so that you can ensure stable external communication. .MetalLB BFD metrics [cols="30%,70%",options="header"] diff --git a/modules/nw-metallb-troubleshoot-bfd.adoc b/modules/nw-metallb-troubleshoot-bfd.adoc index 81fda0fadb2d..b0058fe43450 100644 --- a/modules/nw-metallb-troubleshoot-bfd.adoc +++ b/modules/nw-metallb-troubleshoot-bfd.adoc @@ -6,15 +6,15 @@ [id="nw-metallb-troubleshoot-bfd_{context}"] = Troubleshooting BFD issues -The Bidirectional Forwarding Detection (BFD) implementation that Red Hat supports uses FRRouting (FRR) in a container in the `speaker` pods. -The BFD implementation relies on BFD peers also being configured as BGP peers with an established BGP session. -As a cluster administrator, if you need to troubleshoot BFD configuration issues, you need to run commands in the FRR container. +[role="_abstract"] +To diagnose and resolve Bidirectional Forwarding Detection (BFD) issues, execute commands directly within the FRRouting (FRR) container. By accessing the container, you can verify that BFD peers are correctly configured with established BGP sessions. + +The BFD implementation that Red{nbsp}Hat supports uses FRRouting (FRR) in a container that exists in a `speaker` pod. .Prerequisites * You have access to the cluster as a user with the `cluster-admin` role. - -* You have installed the OpenShift CLI (`oc`). +* You have installed the {oc-first}. .Procedure @@ -46,9 +46,10 @@ $ oc exec -n metallb-system speaker-66bth -c frr -- vtysh -c "show bfd peers bri Session count: 2 SessionId LocalAddress PeerAddress Status ========= ============ =========== ====== -3909139637 10.0.1.2 10.0.2.3 up <.> +3909139637 10.0.1.2 10.0.2.3 up ---- -<.> Confirm that the `PeerAddress` column includes each BFD peer. -If the output does not list a BFD peer IP address that you expected the output to include, troubleshoot BGP connectivity with the peer. -If the status field indicates `down`, check for connectivity on the links and equipment between the node and the peer. ++ +where: ++ +`up`:: Specifies that the `PeerAddress` column includes each BFD peer. If the output does not list a BFD peer IP address that you expected the output to include, troubleshoot BGP connectivity with the peer. If the status field indicates `down`, check for connectivity on the links and equipment between the node and the peer. You can determine the node name for the speaker pod with a command like `oc get pods -n metallb-system speaker-66bth -o jsonpath='{.spec.nodeName}'`. diff --git a/modules/nw-metallb-troubleshoot-bgp.adoc b/modules/nw-metallb-troubleshoot-bgp.adoc index 2ee11df2bc94..fbd4f626fb75 100644 --- a/modules/nw-metallb-troubleshoot-bgp.adoc +++ b/modules/nw-metallb-troubleshoot-bgp.adoc @@ -6,13 +6,13 @@ [id="nw-metallb-troubleshoot-bgp_{context}"] = Troubleshooting BGP issues -As a cluster administrator, if you need to troubleshoot BGP configuration issues, you need to run commands in the FRR container. +[role="_abstract"] +To diagnose and resolve BGP configuration issues, execute commands directly within the FRR container. By accessing the container, you can verify routing states and identify connectivity errors. .Prerequisites * You have access to the cluster as a user with the `cluster-admin` role. - -* You have installed the OpenShift CLI (`oc`). +* You have installed the {oc-first}. .Procedure @@ -52,20 +52,20 @@ no ip forwarding no ipv6 forwarding service integrated-vtysh-config ! -router bgp 64500 <1> +router bgp 64500 bgp router-id 10.0.1.2 no bgp ebgp-requires-policy no bgp default ipv4-unicast no bgp network import-check - neighbor 10.0.2.3 remote-as 64500 <2> - neighbor 10.0.2.3 bfd profile doc-example-bfd-profile-full <3> + neighbor 10.0.2.3 remote-as 64500 + neighbor 10.0.2.3 bfd profile doc-example-bfd-profile-full neighbor 10.0.2.3 timers 5 15 neighbor 10.0.2.4 remote-as 64500 neighbor 10.0.2.4 bfd profile doc-example-bfd-profile-full neighbor 10.0.2.4 timers 5 15 ! address-family ipv4 unicast - network 203.0.113.200/30 <4> + network 203.0.113.200/30 neighbor 10.0.2.3 activate neighbor 10.0.2.3 route-map 10.0.2.3-in in neighbor 10.0.2.4 activate @@ -102,10 +102,13 @@ bfd ! end ---- -<1> The `router bgp` section indicates the ASN for MetalLB. -<2> Confirm that a `neighbor remote-as ` line exists for each BGP peer custom resource that you added. -<3> If you configured BFD, confirm that the BFD profile is associated with the correct BGP peer and that the BFD profile appears in the command output. -<4> Confirm that the `network ` lines match the IP address ranges that you specified in address pool custom resources that you added. ++ +where: ++ +`router bgp 64500`:: Specifies the `router bgp` that indicates the ASN for MetalLB. +`neighbor 10.0.2.3 remote-as 64500`:: Specifies that a `neighbor remote-as ` line exists for each BGP peer custom resource that you added. +`bfd profile doc-example-bfd-profile-full`:: Specifies that the BFD profile is associated with the correct BGP peer and that the BFD profile shows in the command output. +`network 203.0.113.200/30`:: Specifies that the `network ` lines match the IP address ranges that you specified in address pool custom resources . Display the BGP summary by running the following command: + @@ -123,8 +126,8 @@ RIB entries 1, using 192 bytes of memory Peers 2, using 29 KiB of memory Neighbor V AS MsgRcvd MsgSent TblVer InQ OutQ Up/Down State/PfxRcd PfxSnt -10.0.2.3 4 64500 387 389 0 0 0 00:32:02 0 1 <1> -10.0.2.4 4 64500 0 0 0 0 0 never Active 0 <2> +10.0.2.3 4 64500 387 389 0 0 0 00:32:02 0 1 +10.0.2.4 4 64500 0 0 0 0 0 never Active 0 Total number of neighbors 2 @@ -140,9 +143,11 @@ Neighbor V AS MsgRcvd MsgSent TblVer InQ OutQ Up/Down Sta Total number of neighbors 2 ---- -<1> Confirm that the output includes a line for each BGP peer custom resource that you added. -<2> Output that shows `0` messages received and messages sent indicates a BGP peer that does not have a BGP session. -Check network connectivity and the BGP configuration of the BGP peer. ++ +where: ++ +`10.0.2.3`:: Specifies that the output includes a line for each BGP peer custom resource that you added. +`10.0.2.4`:: Specifies that the output shows `0` messages received and `0` messages sent, which indicates a BGP peer that does not have a BGP session. Check network connectivity and the BGP configuration of the BGP peer. . Display the BGP peers that received an address pool by running the following command: + @@ -159,10 +164,13 @@ Replace `203.0.113.200/30` with an IPv4 or IPv6 IP address range from an address BGP routing table entry for 203.0.113.200/30 Paths: (1 available, best #1, table default) Advertised to non peer-group peers: - 10.0.2.3 <1> + 10.0.2.3 Local 0.0.0.0 from 0.0.0.0 (10.0.1.2) Origin IGP, metric 0, weight 32768, valid, sourced, local, best (First path received) Last update: Mon Jan 10 19:49:07 2022 ---- -<1> Confirm that the output includes an IP address for a BGP peer. ++ +where: ++ +`10.0.2.3`:: Specifies that the output includes an IP address for a BGP peer. diff --git a/modules/nw-path-based-routes.adoc b/modules/nw-path-based-routes.adoc index f9938e846812..176ee57497f2 100644 --- a/modules/nw-path-based-routes.adoc +++ b/modules/nw-path-based-routes.adoc @@ -6,14 +6,15 @@ [id="nw-path-based-routes_{context}"] = Path-based routes -Path-based routes specify a path component that can be compared against a URL, which requires that the traffic for the route be HTTP based. Thus, multiple routes can be served using the same hostname, each with a different path. Routers should match routes based on the most specific path to the least. +[role="_abstract"] +To serve multiple applications by using a single hostname, configure path-based routes. This HTTP-based configuration directs traffic to specific services by comparing the URL path component, ensuring requests match the most specific route defined. The following table shows example routes and their accessibility: .Route availability [cols="3*", options="header"] |=== -|Route | When Compared to | Accessible +|Route | When compared to | Accessible .2+|_www.example.com/test_ |_www.example.com/test_|Yes |_www.example.com_|No .2+|_www.example.com/test_ and _www.example.com_ | _www.example.com/test_|Yes @@ -22,8 +23,7 @@ The following table shows example routes and their accessibility: |_www.example.com_|Yes |=== -.An unsecured route with a path - +.Example of an unsecured route with a path [source,yaml] ---- apiVersion: route.openshift.io/v1 @@ -37,7 +37,7 @@ spec: kind: Service name: service-name ---- -* Specifies the path that is the only added attribute for a path-based route. +* `spec.host`: Specifies the path attribute for a path-based route. [NOTE] ==== diff --git a/modules/nw-route-set-or-delete-http-headers.adoc b/modules/nw-route-set-or-delete-http-headers.adoc index 4322252709cf..acdd3784b11d 100644 --- a/modules/nw-route-set-or-delete-http-headers.adoc +++ b/modules/nw-route-set-or-delete-http-headers.adoc @@ -6,6 +6,7 @@ [id="nw-route-set-or-delete-http-headers_{context}"] = Setting or deleting HTTP request and response headers in a route +[role="_abstract"] You can set or delete certain HTTP request and response headers 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. @@ -13,11 +14,12 @@ For example, you might want to enable a web application to serve content in alte 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`. Directing application traffic to this location means that anyone using that specific route is accessing web content written in American English. .Prerequisites -* You have installed the OpenShift CLI (`oc`). +* You have installed the {oc-first}. * You are logged into an {product-title} cluster as a project administrator. * You have a web application that exposes a port and an HTTP or TLS endpoint listening for traffic on the port. .Procedure + . Create a route definition and save it in a file called `app-example-route.yaml`: + .YAML definition of the created route with HTTP header directives @@ -34,19 +36,23 @@ spec: kind: Service name: app-example httpHeaders: - actions: <1> - response: <2> - - name: Content-Location <3> + actions: + response: + - name: Content-Location action: - type: Set <4> + type: Set set: - value: /lang/en-us <5> + value: /lang/en-us +# ... ---- -<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 _HTTP header configuration_. -<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, the value is set to the relative location of the content. ++ +where: ++ +`actions`:: Specifies the list of actions you want to perform on the HTTP headers. +`response`:: Specifies the type of header you want to change. In this case, a response header. +`response.name`:: Specifies the name of the header you want to change. For a list of available headers you can set or delete, see _HTTP header configuration_. +`action.type`:: Specifies the type of action being taken on the header. This field can have the value `Set` or `Delete`. +`set.value`:: 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, 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: + @@ -54,5 +60,5 @@ spec: ---- $ 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_. diff --git a/modules/nw-throughput-troubleshoot.adoc b/modules/nw-throughput-troubleshoot.adoc index d3ee0a3a12d6..bddba3b75dfb 100644 --- a/modules/nw-throughput-troubleshoot.adoc +++ b/modules/nw-throughput-troubleshoot.adoc @@ -7,7 +7,8 @@ [id="nw-throughput-troubleshoot_{context}"] = Throughput issue troubleshooting methods -Sometimes applications deployed by using {product-title} can cause network throughput issues, such as unusually high latency between specific services. +[role="_abstract"] +To diagnose and resolve network throughput issues, such as unusually high latency between specific services, apply troubleshooting methods. Identifying connectivity bottlenecks helps ensure stable application performance within {product-title}. If pod logs do not reveal any cause of the problem, use the following methods to analyze performance issues: @@ -20,7 +21,9 @@ For example, link:https://access.redhat.com/solutions/4569211[run the `tcpdump` $ tcpdump -s 0 -i any -w /tmp/dump.pcap host && host <1> ---- + -<1> `podip` is the IP address for the pod. Run the `oc get pod -o wide` command to get the IP address of a pod. +where: ++ +`podip`:: Specifies the IP address for the pod. Run the `oc get pod -o wide` command to get the IP address of a pod. + The `tcpdump` command generates a file at `/tmp/dump.pcap` containing all traffic between these two pods. You can run the analyzer shortly before the issue is reproduced and stop the analyzer shortly after the issue is finished reproducing to minimize the size of the file. You can also link:https://access.redhat.com/solutions/5074041[run a packet analyzer between the nodes] with: + diff --git a/modules/nw-using-cookies-keep-route-statefulness.adoc b/modules/nw-using-cookies-keep-route-statefulness.adoc index 88b2dcda1a24..81ea87951b77 100644 --- a/modules/nw-using-cookies-keep-route-statefulness.adoc +++ b/modules/nw-using-cookies-keep-route-statefulness.adoc @@ -11,9 +11,10 @@ [id="nw-using-cookies-keep-route-statefulness_{context}"] = Using cookies to keep route statefulness -{product-title} provides sticky sessions, which enables stateful application traffic by ensuring all traffic hits the same endpoint. However, if the endpoint pod terminates, whether through restart, scaling, or a change in configuration, this statefulness can disappear. +[role="_abstract"] +To maintain stateful application traffic during pod restarts or scaling events, configure sticky sessions by using cookies. By using this method, you ensure that all incoming traffic reaches the same endpoint, preventing state loss even if the specific endpoint pod changes. -{product-title} can use cookies to configure session persistence. The ingress controller selects an endpoint to handle any user requests, and creates a cookie for the session. The cookie is passed back in the response to the request and the user sends the cookie back with the next request in the session. The cookie tells the ingress controller which endpoint is handling the session, ensuring that client requests use the cookie so that they are routed to the same pod. +{product-title} can use cookies to configure session persistence. The Ingress Controller selects an endpoint to handle any user requests, and creates a cookie for the session. The cookie is passed back in the response to the request and the user sends the cookie back with the next request in the session. The cookie tells the Ingress Controller which endpoint is handling the session, ensuring that client requests use the cookie so that they are routed to the same pod. [NOTE] ==== diff --git a/networking/ingress_load_balancing/metallb/metallb-troubleshoot-support.adoc b/networking/ingress_load_balancing/metallb/metallb-troubleshoot-support.adoc index 03947d2b9388..eac7babe66db 100644 --- a/networking/ingress_load_balancing/metallb/metallb-troubleshoot-support.adoc +++ b/networking/ingress_load_balancing/metallb/metallb-troubleshoot-support.adoc @@ -6,7 +6,8 @@ include::_attributes/common-attributes.adoc[] toc::[] -If you need to troubleshoot MetalLB configuration, see the following sections for commonly used commands. +[role="_abstract"] +To diagnose and resolve MetalLB configuration issues, refer to this list of commonly used commands. By using these commands, you can verify network connectivity and inspect service states to ensure efficient error recovery. // Set logging level include::modules/nw-metallb-loglevel.adoc[leveloffset=+1] @@ -26,7 +27,7 @@ include::modules/nw-metallb-metrics.adoc[leveloffset=+1] [role="_additional-resources"] .Additional resources -* See link:https://docs.redhat.com/en/documentation/monitoring_stack_for_red_hat_openshift/4.21/html/accessing_metrics/accessing-metrics-as-an-administrator#querying-metrics-for-all-projects-with-mon-dashboard_accessing-metrics-as-an-administrator[Querying metrics for all projects with the monitoring dashboard] for information about using the monitoring dashboard. +* link:https://docs.redhat.com/en/documentation/monitoring_stack_for_red_hat_openshift/4.21/html/accessing_metrics/accessing-metrics-as-an-administrator#querying-metrics-for-all-projects-with-mon-dashboard_accessing-metrics-as-an-administrator[Querying metrics for all projects with the monitoring dashboard] // Collecting data include::modules/nw-metallb-collecting-data.adoc[leveloffset=+1] diff --git a/networking/ingress_load_balancing/routes/creating-advanced-routes.adoc b/networking/ingress_load_balancing/routes/creating-advanced-routes.adoc index 714e6b649445..328cd7ef9280 100644 --- a/networking/ingress_load_balancing/routes/creating-advanced-routes.adoc +++ b/networking/ingress_load_balancing/routes/creating-advanced-routes.adoc @@ -7,8 +7,7 @@ include::_attributes/common-attributes.adoc[] toc::[] [role="_abstract"] -You can create secure routes with the ability to use several types of TLS termination to serve certificates to the client. The following sections describe how to create re-encrypt, edge, and passthrough routes with custom certificates. - +To secure application traffic and serve custom certificates to clients, configure routes by using edge, passthrough, or re-encrypt TLS termination. By using these methods, you can define granular encryption rules, ensuring that traffic is decrypted and re-encrypted according to your specific security requirements. //Creating an edge route with a custom certificate include::modules/nw-ingress-creating-an-edge-route-with-a-custom-certificate.adoc[leveloffset=+1] diff --git a/networking/ingress_load_balancing/routes/nw-configuring-routes.adoc b/networking/ingress_load_balancing/routes/nw-configuring-routes.adoc index e62237e20b89..38a21f5f9d98 100644 --- a/networking/ingress_load_balancing/routes/nw-configuring-routes.adoc +++ b/networking/ingress_load_balancing/routes/nw-configuring-routes.adoc @@ -7,7 +7,7 @@ include::_attributes/common-attributes.adoc[] toc::[] [role="_abstract"] -You can use annotations, headers, cookies, and more to customize your route configuration. +To customise route configuration for specific traffic behaviors, apply annotations, headers, and cookies. By using these mechanisms, you can define granular routing rules, extending standard capabilities to meet complex application requirements. //Configuring route timeouts include::modules/nw-configuring-route-timeouts.adoc[leveloffset=+1]