1. Documentation
×

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.

About the address pool custom resource

The fields for the address pool custom resource are described in the following table.

Table 1. MetalLB address pool custom resource
Field 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.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.

spec.protocol

string

Specifies the protocol for announcing the load balancer IP address to peer nodes. Specify layer2 or bgp.

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.

spec.addresses

array

Specifies a list of IP addresses for MetalLB to assign to services. You can specify multiple ranges in a single pool. Specify each range in CIDR notation or as starting and ending IP addresses separated with a hyphen.

spec.bgpAdvertisements

object

Optional: By default, BGP mode advertises each allocated load-balancer IP address to the configured peers with no additional BGP attributes. The peer routers receive one /32 route for each service IP address, with the BGP local preference set to zero and no BGP communities. Use this field to create custom advertisements.

The fields for the bgpAdvertisements object are defined in the following table:

Table 2. BGP advertisements configuration
Field Type Description

aggregationLength

integer

Optional: Specifies the number of bits to include in a 32-bit CIDR mask. To aggregate the routes that the speaker advertises to BGP peers, the mask is applied to the routes for several service IP addresses and the speaker advertises the aggregated route. For example, with an aggregation length of 24, the speaker can aggregate several 10.0.1.x/32 service IP addresses and advertise a single 10.0.1.0/24 route.

aggregationLengthV6

integer

Optional: Specifies the number of bits to include in a 128-bit CIDR mask. For example, with an aggregation length of 124, the speaker can aggregate several fc00:f853:0ccd:e799::x/128 service IP addresses and advertise a single fc00:f853:0ccd:e799::0/124 route.

community

array

Optional: Specifies one or more BGP communities. Each community is specified as two 16-bit values separated by the colon character. Well-known communities must be specified as 16-bit values:

  • NO_EXPORT: 65535:65281

  • NO_ADVERTISE: 65535:65282

  • NO_EXPORT_SUBCONFED: 65535:65283

localPref

integer

Optional: Specifies the local preference for this advertisement. This BGP attribute applies to BGP sessions within the Autonomous System.

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 addresspool.yaml, with content like the following example:

    apiVersion: metallb.io/v1alpha1
kind: AddressPool
metadata:
  namespace: metallb-system
  name: doc-example
spec:
  protocol: layer2
  addresses:
  - 203.0.113.1-203.0.113.10
  - 203.0.113.65-203.0.113.75

  2. Apply the configuration for the address pool:

    $ oc apply -f addresspool.yaml
Verification

  • View the address pool:

    $ oc describe -n metallb-system addresspool doc-example
    Example output
    Name:         doc-example
Namespace:    metallb-system
Labels:       <none>
Annotations:  <none>
API Version:  metallb.io/v1alpha1
Kind:         AddressPool
Metadata:
  ...
Spec:
  Addresses:
    203.0.113.1-203.0.113.10
    203.0.113.65-203.0.113.75
  Auto Assign:  true
  Protocol:     layer2
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.

apiVersion: metallb.io/v1beta1
kind: AddressPool
metadata:
  name: doc-example-cidr
  namespace: metallb-system
spec:
  protocol: layer2
  addresses:
  - 192.168.100.0/24
  - 192.168.200.0/24
  - 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.

apiVersion: metallb.io/v1beta1
kind: AddressPool
metadata:
  name: doc-example-reserved
  namespace: metallb-system
spec:
  protocol: layer2
  addresses:
  - 10.0.100.0/28
  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.

apiVersion: metallb.io/v1beta1
kind: AddressPool
metadata:
  name: doc-example-combined
  namespace: metallb-system
spec:
  protocol: layer2
  addresses:
  - 10.0.100.0/28
  - 2002:2:2::1-2002:2:2::100

Example: Simple address pool with BGP mode

For BGP mode, you must set the protocol field set to bgp. Other address pool custom resource fields, such as autoAssign, also apply to BGP mode.

In the following example, the peer BGP routers receive one 203.0.113.200/32 route and one fc00:f853:ccd:e799::1/128 route for each load-balancer IP address that MetalLB assigns to a service. Because the localPref and communities fields are not specified, the routes are advertised with localPref set to zero and no BGP communities.

apiVersion: metallb.io/v1beta1
kind: AddressPool
metadata:
  name: doc-example-bgp
  namespace: metallb-system
spec:
  protocol: bgp
  addresses:
    - 203.0.113.200/30
    - fc00:f853:ccd:e799::/124

Example: BGP mode with custom advertisement

You can specify sophisticated custom advertisements.

apiVersion: metallb.io/v1beta1
kind: AddressPool
metadata:
  name: doc-example-bgp-adv
  namespace: metallb-system
spec:
  protocol: bgp
  addresses:
    - 203.0.113.200/30
    - fc00:f853:ccd:e799::/124
  bgpAdvertisements:
  - communities:
    - 65535:65282
    aggregationLength: 32
    localPref: 100
  - communities:
    - 8000:800
    aggregationLength: 30
    aggregationLengthV6: 124

In the preceding example, MetalLB assigns IP addresses to load-balancer services in the ranges between 203.0.113.200 and 203.0.113.203 and between fc00:f853:ccd:e799::0 and fc00:f853:ccd:e799::f.

To explain the two BGP advertisements, consider an instance when MetalLB assigns the IP address of 203.0.113.200 to a service. With that IP address as an example, the speaker advertises two routes to BGP peers:

  • 203.0.113.200/32, with localPref set to 100 and the community set to the numeric value of the well-known NO_ADVERTISE community. This specification indicates to the peer routers that they can use this route but they should not propagate information about this route to BGP peers.

  • 203.0.113.200/30, aggregates the load-balancer IP addresses assigned by MetalLB into a single route. MetalLB advertises the aggregated route to BGP peers with the community attribute set to 8000:800. BGP peers propagate the 203.0.113.200/30 route to other BGP peers. When traffic is routed to a node with a speaker, the 203.0.113.200/32 route is used to forward the traffic into the cluster and to a pod that is associated with the service.

As you add more services and MetalLB assigns more load-balancer IP addresses from the pool, peer routers receive one local route, 203.0.113.20x/32, for each service, as well as the 203.0.113.200/30 aggregate route. Each service that you add generates the /30 route, but MetalLB deduplicates the routes to one BGP advertisement before communicating with peer routers.

Next steps