From 4b769c85e78432b8d0fb155b6dbda0de267fc3ed Mon Sep 17 00:00:00 2001 From: dfitzmau Date: Thu, 15 Jan 2026 12:42:06 +0000 Subject: [PATCH] OSDOCS-16863-2: CQA for MetalLB Ingress and Route Configuration --- modules/nw-metallb-addresspool-cr.adoc | 31 +++++---- modules/nw-metallb-bfdprofile-cr.adoc | 45 +++++-------- modules/nw-metallb-bgppeer-cr.adoc | 63 +++++++------------ ...w-metallb-configure-address-pool-vlan.adoc | 31 +++++---- .../nw-metallb-configure-address-pool.adoc | 14 +++-- modules/nw-metallb-configure-bfdprofle.adoc | 7 ++- modules/nw-metallb-configure-bgppeer.adoc | 12 ++-- ...lb-configure-specificpools-to-bgppeer.adoc | 47 ++++++++------ modules/nw-metallb-configure-vrf-bgppeer.adoc | 41 ++++++------ modules/nw-metallb-example-addresspool.adoc | 36 ++++++----- modules/nw-metallb-example-bgppeer.adoc | 36 ++++++----- .../metallb-configure-address-pools.adoc | 10 ++- .../metallb-configure-bfd-profiles.adoc | 13 ++-- .../metallb/metallb-configure-bgp-peers.adoc | 17 +++-- 14 files changed, 203 insertions(+), 200 deletions(-) diff --git a/modules/nw-metallb-addresspool-cr.adoc b/modules/nw-metallb-addresspool-cr.adoc index c0f5b12d4f..35f0c90fd4 100644 --- a/modules/nw-metallb-addresspool-cr.adoc +++ b/modules/nw-metallb-addresspool-cr.adoc @@ -6,51 +6,48 @@ [id="nw-metallb-ipaddresspool-cr_{context}"] = About the IPAddressPool custom resource -The fields for the `IPAddressPool` custom resource are described in the following tables. +[role="_abstract"] +To define the IP address ranges available for load balancer services, configure the properties of the MetalLB `IPAddressPool` custom resource (CR). Establishing these parameters allows your cluster to automatically allocate specific external addresses to your application workloads. + +The following table details the parameters for the `IPAddressPool` CR: .MetalLB IPAddressPool pool custom resource [cols="1,1,3a", options="header"] |=== -|Field +|Parameter |Type |Description |`metadata.name` |`string` -|Specifies the name for the address pool. -When you add a service, you can specify this pool name in the `metallb.io/address-pool` annotation to select an IP address from a specific pool. -The names `doc-example`, `silver`, and `gold` are used throughout the documentation. +|Specifies the name for the address pool. When you add a service, you can specify this pool name in the `metallb.io/address-pool` annotation to select an IP address from a specific pool. The names `doc-example`, `silver`, and `gold` are used throughout the documentation. |`metadata.namespace` |`string` -|Specifies the namespace for the address pool. -Specify the same namespace that the MetalLB Operator uses. +|Specifies the namespace for the address pool. Specify the same namespace that the MetalLB Operator uses. |`metadata.label` |`string` -|Optional: Specifies the key value pair assigned to the `IPAddressPool`. This can be referenced by the `ipAddressPoolSelectors` in the `BGPAdvertisement` and `L2Advertisement` CRD to associate the `IPAddressPool` with the advertisement +|Optional: Specifies the key-value pair assigned to the `IPAddressPool`. This can be referenced by the `ipAddressPoolSelectors` in the `BGPAdvertisement` and `L2Advertisement` CRD to associate the `IPAddressPool` with the advertisement |`spec.addresses` |`string` -|Specifies a list of IP addresses for MetalLB Operator to assign to services. -You can specify multiple ranges in a single pool; they will all share the same settings. -Specify each range in CIDR notation or as starting and ending IP addresses separated with a hyphen. +|Specifies a list of IP addresses for the MetalLB Operator to assign to services. You can specify multiple ranges in a single pool, where these ranges all share the same settings. Specify each range in Classless Inter-Domain Routing (CIDR) notation or as starting and ending IP addresses separated with a hyphen. |`spec.autoAssign` |`boolean` -|Optional: Specifies whether MetalLB automatically assigns IP addresses from this pool. -Specify `false` if you want to explicitly request an IP address from this pool with the `metallb.io/address-pool` annotation. -The default value is `true`. +|Optional: Specifies whether the MetalLB Operator automatically assigns IP addresses from this pool. +Specify `false` if you want to explicitly request an IP address from this pool with the `metallb.io/address-pool` annotation. The default value is `true`. [NOTE] ==== -For IP address pool configurations, ensure the addresses field specifies only IPs that are available and not in use by other network devices, especially gateway addresses, to prevent conflicts when `autoAssign` is enabled. +For IP address pool configurations, ensure the addresses parameter specifies only IP addresses that are available and not in use by other network devices, especially gateway addresses, to prevent conflicts when `autoAssign` is enabled. ==== |`spec.avoidBuggyIPs` |`boolean` -|Optional: This ensures when enabled that IP addresses ending `.0` and `.255` are not allocated from the pool. The default value is `false`. Some older consumer network equipment mistakenly block IP addresses ending in `.0` and `.255`. +|Optional: When you set the parameter to enabled, the IP addresses ending `.0` and `.255` are not allocated from the pool. The default value is `false`. Some older consumer network equipment mistakenly block IP addresses ending in `.0` and `.255`. |=== @@ -60,7 +57,7 @@ You can assign IP addresses from an `IPAddressPool` to services and namespaces b [cols="1,1,3a", options="header"] |=== -|Field +|Parameter |Type |Description diff --git a/modules/nw-metallb-bfdprofile-cr.adoc b/modules/nw-metallb-bfdprofile-cr.adoc index 72603f23ac..d4f5b7e6fb 100644 --- a/modules/nw-metallb-bfdprofile-cr.adoc +++ b/modules/nw-metallb-bfdprofile-cr.adoc @@ -6,13 +6,16 @@ [id="nw-metallb-bfdprofile-cr_{context}"] = About the BFD profile custom resource -The fields for the BFD profile custom resource are described in the following table. +[role="_abstract"] +To enable rapid detection of communication failures between routing peers, configure the properties of the MetalLB BFD profile custom resource (CR). Defining these parameters ensures that network traffic is quickly rerouted if a path becomes unavailable, maintaining high cluster reachability and stability. + +The following table describes parameters for the BFD profile CR: .BFD profile custom resource [cols="1,1,3a",options="header"] |=== -|Field +|Parameter |Type |Description @@ -26,58 +29,40 @@ The fields for the BFD profile custom resource are described in the following ta |`spec.detectMultiplier` |`integer` -|Specifies the detection multiplier to determine packet loss. -The remote transmission interval is multiplied by this value to determine the connection loss detection timer. +|Specifies the detection multiplier to determine packet loss. The remote transmission interval is multiplied by this value to determine the connection loss detection timer. -For example, when the local system has the detect multiplier set to `3` and the remote system has the transmission interval set to `300`, the local system detects failures only after `900` ms without receiving packets. - -The range is `2` to `255`. -The default value is `3`. +For example, when the local system has the detect multiplier set to `3` and the remote system has the transmission interval set to `300`, the local system detects failures only after `900` ms without receiving packets. The range is `2` to `255`. The default value is `3`. |`spec.echoMode` |`boolean` -|Specifies the echo transmission mode. -If you are not using distributed BFD, echo transmission mode works only when the peer is also FRR. -The default value is `false` and echo transmission mode is disabled. +|Specifies the echo transmission mode. If you are not using distributed BFD, echo transmission mode works only when the peer is also FRR. The default value is `false` and echo transmission mode is disabled. When echo transmission mode is enabled, consider increasing the transmission interval of control packets to reduce bandwidth usage. For example, consider increasing the transmit interval to `2000` ms. |`spec.echoInterval` |`integer` -|Specifies the minimum transmission interval, less jitter, that this system uses to send and receive echo packets. -The range is `10` to `60000`. -The default value is `50` ms. +|Specifies the minimum transmission interval, less jitter, that this system uses to send and receive echo packets. The range is `10` to `60000`. The default value is `50` ms. |`spec.minimumTtl` |`integer` -|Specifies the minimum expected TTL for an incoming control packet. -This field applies to multi-hop sessions only. +|Specifies the minimum expected TTL for an incoming control packet. This field applies to multi-hop sessions only. -The purpose of setting a minimum TTL is to make the packet validation requirements more stringent and avoid receiving control packets from other sessions. - -The default value is `254` and indicates that the system expects only one hop between this system and the peer. +The purpose of setting a minimum TTL is to make the packet validation requirements more stringent and avoid receiving control packets from other sessions. The default value is `254` and indicates that the system expects only one hop between this system and the peer. |`spec.passiveMode` |`boolean` -|Specifies whether a session is marked as active or passive. -A passive session does not attempt to start the connection. +|Specifies whether a session is marked as active or passive. A passive session does not attempt to start the connection. Instead, a passive session waits for control packets from a peer before it begins to reply. -Marking a session as passive is useful when you have a router that acts as the central node of a star network and you want to avoid sending control packets that you do not need the system to send. - -The default value is `false` and marks the session as active. +Marking a session as passive is useful when you have a router that acts as the central node of a star network and you want to avoid sending control packets that you do not need the system to send. The default value is `false` and marks the session as active. |`spec.receiveInterval` |`integer` -|Specifies the minimum interval that this system is capable of receiving control packets. -The range is `10` to `60000`. -The default value is `300` ms. +|Specifies the minimum interval that this system is capable of receiving control packets. The range is `10` to `60000`. The default value is `300` ms. |`spec.transmitInterval` |`integer` -|Specifies the minimum transmission interval, less jitter, that this system uses to send control packets. -The range is `10` to `60000`. -The default value is `300` ms. +|Specifies the minimum transmission interval, less jitter, that this system uses to send control packets. The range is `10` to `60000`. The default value is `300` ms. |=== diff --git a/modules/nw-metallb-bgppeer-cr.adoc b/modules/nw-metallb-bgppeer-cr.adoc index 3e31bc06ed..b19d291306 100644 --- a/modules/nw-metallb-bgppeer-cr.adoc +++ b/modules/nw-metallb-bgppeer-cr.adoc @@ -6,83 +6,69 @@ [id="nw-metallb-bgppeer-cr_{context}"] = About the BGP peer custom resource -The fields for the BGP peer custom resource are described in the following table. +[role="_abstract"] +To establish network connectivity and advertise routes for load-balancer services, configure the properties of the MetalLB Border Gateway Protocol (BGP) peer custom resource (CR). Establishing these parameters ensures that your cluster authorizes specific routing peers to direct external traffic correctly to your application workloads. + +The following table describes the parameters for the BGP peer CR: .MetalLB BGP peer custom resource [cols="1,1,3",options="header"] |=== -|Field +|Parameter |Type |Description |`metadata.name` |`string` -|Specifies the name for the BGP peer custom resource. +|Specifies the name for the BGP peer CR. |`metadata.namespace` |`string` -|Specifies the namespace for the BGP peer custom resource. +|Specifies the namespace for the BGP peer CR. |`spec.myASN` |`integer` -|Specifies the Autonomous System Number (ASN) for the local end of the BGP session. -In all BGP peer custom resources that you add, specify the same value . -The range is `0` to `4294967295`. +|Specifies the Autonomous System Number (ASN) for the local end of the BGP session. In all BGP peer CRs that you add, specify the same value. The range is `0` to `4294967295`. |`spec.peerASN` |`integer` -|Specifies the ASN for the remote end of the BGP session. -The range is `0` to `4294967295`. -If you use this field, you cannot specify a value in the `spec.dynamicASN` field. +|Specifies the ASN for the remote end of the BGP session. The range is `0` to `4294967295`. If you use this parameter, you cannot specify a value in the `spec.dynamicASN` parameter. |`spec.dynamicASN` |`string` -| Detects the ASN to use for the remote end of the session without explicitly setting it. -Specify `internal` for a peer with the same ASN, or `external` for a peer with a different ASN. -If you use this field, you cannot specify a value in the `spec.peerASN` field. +| Detects the ASN to use for the remote end of the session without explicitly setting it. Specify `internal` for a peer with the same ASN, or `external` for a peer with a different ASN. If you use this parameter, you cannot specify a value in the `spec.peerASN` parameter. |`spec.peerAddress` |`string` -|Specifies the IP address of the peer to contact for establishing the BGP session. -If you use this field, you cannot specify a value in the `spec.interface` field. +|Specifies the IP address of the peer to contact for establishing the BGP session. If you use this parameter, you cannot specify a value in the `spec.interface` parameter. |`spec.interface` |`string` -|Specifies the interface name to use when establishing a session. -Use this field to configure unnumbered BGP peering. -You must establish a point-to-point, layer 2 connection between the two BGP peers. -You can use unnumbered BGP peering with IPv4, IPv6, or dual-stack, but you must enable IPv6 RAs (Router Advertisements). -Each interface is limited to one BGP connection. -If you use this field, you cannot specify a value in the `spec.peerAddress` field. +|Specifies the interface name to use when establishing a session. Use this parameter to configure unnumbered BGP peering. +You must establish a point-to-point, layer 2 connection between the two BGP peers. You can use unnumbered BGP peering with IPv4, IPv6, or dual-stack, but you must enable IPv6 RAs (Router Advertisements). Each interface is limited to one BGP connection. +If you use this parameter, you cannot specify a value in the `spec.peerAddress` parameter. |`spec.sourceAddress` |`string` -|Optional: Specifies the IP address to use when establishing the BGP session. -The value must be an IPv4 address. +|Optional: Specifies the IP address to use when establishing the BGP session. The value must be an IPv4 address. |`spec.peerPort` |`integer` -|Optional: Specifies the network port of the peer to contact for establishing the BGP session. -The range is `0` to `16384`. +|Optional: Specifies the network port of the peer to contact for establishing the BGP session. The range is `0` to `16384`. |`spec.holdTime` |`string` -|Optional: Specifies the duration for the hold time to propose to the BGP peer. -The minimum value is 3 seconds (`3s`). -The common units are seconds and minutes, such as `3s`, `1m`, and `5m30s`. -To detect path failures more quickly, also configure BFD. +|Optional: Specifies the duration for the hold time to propose to the BGP peer. The minimum value is 3 seconds (`3s`). +The common units are seconds and minutes, such as `3s`, `1m`, and `5m30s`. To detect path failures more quickly, also configure BFD. |`spec.keepaliveTime` |`string` -|Optional: Specifies the maximum interval between sending keep-alive messages to the BGP peer. -If you specify this field, you must also specify a value for the `holdTime` field. -The specified value must be less than the value for the `holdTime` field. +|Optional: Specifies the maximum interval between sending keep-alive messages to the BGP peer. If you specify this parameter, you must also specify a value for the `holdTime` parameter. The specified value must be less than the value for the `holdTime` parameter. |`spec.routerID` |`string` -|Optional: Specifies the router ID to advertise to the BGP peer. -If you specify this field, you must specify the same value in every BGP peer custom resource that you add. +|Optional: Specifies the router ID to advertise to the BGP peer. If you specify this parameter, you must specify the same value in every BGP peer custom resource that you add. |`spec.password` |`string` @@ -90,7 +76,7 @@ If you specify this field, you must specify the same value in every BGP peer cus |`spec.passwordSecret` |`string` -|Optional: Specifies name of the authentication secret for the BGP Peer. The secret must live in the `metallb` namespace and be of type basic-auth. +|Optional: Specifies name of the authentication secret for the BGP peer. The secret must live in the `metallb` namespace and be of type basic-auth. |`spec.bfdProfile` |`string` @@ -102,10 +88,7 @@ If you specify this field, you must specify the same value in every BGP peer cus |`spec.ebgpMultiHop` |`boolean` -|Optional: Specifies that the BGP peer is multiple network hops away. -If the BGP peer is not directly connected to the same network, the speaker cannot establish a BGP session unless this field is set to `true`. -This field applies to _external BGP_. -External BGP is the term that is used to describe when a BGP peer belongs to a different Autonomous System. +|Optional: Specifies that the BGP peer is multiple network hops away. If the BGP peer is not directly connected to the same network, the speaker cannot establish a BGP session unless this parameter is set to `true`. This parameter applies to _external BGP_.External BGP is the term that is used to describe when a BGP peer belongs to a different Autonomous System. |`connectTime` |`duration` @@ -115,5 +98,5 @@ External BGP is the term that is used to describe when a BGP peer belongs to a d [NOTE] ==== -The `passwordSecret` field is mutually exclusive with the `password` field, and contains a reference to a secret containing the password to use. Setting both fields results in a failure of the parsing. +The `passwordSecret` parameter is mutually exclusive with the `password` parameter, and contains a reference to a secret containing the password to use. Setting both parameters results in a failure of the parsing. ==== diff --git a/modules/nw-metallb-configure-address-pool-vlan.adoc b/modules/nw-metallb-configure-address-pool-vlan.adoc index 6ccd44bc56..bcb0e6d749 100644 --- a/modules/nw-metallb-configure-address-pool-vlan.adoc +++ b/modules/nw-metallb-configure-address-pool-vlan.adoc @@ -2,14 +2,13 @@ [id="nw-metallb-configure-address-pool-vlan_{context}"] = Configure MetalLB address pool for VLAN -As a cluster administrator, you can add address pools to your cluster to control the IP addresses on a created VLAN that MetalLB can assign to load-balancer services +[role="_abstract"] +To precisely manage external access across a specific VLAN, configure MetalLB address pools for your cluster. Defining these pools ensures that load balancer services receive authorized IP addresses from designated network ranges for secure and consistent routing. .Prerequisites -* Install the OpenShift CLI (`oc`). - +* Install the {oc-first}. * Configure a separate VLAN. - * Log in as a user with `cluster-admin` privileges. .Procedure @@ -24,13 +23,17 @@ metadata: namespace: metallb-system name: doc-example-vlan labels: - zone: east <1> + zone: east spec: addresses: - - 192.168.100.1-192.168.100.254 <2> + - 192.168.100.1-192.168.100.254 +# ... ---- -<1> This label assigned to the `IPAddressPool` can be referenced by the `ipAddressPoolSelectors` in the `BGPAdvertisement` CRD to associate the `IPAddressPool` with the advertisement. -<2> This IP range must match the subnet assigned to the VLAN on your network. To support layer 2 (L2) mode, the IP address range must be within the same subnet as the cluster nodes. ++ +where: ++ +`labels.zone`:: This label assigned to the `IPAddressPool` can be referenced by the `ipAddressPoolSelectors` in the `BGPAdvertisement` CRD to associate the `IPAddressPool` with the advertisement. +`spec.addresses`:: This IP range must match the subnet assigned to the VLAN on your network. To support layer 2 (L2) mode, the IP address range must be within the same subnet as the cluster nodes. . Apply the configuration for the IP address pool: + @@ -39,7 +42,7 @@ spec: $ oc apply -f ipaddresspool-vlan.yaml ---- -. To ensure this configuration applies to the VLAN you need to set the `spec` `gatewayConfig.ipForwarding` to `Global`. +. To ensure this configuration applies to the VLAN, you need to set the `spec` `gatewayConfig.ipForwarding` to `Global`. + .. Run the following command to edit the network configuration custom resource (CR): + @@ -48,12 +51,14 @@ $ oc apply -f ipaddresspool-vlan.yaml $ oc edit network.operator.openshift/cluster ---- + -.. Update the `spec.defaultNetwork.ovnKubernetesConfig` section to include the `gatewayConfig.ipForwarding` set to `Global`. It should look something like this: +.. Update the `spec.defaultNetwork.ovnKubernetesConfig` section to include the `gatewayConfig.ipForwarding` set to `Global`. The following example demonstrates this configuration: + -.Example [source,yaml] ---- -... +apiVersion: operator.openshift.io/v1 +kind: Network +metadata: + name: cluster spec: clusterNetwork: - cidr: 10.128.0.0/14 @@ -63,5 +68,5 @@ spec: ovnKubernetesConfig: gatewayConfig: ipForwarding: Global -... +# ... ---- \ No newline at end of file diff --git a/modules/nw-metallb-configure-address-pool.adoc b/modules/nw-metallb-configure-address-pool.adoc index 6066412dd1..977be1ac7f 100644 --- a/modules/nw-metallb-configure-address-pool.adoc +++ b/modules/nw-metallb-configure-address-pool.adoc @@ -2,11 +2,12 @@ [id="nw-metallb-configure-address-pool_{context}"] = Configuring an address pool -As a cluster administrator, you can add address pools to your cluster to control the IP addresses that MetalLB can assign to load-balancer services. +[role="_abstract"] +To precisely manage external access to application workloads, configure MetalLB address pools for your cluster. By defining these pools, you can control the specific IP address ranges assigned to load balancer services for consistent network routing. .Prerequisites -* Install the OpenShift CLI (`oc`). +* Install the {oc-first}. * Log in as a user with `cluster-admin` privileges. .Procedure @@ -20,7 +21,7 @@ kind: IPAddressPool metadata: namespace: metallb-system name: doc-example - labels: <1> + labels: zone: east spec: addresses: @@ -28,9 +29,12 @@ spec: - 203.0.113.65-203.0.113.75 # ... ---- -<1> This label assigned to the `IPAddressPool` can be referenced by the `ipAddressPoolSelectors` in the `BGPAdvertisement` CRD to associate the `IPAddressPool` with the advertisement. ++ +where: ++ +`labels`:: The label assigned to the `IPAddressPool` can be referenced by the `ipAddressPoolSelectors` in the `BGPAdvertisement` CRD to associate the `IPAddressPool` with the advertisement. -. Apply the configuration for the IP address pool: +. Apply the configuration for the IP address pool by entering the following command: + [source,terminal] ---- diff --git a/modules/nw-metallb-configure-bfdprofle.adoc b/modules/nw-metallb-configure-bfdprofle.adoc index 32af2e4127..eb2fdd2e1b 100644 --- a/modules/nw-metallb-configure-bfdprofle.adoc +++ b/modules/nw-metallb-configure-bfdprofle.adoc @@ -6,12 +6,12 @@ [id="nw-metallb-configure-bfdprofile_{context}"] = Configuring a BFD profile -As a cluster administrator, you can add a BFD profile and configure a BGP peer to use the profile. BFD provides faster path failure detection than BGP alone. +[role="_abstract"] +To achieve faster path failure detection for BGP sessions, configure a MetalLB BFD profile and associate it with a BGP peer. Establishing these profiles ensures that your network routing remains highly available and responsive by identifying connectivity issues more rapidly than standard protocols. .Prerequisites -* Install the OpenShift CLI (`oc`). - +* Install the {oc-first}. * Log in as a user with `cluster-admin` privileges. .Procedure @@ -32,6 +32,7 @@ spec: echoMode: false passiveMode: true minimumTtl: 254 +# ... ---- . Apply the configuration for the BFD profile: diff --git a/modules/nw-metallb-configure-bgppeer.adoc b/modules/nw-metallb-configure-bgppeer.adoc index 7f85ec7d6a..b379db8e5b 100644 --- a/modules/nw-metallb-configure-bgppeer.adoc +++ b/modules/nw-metallb-configure-bgppeer.adoc @@ -6,14 +6,15 @@ [id="nw-metallb-configure-bgppeer_{context}"] = Configuring a BGP peer -As a cluster administrator, you can add a BGP peer custom resource to exchange routing information with network routers and advertise the IP addresses for services. +[role="_abstract"] +To exchange routing information and advertise IP addresses for load balancer services, configure MetalLB BGP peer CRs. Establishing these peers ensures that your network infrastructure can reach and correctly route traffic to cluster application workloads. + +You can add a BGP peer custom resource to exchange routing information with network routers and advertise the IP addresses for services. .Prerequisites -* Install the OpenShift CLI (`oc`). - +* Install the {oc-first}. * Log in as a user with `cluster-admin` privileges. - * Configure MetalLB with a BGP advertisement. .Procedure @@ -32,9 +33,10 @@ spec: peerASN: 64501 myASN: 64500 routerID: 10.10.10.10 +# ... ---- -. Apply the configuration for the BGP peer: +. Apply the BGP peer configuration by entering the following command: + [source,terminal] ---- diff --git a/modules/nw-metallb-configure-specificpools-to-bgppeer.adoc b/modules/nw-metallb-configure-specificpools-to-bgppeer.adoc index 17e03843c3..256f2fa4ab 100644 --- a/modules/nw-metallb-configure-specificpools-to-bgppeer.adoc +++ b/modules/nw-metallb-configure-specificpools-to-bgppeer.adoc @@ -6,22 +6,24 @@ [id="nw-metallb-example-assign-specific-address-pools-specific-bgp-peers_{context}"] = Configure a specific set of BGP peers for a given address pool -This procedure illustrates how to: +[role="_abstract"] +To assign specific IP address pools to designated BGP peers, configure MetalLB BGP advertisements. Establishing these mappings ensures that your cluster advertises designated network ranges only to authorized routing peers for precise external traffic control. -* Configure a set of address pools (`pool1` and `pool2`). -* Configure a set of BGP peers (`peer1` and `peer2`). +This procedure demonstrates the following tasks: + +* Configure a set of address pools: `pool1` and `pool2`. +* Configure a set of BGP peers: `peer1` and `peer2`. * Configure BGP advertisement to assign `pool1` to `peer1` and `pool2` to `peer2`. .Prerequisites -* Install the OpenShift CLI (`oc`). - +* Install the {oc-first}. * Log in as a user with `cluster-admin` privileges. .Procedure . Create address pool `pool1`. - ++ .. Create a file, such as `ipaddresspool1.yaml`, with content like the following example: + [source,yaml] @@ -35,8 +37,9 @@ spec: addresses: - 4.4.4.100-4.4.4.200 - 2001:100:4::200-2001:100:4::400 +# ... ---- - ++ .. Apply the configuration for the IP address pool `pool1`: + [source,terminal] @@ -45,7 +48,7 @@ $ oc apply -f ipaddresspool1.yaml ---- . Create address pool `pool2`. - ++ .. Create a file, such as `ipaddresspool2.yaml`, with content like the following example: + [source,yaml] @@ -59,16 +62,18 @@ spec: addresses: - 5.5.5.100-5.5.5.200 - 2001:100:5::200-2001:100:5::400 +# ... ---- - ++ .. Apply the configuration for the IP address pool `pool2`: + [source,terminal] ---- $ oc apply -f ipaddresspool2.yaml ---- -. Create BGP `peer1`. +. Create BGP `peer1`. ++ .. Create a file, such as `bgppeer1.yaml`, with content like the following example: + [source,yaml] @@ -83,9 +88,10 @@ spec: peerASN: 64501 myASN: 64500 routerID: 10.10.10.10 +# ... ---- - -.. Apply the configuration for the BGP peer: ++ +.. Apply the configuration for the BGP `peer1`: + [source,terminal] ---- @@ -93,7 +99,7 @@ $ oc apply -f bgppeer1.yaml ---- . Create BGP `peer2`. - ++ .. Create a file, such as `bgppeer2.yaml`, with content like the following example: + [source,yaml] @@ -108,9 +114,10 @@ spec: peerASN: 64501 myASN: 64500 routerID: 10.10.10.10 +# ... ---- - -.. Apply the configuration for the BGP peer2: ++ +.. Apply the configuration for the BGP `peer2`: + [source,terminal] ---- @@ -118,7 +125,7 @@ $ oc apply -f bgppeer2.yaml ---- . Create BGP advertisement 1. - ++ .. Create a file, such as `bgpadvertisement1.yaml`, with content like the following example: + [source,yaml] @@ -138,8 +145,9 @@ spec: aggregationLength: 32 aggregationLengthV6: 128 localPref: 100 +# ... ---- - ++ .. Apply the configuration: + [source,terminal] @@ -148,7 +156,7 @@ $ oc apply -f bgpadvertisement1.yaml ---- . Create BGP advertisement 2. - ++ .. Create a file, such as `bgpadvertisement2.yaml`, with content like the following example: + [source,yaml] @@ -168,8 +176,9 @@ spec: aggregationLength: 32 aggregationLengthV6: 128 localPref: 100 +# ... ---- - ++ .. Apply the configuration: + [source,terminal] diff --git a/modules/nw-metallb-configure-vrf-bgppeer.adoc b/modules/nw-metallb-configure-vrf-bgppeer.adoc index d42fa002fa..41042bebc2 100644 --- a/modules/nw-metallb-configure-vrf-bgppeer.adoc +++ b/modules/nw-metallb-configure-vrf-bgppeer.adoc @@ -6,7 +6,8 @@ [id="nw-metallb-bgp-peer-vrf_{context}"] = Exposing a service through a network VRF -You can expose a service through a virtual routing and forwarding (VRF) instance by associating a VRF on a network interface with a BGP peer. +[role="_abstract"] +To isolate network traffic and manage multiple routing tables, expose a service through a virtual routing and forwarding (VRF) instance. Associating a VRF with a MetalLB BGP peer ensures that external traffic is segmented and correctly routed to the intended application workloads. :FeatureName: Exposing a service through a VRF on a BGP peer include::snippets/technology-preview.adoc[] @@ -20,24 +21,24 @@ By establishing a BGP session through an interface belonging to a network VRF, M To enable the traffic directed to the service to reach the OVN-Kubernetes network infrastructure, you must configure routing rules to define the next hops for network traffic. See the `NodeNetworkConfigurationPolicy` resource in "Managing symmetric routing with MetalLB" in the _Additional resources_ section for more information. ==== -These are the high-level steps to expose a service through a network VRF with a BGP peer: +The following high-level steps demonstrate how to expose a service through a network VRF with a BGP peer: . Define a BGP peer and add a network VRF instance. . Specify an IP address pool for MetalLB. -. Configure a BGP route advertisement for MetalLB to advertise a route using the specified IP address pool and the BGP peer associated with the VRF instance. +. Configure a BGP route advertisement for MetalLB to advertise a route by using the specified IP address pool and the BGP peer associated with the VRF instance. . Deploy a service to test the configuration. .Prerequisites -* You installed the OpenShift CLI (`oc`). +* You installed the {oc-first}. * You logged in as a user with `cluster-admin` privileges. -* You defined a `NodeNetworkConfigurationPolicy` to associate a Virtual Routing and Forwarding (VRF) instance with a network interface. For more information about completing this prerequisite, see the _Additional resources_ section. +* You defined a `NodeNetworkConfigurationPolicy` (NNCP) to associate a Virtual Routing and Forwarding (VRF) instance with a network interface. For more information about completing this prerequisite, see the _Additional resources_ section. * You installed MetalLB on your cluster. .Procedure -. Create a `BGPPeer` custom resources (CR): - +. Create a `BGPPeer` custom resource (CR): ++ .. Create a file, such as `frrviavrf.yaml`, with content like the following example: + [source,yaml] @@ -51,15 +52,16 @@ spec: myASN: 100 peerASN: 200 peerAddress: 192.168.130.1 - vrf: ens4vrf <1> + vrf: ens4vrf +# ... ---- -<1> Specifies the network VRF instance to associate with the BGP peer. MetalLB can advertise services and make routing decisions based on the routing information in the VRF. +`spec.vrf`: Specifies the network VRF instance to associate with the BGP peer. MetalLB can advertise services and make routing decisions based on the routing information in the VRF. + [NOTE] ==== You must configure this network VRF instance in a `NodeNetworkConfigurationPolicy` CR. See the _Additional resources_ for more information. ==== - ++ .. Apply the configuration for the BGP peer by running the following command: + [source,terminal] @@ -68,7 +70,7 @@ $ oc apply -f frrviavrf.yaml ---- . Create an `IPAddressPool` CR: - ++ .. Create a file, such as `first-pool.yaml`, with content like the following example: + [source,yaml] @@ -81,8 +83,9 @@ metadata: spec: addresses: - 192.169.10.0/32 +# ... ---- - ++ .. Apply the configuration for the IP address pool by running the following command: + [source,terminal] @@ -91,7 +94,7 @@ $ oc apply -f first-pool.yaml ---- . Create a `BGPAdvertisement` CR: - ++ .. Create a file, such as `first-adv.yaml`, with content like the following example: + [source,yaml] @@ -105,10 +108,11 @@ spec: ipAddressPools: - first-pool peers: - - frrviavrf <1> + - frrviavrf +# ... ---- -<1> In this example, MetalLB advertises a range of IP addresses from the `first-pool` IP address pool to the `frrviavrf` BGP peer. - +`peers.frrviavrf`: In this example, MetalLB advertises a range of IP addresses from the `first-pool` IP address pool to the `frrviavrf` BGP peer. ++ .. Apply the configuration for the BGP advertisement by running the following command: + [source,terminal] @@ -117,7 +121,7 @@ $ oc apply -f first-adv.yaml ---- . Create a `Namespace`, `Deployment`, and `Service` CR: - ++ .. Create a file, such as `deploy-service.yaml`, with content like the following example: + [source,yaml] @@ -162,8 +166,9 @@ spec: selector: app: server type: LoadBalancer +# ... ---- - ++ .. Apply the configuration for the namespace, deployment, and service by running the following command: + [source,terminal] diff --git a/modules/nw-metallb-example-addresspool.adoc b/modules/nw-metallb-example-addresspool.adoc index 7003a7d807..ccb790d5e3 100644 --- a/modules/nw-metallb-example-addresspool.adoc +++ b/modules/nw-metallb-example-addresspool.adoc @@ -6,9 +6,10 @@ [id="nw-metallb-example-addresspool_{context}"] = Example address pool configurations -The following examples show address pool configurations for specific scenarios. +[role="_abstract"] +To precisely allocate IP address ranges for cluster services, configure MetalLB address pools by using Classless Inter-Domain Routing (CIDR) notation or hyphenated bounds. Defining these specific ranges ensures that application workloads receive valid IP assignments that align with your existing network infrastructure requirements. -== Example: IPv4 and CIDR ranges +Example of IPv4 and CIDR ranges:: You can specify a range of IP addresses in classless inter-domain routing (CIDR) notation. You can combine CIDR notation with the notation that uses a hyphen to separate lower and upper bounds. @@ -27,9 +28,9 @@ spec: # ... ---- -== Example: Assign IP addresses +Example of assigning IP addresses:: -You can set the `autoAssign` field to `false` to prevent MetalLB from automatically assigning IP addresses from the address pool. You can then assign a single IP address or multiple IP addresses from an IP address pool. To assign an IP address, append the `/32` CIDR notation to the target IP address in the `spec.addresses` parameter. This setting ensures that only the specific IP address is avilable for assignment, leaving non-reserved IP addresses for application use. +You can set the `autoAssign` parameter to `false` to prevent MetalLB from automatically assigning IP addresses from the address pool. You can then assign a single IP address or multiple IP addresses from an IP address pool. To assign an IP address, append the `/32` CIDR notation to the target IP address in the `spec.addresses` parameter. This setting ensures that only the specific IP address is available for assignment, leaving non-reserved IP addresses for application use. .Example `IPAddressPool` CR that assigns multiple IP addresses [source,yaml] @@ -52,11 +53,11 @@ spec: When you add a service, you can request a specific IP address from the address pool or you can specify the pool name in an annotation to request any IP address from the pool. ==== -== Example: IPv4 and IPv6 addresses +Example of IPv4 and IPv6 addresses:: You can add address pools that use IPv4 and IPv6. You can specify multiple ranges in the `addresses` list, just like several IPv4 examples. -Whether the service is assigned a single IPv4 address, a single IPv6 address, or both is determined by how you add the service. The `spec.ipFamilies` and `spec.ipFamilyPolicy` fields control how IP addresses are assigned to the service. +How the service is assigned to a single IPv4 address, a single IPv6 address, or both is determined by how you add the service. The `spec.ipFamilies` and `spec.ipFamilyPolicy` parameters control how IP addresses are assigned to the service. [source,yaml] ---- @@ -71,9 +72,9 @@ spec: - 2002:2:2::1-2002:2:2::100 # ... ---- -<1> Where `10.0.100.0/28` is the local network IP address followed by the `/28` network prefix. +`spec.addresses`: Where `10.0.100.0/28` is the local network IP address followed by the `/28` network prefix. -== Example: Assign IP address pools to services or namespaces +Example of assigning IP address pools to services or namespaces:: You can assign IP addresses from an `IPAddressPool` to services and namespaces that you specify. @@ -95,14 +96,14 @@ spec: addresses: - 192.168.20.0/24 serviceAllocation: - priority: 50 <1> - namespaces: <2> + priority: 50 + namespaces: - namespace-a - namespace-b - namespaceSelectors: <3> + namespaceSelectors: - matchLabels: zone: east - serviceSelectors: <4> + serviceSelectors: - matchExpressions: - key: security operator: In @@ -110,8 +111,11 @@ spec: - S1 # ... ---- -<1> Assign a priority to the address pool. A lower number indicates a higher priority. -<2> Assign one or more namespaces to the IP address pool in a list format. -<3> Assign one or more namespace labels to the IP address pool by using label selectors in a list format. -<4> Assign one or more service labels to the IP address pool by using label selectors in a list format. + +where: + +`serviceAllocation.priority`:: Assign a priority to the address pool. A lower number indicates a higher priority. +`serviceAllocation.namespaces`:: Assign one or more namespaces to the IP address pool in a list format. +`serviceAllocation.namespaceSelectors`:: Assign one or more namespace labels to the IP address pool by using label selectors in a list format. +`serviceAllocation.serviceSelectors`:: Assign one or more service labels to the IP address pool by using label selectors in a list format. diff --git a/modules/nw-metallb-example-bgppeer.adoc b/modules/nw-metallb-example-bgppeer.adoc index af5c8fd28d..71db22ae37 100644 --- a/modules/nw-metallb-example-bgppeer.adoc +++ b/modules/nw-metallb-example-bgppeer.adoc @@ -2,14 +2,16 @@ // // * networking/metallb/metallb-configure-bgp-peers.adoc -:_mod-docs-content-type: PROCEDURE +:_mod-docs-content-type: REFERENCE [id="nw-metallb-example-bgppeer_{context}"] = Example BGP peer configurations -[id="nw-metallb-example-limit-nodes-bgppeer_{context}"] -== Example: Limit which nodes connect to a BGP peer +[role="_abstract"] +To precisely manage network topology and improve routing resilience, configure MetalLB BGP peer settings that limit node connectivity and incorporate BFD profiles. Defining these parameters ensures that your cluster maintains secure peer relationships and rapidly detects path failures for high service availability. -You can specify the node selectors field to control which nodes can connect to a BGP peer. +Example of limiting which nodes connect to a BGP peer:: + +You can specify the `nodeSelectors` parameter to control which nodes can connect to a BGP peer. [source,yaml] ---- @@ -27,13 +29,12 @@ spec: - key: kubernetes.io/hostname operator: In values: [compute-1.example.com, compute-2.example.com] +# ... ---- -[id="nw-metallb-example-specify-bfd-profile_{context}"] -== Example: Specify a BFD profile for a BGP peer +Example of specifying a BFD profile for a BGP peer:: -You can specify a BFD profile to associate with BGP peers. -BFD compliments BGP by providing more rapid detection of communication failures between peers than BGP alone. +You can specify a BFD profile to associate with BGP peers. BFD complements BGP by providing faster detection of communication failures between peers than BGP alone. [source,yaml] ---- @@ -48,15 +49,16 @@ spec: myASN: 64500 holdTime: "10s" bfdProfile: doc-example-bfd-profile-full +# ... ---- + //Dependency on RHEL bug 2054160 being addressed.Remove note when fixed. [NOTE] ==== Deleting the bidirectional forwarding detection (BFD) profile and removing the `bfdProfile` added to the border gateway protocol (BGP) peer resource does not disable the BFD. Instead, the BGP peer starts using the default BFD profile. To disable BFD from a BGP peer resource, delete the BGP peer configuration and recreate it without a BFD profile. For more information, see link:https://bugzilla.redhat.com/show_bug.cgi?id=2050824[*BZ#2050824*]. ==== -[id="nw-metallb-example-dual-stack_{context}"] -== Example: Specify BGP peers for dual-stack networking +Example of specifying BGP peers for dual-stack networking:: To support dual-stack networking, add one BGP peer custom resource for IPv4 and one BGP peer custom resource for IPv6. @@ -81,12 +83,12 @@ spec: peerAddress: 2620:52:0:88::104 peerASN: 64500 myASN: 64500 +# ... ---- -[id="nw-metallb-example-unnumbered-bgp-peering_{context}"] -== Example: Specify BGP peers for unnumbered BGP peering +Example of specifying BGP peers for unnumbered BGP peering:: -To configure unnumbered BGP peering, specify the interface in the `spec.interface` field by using the following example configuration: +To configure unnumbered BGP peering, specify the interface in the `spec.interface` parameter by using the following example configuration: [source,yaml] ---- @@ -99,12 +101,14 @@ spec: myASN: 64512 ASN: 645000 interface: net0 +# ... ---- + [NOTE] ==== -To use the `interface` field, you must establish a point-to-point, layer 2 connection between the two BGP peers. -You can use unnumbered BGP peering with IPv4, IPv6, or dual-stack, but you must enable IPv6 RAs (Router Advertisements). +To use the `interface` parameter, you must establish a point-to-point layer 2 connection between the two BGP peers. +You can use unnumbered BGP peering with IPv4, IPv6, or dual-stack, but you must enable IPv6 Router Advertisements (RAs). Each interface is limited to one BGP connection. -If you use this field, you cannot specify a value in the `spec.bgp.routers.neighbors.address` field. +If you use this parameter, you cannot specify a value in the `spec.bgp.routers.neighbors.address` parameter. ==== \ No newline at end of file diff --git a/networking/ingress_load_balancing/metallb/metallb-configure-address-pools.adoc b/networking/ingress_load_balancing/metallb/metallb-configure-address-pools.adoc index ce24944694..737ed7f105 100644 --- a/networking/ingress_load_balancing/metallb/metallb-configure-address-pools.adoc +++ b/networking/ingress_load_balancing/metallb/metallb-configure-address-pools.adoc @@ -6,7 +6,10 @@ include::_attributes/common-attributes.adoc[] toc::[] -As a cluster administrator, you can add, modify, and delete address pools. The MetalLB Operator uses the address pool custom resources to set the IP addresses that MetalLB can assign to services. The namespace used in the examples assume the namespace is `metallb-system`. +[role="_abstract"] +To allocate and manage the IP addresses assigned to load balancer services, configure MetalLB address pool custom resources. Defining these pools ensures that application workloads remain reachable through designated network ranges for consistent external access. + +The namespaces used in the examples show `metallb-system` as the namespace. For more information about how to install the MetalLB Operator, see xref:../../../networking/networking_operators/metallb-operator/about-metallb.adoc#about-metallb[About MetalLB and the MetalLB Operator]. @@ -22,8 +25,9 @@ include::modules/nw-metallb-configure-address-pool-vlan.adoc[leveloffset=+1] // Examples include::modules/nw-metallb-example-addresspool.adoc[leveloffset=+1] -[id="next-steps_{context}"] -== Next steps +[id="additional-resources_metallb-configure-address-pools"] +[role="_additional-resources"] +== Additional resources * xref:../../../networking/ingress_load_balancing/metallb/about-advertising-ipaddresspool.adoc#nw-metallb-configure-with-L2-advertisement-label_about-advertising-ip-address-pool[Configuring MetalLB with an L2 advertisement and label] diff --git a/networking/ingress_load_balancing/metallb/metallb-configure-bfd-profiles.adoc b/networking/ingress_load_balancing/metallb/metallb-configure-bfd-profiles.adoc index 3a9dd57ab8..4448989cc6 100644 --- a/networking/ingress_load_balancing/metallb/metallb-configure-bfd-profiles.adoc +++ b/networking/ingress_load_balancing/metallb/metallb-configure-bfd-profiles.adoc @@ -6,8 +6,10 @@ include::_attributes/common-attributes.adoc[] toc::[] -As a cluster administrator, you can add, modify, and delete Bidirectional Forwarding Detection (BFD) profiles. -The MetalLB Operator uses the BFD profile custom resources to identify which BGP sessions use BFD to provide faster path failure detection than BGP alone provides. +[role="_abstract"] +To achieve faster path failure detection for BGP sessions, configure MetalLB Bidirectional Forwarding Detection (BFD) profiles. Establishing these profiles ensures that your network routing remains highly available and responsive by identifying connectivity issues more quickly than standard protocols. + +You can add, modify, and delete BFD profiles. The MetalLB Operator uses the BFD profile custom resources (CRs) to identify the BGP sessions that use BFD. // BFD profile custom resource include::modules/nw-metallb-bfdprofile-cr.adoc[leveloffset=+1] @@ -15,7 +17,8 @@ include::modules/nw-metallb-bfdprofile-cr.adoc[leveloffset=+1] // Add a BFD profile include::modules/nw-metallb-configure-bfdprofle.adoc[leveloffset=+1] -[id="next-steps_{context}"] -== Next steps +[id="additional-resources_metallb-configure-bfd-profiles"] +[role="_additional-resources"] +== Additional resources -* xref:../../../networking/ingress_load_balancing/metallb/metallb-configure-bgp-peers.adoc#metallb-configure-bgp-peers[Configure a BGP peer] to use the BFD profile. +* xref:../../../networking/ingress_load_balancing/metallb/metallb-configure-bgp-peers.adoc#metallb-configure-bgp-peers[Configuring MetalLB BGP peers] diff --git a/networking/ingress_load_balancing/metallb/metallb-configure-bgp-peers.adoc b/networking/ingress_load_balancing/metallb/metallb-configure-bgp-peers.adoc index c2686e02ae..1e04aadf4e 100644 --- a/networking/ingress_load_balancing/metallb/metallb-configure-bgp-peers.adoc +++ b/networking/ingress_load_balancing/metallb/metallb-configure-bgp-peers.adoc @@ -6,13 +6,10 @@ include::_attributes/common-attributes.adoc[] toc::[] -As a cluster administrator, you can add, modify, and delete Border Gateway Protocol (BGP) peers. -The MetalLB Operator uses the BGP peer custom resources to identify which peers that MetalLB `speaker` pods contact to start BGP sessions. -The peers receive the route advertisements for the load-balancer IP addresses that MetalLB assigns to services. +[role="_abstract"] +To establish BGP sessions and advertise routes for load balancer services, configure MetalLB Border Gateway Protocol (BGP) peer custom resources (CRs). Defining these peers ensures that your network infrastructure receives accurate routing information to reach cluster application workloads. -// Dear reviewers and maintainers, I capitalized Autonomous System (AS) -// to match the capitalization that is shown in the common terms section -// of the foll RFC: https://datatracker.ietf.org/doc/html/rfc4271 +You can add, modify, and delete BGP peers. The MetalLB Operator uses the BGP peer custom resources to identify the peers that MetalLB `speaker` pods contact to start BGP sessions. The peers receive the route advertisements for the load-balancer IP addresses that MetalLB assigns to services. // BGP peer custom resource include::modules/nw-metallb-bgppeer-cr.adoc[leveloffset=+1] @@ -27,7 +24,8 @@ include::modules/nw-metallb-configure-specificpools-to-bgppeer.adoc[leveloffset= include::modules/nw-metallb-configure-vrf-bgppeer.adoc[leveloffset=+1] [role="_additional-resources"] -.Additional resources +[id="additional-resources_{context}"] +== Additional resources * xref:../../../networking/multiple_networks/about-virtual-routing-and-forwarding.adoc#cnf-about-virtual-routing-and-forwarding_about-virtual-routing-and-forwarding[About virtual routing and forwarding] @@ -37,10 +35,9 @@ include::modules/nw-metallb-configure-vrf-bgppeer.adoc[leveloffset=+1] * xref:../../../networking/ingress_load_balancing/metallb/metallb-configure-return-traffic.adoc#metallb-configure-return-traffic[Managing symmetric routing with MetalLB] -// Examples include::modules/nw-metallb-example-bgppeer.adoc[leveloffset=+1] -[id="next-steps_{context}"] -== Next steps +[role="_additional-resources"] +== Additional resources * xref:../../../networking/ingress_load_balancing/metallb/metallb-configure-services.adoc#metallb-configure-services[Configuring services to use MetalLB]