Merge pull request #110365 from openshift/revert-105199-OSDOCS-16863-5-18

Revert "[enterprise-4.18] OSDOCS-16863-5: CQA for MetalLB Ingress and Route"

Author: JoeAldinger

modules/challenges-of-managing-symmetric-routing-with-metallb.adoc

@@ -6,8 +6,7 @@
 [id="nw-ingress-creating-a-passthrough-route_{context}"]
 = Creating a passthrough route
 
-[role="_abstract"]
-To send encrypted traffic directly to the destination without decryption at the router, configure a route with passthrough termination by running the `oc create route` command. This configuration requires no key or certificate on the route, as the destination pod handles TLS termination.
+You can configure a secure route using passthrough termination by using the `oc create route` command. With passthrough termination, encrypted traffic is sent straight to the destination without the router providing TLS termination. Therefore no key or certificate is required on the route.
 
 .Prerequisites
 
@@ -30,23 +29,21 @@ If you examine the resulting `Route` resource, it should look similar to the fol
 apiVersion: route.openshift.io/v1
 kind: Route
 metadata:
-  name: route-passthrough-secured
+  name: route-passthrough-secured <1>
 spec:
   host: www.example.com
   port:
     targetPort: 8080
   tls:
-    termination: passthrough
-    insecureEdgeTerminationPolicy: None
+    termination: passthrough <2>
+    insecureEdgeTerminationPolicy: None <3>
   to:
     kind: Service
     name: frontend
 ----
+<1> The name of the object, which is limited to 63 characters.
+<2> The `*termination*` field is set to `passthrough`. This is the only required `tls` field.
+<3> Optional `insecureEdgeTerminationPolicy`. The only valid values are `None`, `Redirect`, or empty for disabled.
 +
-where:
-+
-`metadata.name`:: Specifies the name of the object, which is limited to 63 characters.
-`tls.termination`:: Specifies the `termination` field is set to `passthrough`. This is the only required `tls` field.
-`tls.insecureEdgeTerminationPolicy`:: Specifies the type of edge termination policy. Optional parameter. The only valid values are `None`, `Redirect`, or empty for disabled.
-+
-The destination pod is responsible for serving certificates for the traffic at the endpoint. This is currently the only method that can support requiring client certificates, also known as two-way authentication.
+The destination pod is responsible for serving certificates for the
+traffic at the endpoint. This is currently the only method that can support requiring client certificates, also known as two-way authentication.

modules/nw-ingress-creating-a-passthrough-route.adoc

@@ -6,8 +6,8 @@
 [id="nw-ingress-creating-a-reencrypt-route-with-a-custom-certificate_{context}"]
 = Creating a re-encrypt route with a custom certificate
 
-[role="_abstract"]
-To secure traffic by using a custom certificate, configure a route with re-encrypt TLS termination by running the `oc create route` command. This configuration enables the Ingress Controller to decrypt traffic, and then re-encrypt traffic before forwarding the traffic to the destination pod.
+You can configure a secure route using reencrypt TLS termination with a custom
+certificate by using the `oc create route` command.
 
 .Prerequisites
 
@@ -52,7 +52,8 @@ certificate:
 $ oc create route reencrypt --service=frontend --cert=tls.crt --key=tls.key --dest-ca-cert=destca.crt --ca-cert=ca.crt --hostname=www.example.com
 ----
 +
-If you examine the resulting `Route` resource, the resource should have a configuration similar to the following example:
+If you examine the resulting `Route` resource, it should look similar to the
+following:
 +
 .YAML Definition of the Secure Route
 [source,yaml]
@@ -84,7 +85,6 @@ spec:
       -----BEGIN CERTIFICATE-----
       [...]
       -----END CERTIFICATE-----
-# ...
 ----
 +
 See `oc create route reencrypt --help` for more options.

modules/nw-ingress-creating-a-reencrypt-route-with-a-custom-certificate.adoc

@@ -6,10 +6,11 @@
 [id="nw-ingress-creating-an-edge-route-with-a-custom-certificate_{context}"]
 = Creating an edge route with a custom certificate
 
-[role="_abstract"]
-To secure traffic by using a custom certificate, configure a route with edge TLS termination by running the `oc create route` command. This configuration terminates encryption at the Ingress Controller before forwarding traffic to the destination pod.
-
-The route specifies the TLS certificate and key that the Ingress Controller uses for the route.
+You can configure a secure route using edge TLS termination with a custom
+certificate by using the `oc create route` command. With an edge route, the
+Ingress Controller terminates TLS encryption before forwarding traffic to the
+destination pod. The route specifies the TLS certificate and key that the
+Ingress Controller uses for the route.
 
 .Prerequisites
 
@@ -19,6 +20,8 @@ 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 service that you want to expose.
+
 [NOTE]
 ====
 Password protected key files are not supported. To remove a passphrase from a
@@ -47,7 +50,8 @@ for `frontend`. Substitute the appropriate hostname for `www.example.com`.
 $ oc create route edge --service=frontend --cert=tls.crt --key=tls.key --ca-cert=ca.crt --hostname=www.example.com
 ----
 +
-If you examine the resulting `Route` resource, the resource should have a configuration similar to the following example:
+If you examine the resulting `Route` resource, it should look similar to the
+following:
 +
 .YAML Definition of the Secure Route
 [source,yaml]
@@ -75,7 +79,6 @@ spec:
       -----BEGIN CERTIFICATE-----
       [...]
       -----END CERTIFICATE-----
-# ...
 ----
 +
 See `oc create route edge --help` for more options.

modules/nw-ingress-creating-an-edge-route-with-a-custom-certificate.adoc

@@ -6,16 +6,14 @@
 [id="nw-metallb-community-cr_{context}"]
 = About the community custom resource
 
-[role="_abstract"]
-To simplify BGP configuration, define named aliases for community values by using the community custom resource. You can reference these aliases when advertising `ipAddressPools` with the `BGPAdvertisement` resource.
-
-The fields for the `community` custom resource are described in the following table.
+The `community` custom resource is a collection of aliases for communities. Users can define named aliases to be used when advertising `ipAddressPools` using the `BGPAdvertisement`. The fields for the `community` custom resource are described in the following table.
 
 [NOTE]
 ====
 The `community` CRD applies only to BGPAdvertisement.
 ====
 
+
 .MetalLB community custom resource
 [cols="1,1,3a", options="header"]
 |===

modules/nw-metallb-community-cr.adoc

@@ -6,20 +6,21 @@
 [id="nw-metallb-configure-BGP-advertisement-community-alias_{context}"]
 = Configuring MetalLB with a BGP advertisement and community alias
 
-[role="_abstract"]
-To advertise an `IPAddressPool` by using the BGP protocol, configure MetalLB with a community alias. This configuration sets the alias to the numeric value of the `NO_ADVERTISE` community.
+Configure MetalLB as follows so that the `IPAddressPool` is advertised with the BGP protocol and the community alias set to the numeric value of the NO_ADVERTISE community.
 
 In the following example, the peer BGP router `doc-example-peer-community` receives one `203.0.113.200/32` route and one `fc00:f853:ccd:e799::1/128` route for each load-balancer IP address that MetalLB assigns to a service. A community alias is configured with the `NO_ADVERTISE` community.
 
 .Prerequisites
 
-* Install the {oc-first}
+* Install the OpenShift CLI (`oc`).
+
 * Log in as a user with `cluster-admin` privileges.
 
+
 .Procedure
 
 . Create an IP address pool.
-+
+
 .. Create a file, such as `ipaddresspool.yaml`, with content like the following example:
 +
 [source,yaml]
@@ -34,7 +35,7 @@ spec:
     - 203.0.113.200/30
     - fc00:f853:ccd:e799::/124
 ----
-+
+
 .. Apply the configuration for the IP address pool:
 +
 [source,terminal]
@@ -58,7 +59,7 @@ spec:
 ----
 
 . Create a BGP peer named `doc-example-bgp-peer`.
-+
+
 .. Create a file, such as `bgppeer.yaml`, with content like the following example:
 +
 [source,yaml]
@@ -74,7 +75,7 @@ spec:
   myASN: 64500
   routerID: 10.10.10.10
 ----
-+
+
 .. Apply the configuration for the BGP peer:
 +
 [source,terminal]
@@ -83,7 +84,7 @@ $ oc apply -f bgppeer.yaml
 ----
 
 . Create a BGP advertisement with the community alias.
-+
+
 .. Create a file, such as `bgpadvertisement.yaml`, with content like the following example:
 +
 [source,yaml]
@@ -104,10 +105,8 @@ spec:
     - doc-example-peer
 ----
 +
-where:
-+
-`NO_ADVERTISE`: Specifies the `CommunityAlias.name` here and not the community custom resource (CR) name.
-+
+<1> Specify the `CommunityAlias.name` here and not the community custom resource (CR) name.
+
 .. Apply the configuration:
 +
 [source,terminal]