diff --git a/modules/nw-metallb-bgp-limitations.adoc b/modules/nw-metallb-bgp-limitations.adoc index 66f51dfb9d..6a787bd684 100644 --- a/modules/nw-metallb-bgp-limitations.adoc +++ b/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 diff --git a/modules/nw-metallb-bgp.adoc b/modules/nw-metallb-bgp.adoc index bfd7dae173..ca5704177d 100644 --- a/modules/nw-metallb-bgp.adoc +++ b/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. diff --git a/modules/nw-metallb-extern-traffic-pol.adoc b/modules/nw-metallb-extern-traffic-pol.adoc index 5a53f5e056..c61229ad7c 100644 --- a/modules/nw-metallb-extern-traffic-pol.adoc +++ b/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`:: diff --git a/modules/nw-metallb-infra-considerations.adoc b/modules/nw-metallb-infra-considerations.adoc index 3722d2551d..307cd516bf 100644 --- a/modules/nw-metallb-infra-considerations.adoc +++ b/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 diff --git a/modules/nw-metallb-layer2-limitations.adoc b/modules/nw-metallb-layer2-limitations.adoc index 9688507e90..5db8f4e462 100644 --- a/modules/nw-metallb-layer2-limitations.adoc +++ b/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 diff --git a/modules/nw-metallb-layer2.adoc b/modules/nw-metallb-layer2.adoc index 8ee0449c8d..3fe3aea853 100644 --- a/modules/nw-metallb-layer2.adoc +++ b/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] ==== diff --git a/modules/nw-metallb-limitations-and-restrictions.adoc b/modules/nw-metallb-limitations-and-restrictions.adoc new file mode 100644 index 0000000000..81f1c4d66c --- /dev/null +++ b/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. \ No newline at end of file diff --git a/modules/nw-metallb-operator-custom-resources.adoc b/modules/nw-metallb-operator-custom-resources.adoc index 154b2ed4ab..2791dadea1 100644 --- a/modules/nw-metallb-operator-custom-resources.adoc +++ b/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. diff --git a/modules/nw-metallb-software-components.adoc b/modules/nw-metallb-software-components.adoc index c72133ac8d..75201994a4 100644 --- a/modules/nw-metallb-software-components.adoc +++ b/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. diff --git a/modules/nw-metallb-when-metallb.adoc b/modules/nw-metallb-when-metallb.adoc index 0855f06633..13fdb86e15 100644 --- a/modules/nw-metallb-when-metallb.adoc +++ b/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. diff --git a/networking/networking_operators/metallb-operator/about-metallb.adoc b/networking/networking_operators/metallb-operator/about-metallb.adoc index 75e2831d26..9fb1e59cfb 100644 --- a/networking/networking_operators/metallb-operator/about-metallb.adoc +++ b/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]