Merge pull request #89196 from dfitzmau/OCPBUGS-51188

OCPBUGS#51188: Added note to metallb doc about single IP address

Author: dfitzmau

modules/nw-metallb-addresspool-cr.adoc

@@ -45,7 +45,7 @@ The default value is `true`.
 
 |`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: 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`.
 
 |===
 

modules/nw-metallb-configure-address-pool.adoc

@@ -7,7 +7,6 @@ As a cluster administrator, you can add address pools to your cluster to control
 .Prerequisites
 
 * Install the OpenShift CLI (`oc`).
-
 * Log in as a user with `cluster-admin` privileges.
 
 .Procedure
@@ -27,6 +26,7 @@ spec:
   addresses:
   - 203.0.113.1-203.0.113.10
   - 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.
 
@@ -39,7 +39,7 @@ $ oc apply -f ipaddresspool.yaml
 
 .Verification
 
-* View the address pool:
+. View the address pool by entering the following command:
 +
 [source,terminal]
 ----
@@ -65,4 +65,4 @@ Spec:
 Events:         <none>
 ----
 
-Confirm that the address pool name, such as `doc-example`, and the IP address ranges appear in the output.
+. Confirm that the address pool name, such as `doc-example`, and the IP address ranges exist in the output.

modules/nw-metallb-example-addresspool.adoc

@@ -2,13 +2,15 @@
 //
 // * networking/metallb/metallb-configure-address-pools.adoc
 
+:_mod-docs-content-type: REFERENCE
 [id="nw-metallb-example-addresspool_{context}"]
 = Example address pool configurations
 
+The following examples show address pool configurations for specific scenarios.
+
 == Example: IPv4 and CIDR ranges
 
-You can specify a range of IP addresses in CIDR notation.
-You can combine CIDR notation with the notation that uses a hyphen to separate lower and upper bounds.
+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.
 
 [source,yaml]
 ----
@@ -22,13 +24,14 @@ spec:
   - 192.168.100.0/24
   - 192.168.200.0/24
   - 192.168.255.1-192.168.255.5
+# ...
 ----
 
-== Example: Reserve IP addresses
+== Example: Assign IP addresses
 
-You can set the `autoAssign` field to `false` to prevent MetalLB from automatically assigning the IP addresses from the pool.
-When you add a service, you can request a specific IP address from the pool or you can specify the pool name in an annotation to request any IP address from the pool.
+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.
 
+.Example `IPAddressPool` CR that assigns multiple IP addresses
 [source,yaml]
 ----
 apiVersion: metallb.io/v1beta1
@@ -38,17 +41,22 @@ metadata:
   namespace: metallb-system
 spec:
   addresses:
-  - 10.0.100.0/28
+  - 192.168.100.1/32
+  - 192.168.200.1/32
   autoAssign: false
+# ...
 ----
 
+[NOTE]
+====
+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
 
-You can add address pools that use IPv4 and IPv6.
-You can specify multiple ranges in the `addresses` list, just like several IPv4 examples.
+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.
+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.
 
 [source,yaml]
 ----
@@ -59,11 +67,14 @@ metadata:
   namespace: metallb-system
 spec:
   addresses:
-  - 10.0.100.0/28
+  - 10.0.100.0/28 <1>
   - 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.
 
 == Example: Assign IP address pools to services or namespaces
+
 You can assign IP addresses from an `IPAddressPool` to services and namespaces that you specify.
 
 If you assign a service or namespace to more than one IP address pool, MetalLB uses an available IP address from the higher-priority IP address pool. If no IP addresses are available from the assigned IP address pools with a high priority, MetalLB uses available IP addresses from an IP address pool with lower priority or no priority. 
@@ -96,7 +107,8 @@ spec:
         - key: security 
           operator: In 
           values:
-          - S1 
+          - 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.