OSDOCS 16844 MetalLB ADV fixes

modules/nw-metallb-bgp-limitations.adoc

@@ -6,6 +6,9 @@
 [id="nw-metallb-bgp-limitations_{context}"]
 = Limitations for BGP mode
 
+[role="_abstract"]
+In {product-title}, MetalLB border gateway protocol (BGP) mode can reset active connections when a BGP session terminates and requires a single ASN and router ID for all BGP peers. Use a node selector when adding a BGP peer to limit which nodes run BGP sessions and reduce the impact of node faults.
+
 [id="nw-metallb-bgp-limitations-break-connections_{context}"]
 == Node failure can break all active connections
 

modules/nw-metallb-bgp.adoc

@@ -6,18 +6,16 @@
 [id="nw-metallb-bgp_{context}"]
 = MetalLB concepts for BGP mode
 
-In BGP mode, by default each `speaker` pod advertises the load balancer IP address for a service to each BGP peer. It is also possible to advertise the IPs coming from a given pool to a specific set of peers by adding an optional list of BGP peers.
-BGP peers are commonly network routers that are configured to use the BGP protocol.
-When a router receives traffic for the load balancer IP address, the router picks one of the nodes with a `speaker` pod that advertised the IP address.
-The router sends the traffic to that node.
-After traffic enters the node, the service proxy for the CNI network plugin distributes the traffic to all the pods for the service.
+[role="_abstract"]
+MetalLB in border gateway protocol (BGP) mode advertises load balancer IP addresses to BGP peers from each `speaker` pod. The router sends traffic to one of the nodes, so load is distributed across nodes and the router switches to another node when one becomes unavailable.
 
-The directly-connected router on the same layer 2 network segment as the cluster nodes can be configured as a BGP peer.
-If the directly-connected router is not configured as a BGP peer, you need to configure your network so that packets for load balancer IP addresses are routed between the BGP peers and the cluster nodes that run the `speaker` pods.
+It is also possible to advertise the IPs coming from a given pool to a specific set of peers by adding an optional list of BGP peers.
 
-Each time a router receives new traffic for the load balancer IP address, it creates a new connection to a node.
-Each router manufacturer has an implementation-specific algorithm for choosing which node to initiate the connection with.
-However, the algorithms commonly are designed to distribute traffic across the available nodes for the purpose of balancing the network load.
+BGP peers are commonly network routers that are configured to use the BGP protocol. When a router receives traffic for the load balancer IP address, the router picks one of the nodes with a `speaker` pod that advertised the IP address. The router sends the traffic to that node. After traffic enters the node, the service proxy for the CNI network plugin distributes the traffic to all the pods for the service.
+
+The directly-connected router on the same layer 2 network segment as the cluster nodes can be configured as a BGP peer. If the directly-connected router is not configured as a BGP peer, you need to configure your network so that packets for load balancer IP addresses are routed between the BGP peers and the cluster nodes that run the `speaker` pods.
+
+Each time a router receives new traffic for the load balancer IP address, it creates a new connection to a node. Each router manufacturer has an implementation-specific algorithm for choosing which node to initiate the connection with. However, the algorithms commonly are designed to distribute traffic across the available nodes for the purpose of balancing the network load.
 
 If a node becomes unavailable, the router initiates a new connection with another node that has a `speaker` pod that advertises the load balancer IP address.
 

modules/nw-metallb-extern-traffic-pol.adoc

@@ -6,8 +6,13 @@
 [id="nw-metallb-extern-traffic-pol_{context}"]
 = MetalLB and external traffic policy
 
+[role="_abstract"]
+External traffic policy for MetalLB LoadBalancer services determines how the service proxy distributes traffic to pods. Set the policy to `cluster` for uniform distribution or to `local` to preserve client IP addresses.
+
 With layer 2 mode, one node in your cluster receives all the traffic for the service IP address.
+
 With BGP mode, a router on the host network opens a connection to one of the nodes in the cluster for a new client connection.
+
 How your cluster handles the traffic after it enters the node is affected by the external traffic policy.
 
 `cluster`::

modules/nw-metallb-infra-considerations.adoc

@@ -6,9 +6,10 @@
 [id="nw-metallb-infra-considerations_{context}"]
 = Infrastructure considerations for MetalLB
 
-MetalLB is primarily useful for on-premise, bare metal installations because these installations do not include a native load-balancer capability.
-In addition to bare metal installations, installations of {product-title} on some infrastructures might not include a native load-balancer capability.
-For example, the following infrastructures can benefit from adding the MetalLB Operator:
+[role="_abstract"]
+You can use MetalLB for bare metal and on-premise installations that lack a native load balancer.
+
+In addition to bare-metal installations, installations of {product-title} on some infrastructures might not include a native load-balancer capability. For example, the following infrastructures can benefit from adding the MetalLB Operator:
 
 * Bare metal
 

modules/nw-metallb-layer2-limitations.adoc

@@ -2,10 +2,13 @@
 //
 // * networking/metallb/about-metallb.adoc
 
-:_mod-docs-content-type: REFERENCE
+:_mod-docs-content-type: CONCEPT
 [id="nw-metallb-layer2-limitations_{context}"]
 = Limitations for layer 2 mode
 
+[role="_abstract"]
+In {product-title}, MetalLB layer 2 mode is limited to single-node bandwidth and failover depends on client ARP handling. Avoid using the same VLAN for MetalLB and an additional network to prevent connection failures.
+
 [id="nw-metallb-layer2-limitations-bottleneck_{context}"]
 == Single-node bottleneck
 

modules/nw-metallb-layer2.adoc

@@ -7,8 +7,8 @@
 [id="nw-metallb-layer2_{context}"]
 = MetalLB concepts for layer 2 mode
 
-In layer 2 mode, the `speaker` pod on one node announces the external IP address for a service to the host network.
-From a network perspective, the node appears to have multiple IP addresses assigned to a network interface.
+[role="_abstract"]
+MetalLB in layer 2 mode announces the external IP for a LoadBalancer service from one node via ARP or NDP. All traffic for the service goes through that node, and failover to another node is automatic when the node becomes unavailable.
 
 [NOTE]
 ====

modules/nw-metallb-limitations-and-restrictions.adoc

@@ -0,0 +1,10 @@
+// Module included in the following assemblies:
+//
+// * networking/metallb/about-metallb.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="nw-metallb-limitations-and-restrictions_{context}"]
+= Limitations and restrictions
+
+[role="_abstract"]
+MetalLB has limitations for infrastructure, layer 2 mode, and BGP mode in {product-title}. Consider infrastructure fit, layer 2 single-node bandwidth and failover, and BGP connection resets and single ASN when you plan your deployment.

modules/nw-metallb-operator-custom-resources.adoc

@@ -6,7 +6,8 @@
 [id="nw-metallb-operator-custom-resources_{context}"]
 = MetalLB Operator custom resources
 
-The MetalLB Operator monitors its own namespace for the following custom resources:
+[role="_abstract"]
+In {product-title}, you configure MetalLB deployment and IP advertisement through custom resources that the MetalLB Operator monitors. The resources include `MetalLB`, `IPAddressPool`, `L2Advertisement`, `BGPAdvertisement`, `BGPPeer`, and `BFDProfile`.
 
 `MetalLB`::
 When you add a `MetalLB` custom resource to the cluster, the MetalLB Operator deploys MetalLB on the cluster.

modules/nw-metallb-software-components.adoc

@@ -6,6 +6,9 @@
 [id="nw-metallb-software-components_{context}"]
 = MetalLB software components
 
+[role="_abstract"]
+In {product-title}, you get external IPs for LoadBalancer services from two MetalLB components. The controller assigns IPs from address pools, and the speaker advertises them via layer 2 or BGP.
+
 When you install the MetalLB Operator, the `metallb-operator-controller-manager` deployment starts a pod. The pod is the implementation of the Operator. The pod monitors for changes to all the relevant resources.
 
 When the Operator starts an instance of MetalLB, it starts a `controller` deployment and a `speaker` daemon set.

modules/nw-metallb-when-metallb.adoc

@@ -6,6 +6,9 @@
 [id="nw-metallb-when-metallb_{context}"]
 = When to use MetalLB
 
+[role="_abstract"]
+To get fault-tolerant access to applications through an external IP on bare metal in {product-title}, you can use MetalLB.
+
 Using MetalLB is valuable when you have a bare-metal cluster, or an infrastructure that is like bare metal, and you want fault-tolerant access to an application through an external IP address.
 
 You must configure your networking infrastructure to ensure that network traffic for the external IP address is routed from clients to the host network for the cluster.

networking/networking_operators/metallb-operator/about-metallb.adoc

@@ -6,8 +6,8 @@ include::_attributes/common-attributes.adoc[]
 
 toc::[]
 
-As a cluster administrator, you can add the MetalLB Operator to your cluster so that when a service of type `LoadBalancer` is added to the cluster, MetalLB can add an external IP address for the service.
-The external IP address is added to the host network for your cluster.
+[role="_abstract"]
+In {product-title} clusters running on bare metal or without a cloud load balancer, you can use the MetalLB Operator to assign external IP addresses to LoadBalancer services. These services receive external IPs on the host network.
 
 // When to deploy MetalLB
 include::modules/nw-metallb-when-metallb.adoc[leveloffset=+1]
@@ -27,8 +27,8 @@ include::modules/nw-metallb-layer2.adoc[leveloffset=+1]
 // BGP
 include::modules/nw-metallb-bgp.adoc[leveloffset=+1]
 
-[id="limitations-and-restrictions_{context}"]
-== Limitations and restrictions
+//Limitations
+include::modules/nw-metallb-limitations-and-restrictions.adoc[leveloffset=+1]
 
 // Infra considerations
 include::modules/nw-metallb-infra-considerations.adoc[leveloffset=+2]
@@ -40,7 +40,7 @@ include::modules/nw-metallb-layer2-limitations.adoc[leveloffset=+2]
 include::modules/nw-metallb-bgp-limitations.adoc[leveloffset=+2]
 
 [role="_additional-resources"]
-[id="additional-resources_about-metallb-and-metallb-operator"]
+[id="additional-resources_{context}"]
 == Additional resources
 
 * xref:../../../networking/ingress_load_balancing/configuring_ingress_cluster_traffic/overview-traffic.adoc#overview-traffic-comparision_overview-traffic[Comparison: Fault tolerant access to external IP addresses]