Merge pull request #55756 from rohennes/TELCODOCS-423-metallb-service-allocation

Adding an example for TELCODOCS-423

Author: stevsmit

modules/nw-metallb-addresspool-cr.adoc

@@ -8,10 +8,10 @@
 
 [NOTE]
 ====
-The address pool custom resource definition (CRD) and API documented in "Load balancing with MetalLB" in {product-title} 4.10 can still be used in {product-version}. However, the enhanced functionality associated with advertising the `IPAddressPools` with layer 2 or the BGP protocol is not supported when using the address pool CRD.   
+The address pool custom resource definition (CRD) and API documented in "Load balancing with MetalLB" in {product-title} 4.10 can still be used in {product-version}. However, the enhanced functionality associated with advertising an IP address from an `IPAddressPool` with layer 2 protocols, or the BGP protocol, is not supported when using the `AddressPool` CRD. 
 ====
 
-The fields for the `IPAddressPool` custom resource are described in the following table.
+The fields for the `IPAddressPool` custom resource are described in the following tables.
 
 .MetalLB IPAddressPool pool custom resource
 [cols="1,1,3a", options="header"]
@@ -49,3 +49,31 @@ Specify `false` if you want explicitly request an IP address from this pool with
 The default value is `true`.
 
 |===
+
+You can assign IP addresses from an `IPAddressPool` to services and namespaces by configuring the `spec.serviceAllocation` specification.
+
+.MetalLB IPAddressPool custom resource spec.serviceAllocation subfields
+[cols="1,1,3a", options="header"]
+|===
+
+|Field
+|Type
+|Description
+
+|`priority`
+|`int`
+|Optional: Defines the priority between IP address pools when more than one IP address pool matches a service or namespace. A lower number indicates a higher priority.
+
+|`namespaces`
+|`array (string)`
+|Optional: Specifies a list of namespaces that you can assign to IP addresses in an IP address pool.
+
+|`namespaceSelectors`
+|`array (LabelSelector)`
+|Optional: Specifies namespace labels that you can assign to IP addresses from an IP address pool by using label selectors in a list format.
+
+|`serviceSelectors`
+|`array (LabelSelector)`
+|Optional: Specifies service labels that you can assign to IP addresses from an address pool by using label selectors in a list format. 
+
+|===

modules/nw-metallb-example-addresspool.adoc

@@ -62,3 +62,44 @@ spec:
   - 10.0.100.0/28
   - 2002:2:2::1-2002:2:2::100
 ----
+
+== 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. 
+
+[NOTE]
+====
+You can use the `matchLabels` label selector, the `matchExpressions` label selector, or both, for the `namespaceSelectors` and `serviceSelectors` specifications. This example demonstrates one label selector for each specification.
+====
+
+[source,yaml]
+----
+apiVersion: metallb.io/v1beta1
+kind: IPAddressPool
+metadata:
+  name: doc-example-service-allocation
+  namespace: metallb-system
+spec:
+  addresses:
+    - 192.168.20.0/24
+  serviceAllocation:
+    priority: 50 <1>
+    namespaces: <2>
+      - namespace-a 
+      - namespace-b
+    namespaceSelectors: <3>
+      - matchLabels:
+          zone: east 
+    serviceSelectors: <4>
+      - matchExpressions: 
+        - key: security 
+          operator: In 
+          values:
+          - 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.
+ 

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

@@ -18,15 +18,15 @@ An `IPAddressPool` includes a list of IP addresses.
 The list can be a single IP address that is set using a range, such as 1.1.1.1-1.1.1.1, a range specified in CIDR notation, a range specified as a starting and ending address separated by a hyphen, or a combination of the three.
 An `IPAddressPool` requires a name.
 The documentation uses names like `doc-example`, `doc-example-reserved`, and `doc-example-ipv6`.
-An `IPAddressPool` assigns IP addresses from the pool.
+The MetalLB `controller` assigns IP addresses from a pool of addresses in an `IPAddressPool`.
 `L2Advertisement` and `BGPAdvertisement` custom resources enable the advertisement of a given IP from a given pool.
+You can assign IP addresses from an `IPAddressPool` to services and namespaces by using the `spec.serviceAllocation` specification in the `IPAddressPool` custom resource.
 +
 [NOTE]
 ====
 A single `IPAddressPool` can be referenced by a L2 advertisement and a BGP advertisement.
 ====
 
-
 `BGPPeer`::
 The BGP peer custom resource identifies the BGP router for MetalLB to communicate with, the AS number of the router, the AS number for MetalLB, and customizations for route advertisement.
 MetalLB advertises the routes for service load-balancer IP addresses to one or more BGP peers.