MetalLB configuration guidelines for subnets

Note

Consider this section as obsolete since MOSK 24.2 due to the MetalLBConfigTemplate object deprecation. For details, see Deprecation Notes: MetalLBConfigTemplate object.

Caution

This section also applies to the bootstrap procedure of a management cluster with the following difference: instead of creating the Subnet object, add its configuration to ipam-objects.yaml.template located in kaas-bootstrap/templates/bm/.

The Kubernetes Subnet object is created for a management cluster from templates during bootstrap.

Each Subnet object can define either a MetalLB address range or MetalLB address pool. A MetalLB address pool may contain one or several address ranges. The following rules apply to creation of address ranges or pools:

To designate a subnet as a MetalLB address pool or range, use the ipam/SVC-MetalLB label key. Set the label value to "1".
The object must contain the cluster.sigs.k8s.io/<cluster-name> label to reference the name of the target cluster where the MetalLB address pool is used.
You may create multiple subnets with the ipam/SVC-MetalLB label to define multiple IP address ranges or multiple address pools for MetalLB in the cluster.
The IP addresses of the MetalLB address pool are not assigned to the interfaces on hosts. This subnet is virtual. Do not include such subnets to the L2 template definitions for your cluster.
If a Subnet object defines a MetalLB address range, no additional object properties are required.
You can use any number of Subnet objects that define a single MetalLB address range. In this case, all address ranges are aggregated into a single MetalLB L2 address pool named services having the auto-assign policy enabled.
Intersection of IP address ranges within any single MetalLB address pool is not allowed.

The bare-metal provider verifies intersection of IP address ranges. If it detects intersection, the MetalLB configuration is blocked and the provider logs contain corresponding error messages.

Use the following labels to identify the Subnet object as a MetalLB address pool and configure the name and protocol for that address pool. All labels below are mandatory for the Subnet object that configures a MetalLB address pool.

Mandatory Subnet labels for a MetalLB address pool
Label	Description
Labels to link `Subnet` to the target MOSK clusters within a management cluster.	`cluster.sigs.k8s.io/cluster-name` Specifies the cluster name where the MetalLB address pool is used. `kaas.mirantis.com/region` Specifies the region name of the cluster where the MetalLB address pool is used. `kaas.mirantis.com/provider` Specifies the provider of the cluster where the MetalLB address pool is used. Note The `kaas.mirantis.com/region` label is removed from all MOSK objects in 24.1. Therefore, do not add the label starting with this release. On existing clusters updated to this release, or if added manually, MOSK ignores this label.
`ipam/SVC-MetalLB`	Defines that the `Subnet` object will be used to provide a new address pool or range for MetalLB.
`metallb/address-pool-name`	Every address pool must have a distinct name. The `services-pxe` address pool is mandatory when configuring a dedicated PXE network in the management cluster. This name will be used in annotations for services exposed through the PXE network. A bootstrap cluster also uses the `services-pxe` address pool for its provision services so that management cluster nodes can be provisioned from the bootstrap cluster. After a management cluster is deployed, the bootstrap cluster is deleted and that address pool is solely used by the newly deployed cluster.
`metallb/address-pool-auto-assign`	Configures the auto-assign policy of an address pool. Boolean. Caution For the address pools defined using the MetalLB Helm chart values in the `Cluster` `spec` section, auto-assign policy is set to `true` and is not configurable. For any service that does not have a specific MetalLB annotation configured, MetalLB allocates external IPs from arbitrary address pools that have the auto-assign policy set to `true`. Only for the service that has a specific MetalLB annotation with the address pool name, MetalLB allocates external IPs from the address pool having the auto-assign policy set to `false`.
`metallb/address-pool-protocol`	Sets the address pool protocol. The only supported value is `layer2` (default).

Caution

Do not set the same address pool name for two or more Subnet objects. Otherwise, the corresponding MetalLB address pool configuration fails with a warning message in the bare-metal provider log.

Caution

For the auto-assign policy, the following configuration rules apply:

At least one MetalLB address pool must have the auto-assign policy enabled so that unannotated services can have load balancer IPs allocated for them. To satisfy this requirement, either configure one of address pools using the Subnet object with metallb/address-pool-auto-assign: "true" or configure address range(s) using the Subnet object(s) without metallb/address-pool-* labels.
When configuring multiple address pools with the auto-assign policy enabled, keep in mind that it is not determined in advance which pool of those multiple address pools is used to allocate an IP for a particular unannotated service.