Configuring MetalLB address pools

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.

About the IPAddressPool custom resource

The address pool custom resource definition (CRD) and API documented in “Load balancing with MetalLB” in OKD 4.10 can still be used in 4.13. 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 tables.

Table 1. MetalLB IPAddressPool pool custom resource
FieldTypeDescription

metadata.name

string

Specifies the name for the address pool. When you add a service, you can specify this pool name in the metallb.universe.tf/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.

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

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.

spec.autoAssign

boolean

Optional: Specifies whether MetalLB automatically assigns IP addresses from this pool. Specify false if you want explicitly request an IP address from this pool with the metallb.universe.tf/address-pool annotation. The default value is true.

You can assign IP addresses from an IPAddressPool to services and namespaces by configuring the spec.serviceAllocation specification.

Table 2. MetalLB IPAddressPool custom resource spec.serviceAllocation subfields
FieldTypeDescription

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.

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.

Prerequisites

  • Install the OpenShift CLI (oc).

  • Log in as a user with cluster-admin privileges.

Procedure

  1. Create a file, such as ipaddresspool.yaml, with content like the following example:

    1. apiVersion: metallb.io/v1beta1
    2. kind: IPAddressPool
    3. metadata:
    4.   namespace: metallb-system
    5.   name: doc-example
    6.   labels: (1)
    7.     zone: east
    8. spec:
    9.   addresses:
    10.   - 203.0.113.1-203.0.113.10
    11.   - 203.0.113.65-203.0.113.75
    1This label assigned to the IPAddressPool can be referenced by the ipAddressPoolSelectors in the BGPAdvertisement CRD to associate the IPAddressPool with the advertisement.

  2. Apply the configuration for the IP address pool:

    1. $ oc apply -f ipaddresspool.yaml

Verification

  • View the address pool:

    1. $ oc describe -n metallb-system IPAddressPool doc-example

    Example output

    1. Name:         doc-example
    2. Namespace:    metallb-system
    3. Labels:       zone=east
    4. Annotations:  <none>
    5. API Version:  metallb.io/v1beta1
    6. Kind:         IPAddressPool
    7. Metadata:
    8.   ...
    9. Spec:
    10.   Addresses:
    11.     203.0.113.1-203.0.113.10
    12.     203.0.113.65-203.0.113.75
    13.   Auto Assign:  true
    14. Events:         <none>

Confirm that the address pool name, such as doc-example, and the IP address ranges appear in the output.

Example address pool configurations

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.

  1. apiVersion: metallb.io/v1beta1
  2. kind: IPAddressPool
  3. metadata:
  4.   name: doc-example-cidr
  5.   namespace: metallb-system
  6. spec:
  7.   addresses:
  8.   - 192.168.100.0/24
  9.   - 192.168.200.0/24
  10.   - 192.168.255.1-192.168.255.5

Example: Reserve 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.

  1. apiVersion: metallb.io/v1beta1
  2. kind: IPAddressPool
  3. metadata:
  4.   name: doc-example-reserved
  5.   namespace: metallb-system
  6. spec:
  7.   addresses:
  8.   - 10.0.100.0/28
  9.   autoAssign: false

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.

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.

  1. apiVersion: metallb.io/v1beta1
  2. kind: IPAddressPool
  3. metadata:
  4.   name: doc-example-combined
  5.   namespace: metallb-system
  6. spec:
  7.   addresses:
  8.   - 10.0.100.0/28
  9.   - 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.

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.

  1. apiVersion: metallb.io/v1beta1
  2. kind: IPAddressPool
  3. metadata:
  4.   name: doc-example-service-allocation
  5.   namespace: metallb-system
  6. spec:
  7.   addresses:
  8.     - 192.168.20.0/24
  9.   serviceAllocation:
  10.     priority: 50 (1)
  11.     namespaces: (2)
  12.       - namespace-a
  13.       - namespace-b
  14.     namespaceSelectors: (3)
  15.       - matchLabels:
  16.           zone: east
  17.     serviceSelectors: (4)
  18.       - matchExpressions:
  19.         - key: security
  20.           operator: In
  21.           values:
  22.           - S1
1Assign a priority to the address pool. A lower number indicates a higher priority.
2Assign one or more namespaces to the IP address pool in a list format.
3Assign one or more namespace labels to the IP address pool by using label selectors in a list format.
4Assign one or more service labels to the IP address pool by using label selectors in a list format.

Additional resources

Next steps