MetalLBConfig

Available since 2.24.0 (14.0.1 and 14.0.0) for management clusters

Caution

For managed clusters, this object is available as Technology Preview since Container Cloud 2.24.0 and is generally available since 2.25.0.

This section describes the MetalLBConfig custom resource used in the Container Cloud API that contains the MetalLB configuration objects for a particular cluster.

Note

The MetalLBConfig custom resource described below applies to vSphere-based deployments only. For the bare metal provider, refer to MetalLBConfig for bare metal.

For demonstration purposes, the Container Cloud MetalLBConfig custom resource description is split into the following major sections:

The Container Cloud API also uses the third-party open source MetalLB API. For details, see MetalLB objects.

MetalLBConfig metadata

The Container Cloud MetalLBConfig CR contains the following fields:

  • apiVersion

    API version of the object that is kaas.mirantis.com/v1alpha1.

  • kind

    Object type that is MetalLBConfig.

The metadata object field of the MetalLBConfig resource contains the following fields:

  • name

    Name of the MetalLBConfig object.

  • namespace

    Project in which the object was created. Must match the project name of the target cluster.

  • labels

    Key-value pairs attached to the object. Mandatory labels are:

    • kaas.mirantis.com/provider

      Provider type: vsphere.

    • kaas.mirantis.com/region

      Region name that matches the region name of the target cluster.

      Note

      The kaas.mirantis.com/region label is removed from all Container Cloud objects in 2.26.0 (Cluster releases 17.1.0 and 16.1.0). Therefore, do not add the label starting these releases. On existing clusters updated to these releases, or if manually added, this label will be ignored by Container Cloud.

    • cluster.sigs.k8s.io/cluster-name

      Name of the cluster that the MetalLB configuration must apply to.

    Warning

    Labels and annotations that are not documented in this API Reference are generated automatically by Container Cloud. Do not modify them using the Container Cloud API.

Configuration example:

apiVersion: kaas.mirantis.com/v1alpha1
kind: MetalLBConfig
metadata:
  name: metallb-demo
  namespace: test-ns
  labels:
    kaas.mirantis.com/provider: vsphere
    cluster.sigs.k8s.io/cluster-name: test-cluster

MetalLBConfig spec

The spec field of the MetalLBConfig object represents the MetalLBConfigSpec subresource that contains the description of MetalLB configuration objects. These objects are created in the target cluster during its deployment.

The spec field contains the following optional fields:

  • addressPools

    List of MetalLBAddressPool objects to create MetalLB AddressPool objects.

  • ipAddressPools

    List of MetalLBIPAddressPool objects to create MetalLB IPAddressPool objects.

  • l2Advertisements

    List of MetalLBL2Advertisement objects to create MetalLB L2Advertisement objects.


The objects listed in the spec field of the MetalLBConfig object, such as MetalLBIPAddressPool, MetalLBL2Advertisement, and so on, are used as templates for the MetalLB objects that will be created in the target cluster. Each of these objects has the following structure:

  • labels

    Optional. Key-value pairs attached to the metallb.io/<objectName> object as metadata.labels.

  • name

    Name of the metallb.io/<objectName> object.

  • spec

    Contents of the spec section of the metallb.io/<objectName> object. The spec field has the metallb.io/<objectName>Spec type. For details, see MetalLB objects.

For example, MetalLBIPAddressPool is a template for the metallb.io/IPAddressPool object and has the following structure:

  • labels

    Optional. Key-value pairs attached to the metallb.io/IPAddressPool object as metadata.labels.

  • name

    Name of the metallb.io/IPAddressPool object.

  • spec

    Contents of spec section of the metallb.io/IPAddressPool object. The spec has the metallb.io/IPAddressPoolSpec type.

MetalLB objects

Container Cloud supports the following MetalLB object types of the metallb.io API group:

  • AddressPool

  • IPAddressPool

  • L2Advertisement

As of v1beta1 and v1beta2 API versions, metadata of MetalLB objects has a standard format with no specific fields or labels defined for any particular object:

  • apiVersion

    API version of the object that can be metallb.io/v1beta1 or metallb.io/v1beta2.

  • kind

    Object type that is one of the metallb.io types listed above. For example, AddressPool.

  • metadata

    Object metadata that contains the following subfields:

    • name

      Name of the object.

    • namespace

      Namespace where the MetalLB components are located. It matches metallb-system in Container Cloud.

    • labels

      Optional. Key-value pairs that are attached to the object. It can be an arbitrary set of labels. No special labels are defined as of v1beta1 and v1beta2 API versions.

The MetalLBConfig object contains spec sections of the metallb.io/<objectName> objects that have the metallb.io/<objectName>Spec type. For metallb.io/<objectName> and metallb.io/<objectName>Spec types definitions, refer to the official MetalLB documentation:

MetalLBConfig status

The status field describes the actual state of the object. It contains the following fields:

  • bootstrapMode Only in 2.24.0 (14.0.1 and 14.0.0)

    Field that appears only during a management cluster bootstrap as true and is used internally for bootstrap. Once deployment completes, the value is moved to false and is excluded from the status output.

  • objects

    Description of MetalLB objects taken from spec field and used to create MetalLB native objects in the target cluster.

    The format of the underlying objects is the same as for those in the spec field. These objects have to match the spec contents. Otherwise, an error appears in the status.updateResult field.

  • propagateResult

    Result of objects propagation. During objects propagation, native MetalLB objects of the target cluster are created and updated according to the description of the objects present in the status.objects field.

    This field contains the following information:

    • message

      Text message that describes the result of the last attempt of objects propagation. Contains an error message if the last attempt was unsuccessful.

    • success

      Result of the last attempt of objects propagation. Boolean.

    • time

      Timestamp of the last attempt of objects propagation. For example, 2023-07-04T00:30:36Z.

    If the objects propagation was successful, the MetalLB objects of the target cluster match the ones present in the status.objects field.

  • updateResult

    Status of the MetalLB objects update. Has the same format of subfields that in propagateResult described above.

    During objects update, the status.objects contents are rendered from MetalLBConfig.spec.

    If the objects update was successful, the MetalLB objects description present in status.objects is rendered successfully and up to date. This description is used to update MetalLB objects in the target cluster. If the objects update was not successful, MetalLB objects will not be propagated to the target cluster.

MetalLB configuration examples

Example of configuration template for a managed cluster:

apiVersion: kaas.mirantis.com/v1alpha1
kind: MetalLBConfig
metadata:
  labels:
    cluster.sigs.k8s.io/cluster-name: managed-cluster
    kaas.mirantis.com/provider: vsphere
  name: managed-l2
  namespace: managed-ns
spec:
  ipAddressPools:
    - name: services
      spec:
        addresses:
          - 10.100.91.151-10.100.91.170
        autoAssign: true
        avoidBuggyIPs: false
  l2Advertisements:
    - name: services
      spec:
        ipAddressPools:
        - services

After the object is created and processed by the MetalLB Controller, the status field is added. For example:

status:
  objects:
    ipAddressPools:
    - name: services
      spec:
        addresses:
        - 10.100.100.151-10.100.100.170
        autoAssign: true
        avoidBuggyIPs: false
    l2Advertisements:
      - name: services
        spec:
          ipAddressPools:
          - services
  propagateResult:
    message: Objects were successfully updated
    success: true
    time: "2023-07-04T14:31:40Z"
  updateResult:
    message: Objects were successfully read from MetalLB configuration specification
    success: true
    time: "2023-07-04T14:31:39Z"

Example of native MetalLB objects to be created in the managed-ns/managed-cluster cluster during deployment:

apiVersion: metallb.io/v1beta1
kind: IPAddressPool
metadata:
  name: services
  namespace: metallb-system
spec:
  addresses:
  - 10.100.91.151-10.100.91.170
  autoAssign: true
  avoidBuggyIPs: false
apiVersion: metallb.io/v1beta1
kind: L2Advertisement
metadata:
  name: services
  namespace: metallb-system
spec:
  ipAddressPools:
  - services

See also