1. Documentation
×

Installing the MetalLB Operator

As a cluster administrator, you can add the MetallB Operator so that the Operator can manage the lifecycle for an instance of MetalLB on your cluster.

The installation procedures use the metallb-system namespace. You can install the Operator and configure custom resources in a different namespace. The Operator starts MetalLB in the same namespace that the Operator is installed in.

MetalLB and IP failover are incompatible. If you configured IP failover for your cluster, perform the steps to remove IP failover before you install the Operator.

Installing the MetalLB Operator from the OperatorHub using the web console

As a cluster administrator, you can install the MetalLB Operator by using the OKD web console.

Procedure

  1. Log in to the OKD web console.

  2. Optional: Create the required namespace for the MetalLB Operator:

    You can choose to create the namespace at this stage or you can create it when you start the MetalLB Operator install. From the Installed Namespace list you can create the project.

    1. Navigate to Administration → Namespaces and click Create Namespace.

    2. Enter metallb-system in the Name field, and click Create.

  3. Install the MetalLB Operator:

    1. In the OKD web console, click Operators → OperatorHub.

    2. Type metallb into the Filter by keyword field to find the MetalLB Operator, and then click Install.

      You can also filter options by Infrastructure Features. For example, select Disconnected if you want to see Operators that work in disconnected environments, also known as restricted network environments.

    3. On the Install Operator page, select a specific namespace on the cluster. Select the namespace created in the earlier section or choose to create the metallb-system project, and then click Install.

Verification

To verify that the MetalLB Operator installed successfully:

  1. Navigate to the Operators → Installed Operators page.

  2. Ensure that MetalLB Operator is listed in the metallb-system project with a Status of Succeeded.

    During installation, an Operator might display a Failed status. If the installation later succeeds with an Succeeded message, you can ignore the Failed message.

  3. If the Operator installation does not succeed, you can troubleshoot further:

    1. Navigate to the Operators → Installed Operators page and inspect the Operator Subscriptions and Install Plans tabs for any failure or errors under Status.

    2. Navigate to the Workloads → Pods page and check the logs for pods in the metallb-system project.

Installing from OperatorHub using the CLI

Instead of using the OKD web console, you can install an Operator from OperatorHub using the CLI. Use the oc command to create or update a Subscription object.

Prerequisites

  • Install the OpenShift CLI (oc).

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

Procedure

  1. Confirm that the MetalLB Operator is available:

    $ oc get packagemanifests -n openshift-marketplace metallb-operator
    Example output
    NAME               CATALOG                AGE
metallb-operator   Red Hat Operators      9h

  2. Create the metallb-system namespace:

    $ cat << EOF | oc apply -f -
apiVersion: v1
kind: Namespace
metadata:
  name: metallb-system
EOF

  3. Optional: To ensure BGP and BFD metrics appear in Prometheus, you can label the namespace as in the following command:

    $ oc label ns metallb-system "openshift.io/cluster-monitoring=true"

  4. Create an Operator group custom resource in the namespace:

    $ cat << EOF | oc apply -f -
apiVersion: operators.coreos.com/v1
kind: OperatorGroup
metadata:
  name: metallb-operator
  namespace: metallb-system
spec:
  targetNamespaces:
  - metallb-system
EOF

  5. Confirm the Operator group is installed in the namespace:

    $ oc get operatorgroup -n metallb-system
    Example output
    NAME               AGE
metallb-operator   14m

  6. Subscribe to the MetalLB Operator.

    1. Run the following command to get the OKD major and minor version. You use the values to set the channel value in the next step.

      $ OC_VERSION=$(oc version -o yaml | grep openshiftVersion | \
    grep -o '[0-9]*[.][0-9]*' | head -1)

    2. To create a subscription custom resource for the Operator, enter the following command:

      $ cat << EOF| oc apply -f -
apiVersion: operators.coreos.com/v1alpha1
kind: Subscription
metadata:
  name: metallb-operator-sub
  namespace: metallb-system
spec:
  channel: "${OC_VERSION}"
  name: metallb-operator
  source: redhat-operators
  sourceNamespace: openshift-marketplace
EOF

  7. Confirm the install plan is in the namespace:

    $ oc get installplan -n metallb-system
    Example output
    NAME            CSV                                                 APPROVAL    APPROVED
install-wzg94   metallb-operator.4.10.0-nnnnnnnnnnnn   Automatic   true

  8. To verify that the Operator is installed, enter the following command:

    $ oc get clusterserviceversion -n metallb-system \
  -o custom-columns=Name:.metadata.name,Phase:.status.phase
    Example output
    Name                                                Phase
metallb-operator.4.10.0-nnnnnnnnnnnn   Succeeded

Starting MetalLB on your cluster

After you install the Operator, you need to configure a single instance of a MetalLB custom resource. After you configure the custom resource, the Operator starts MetalLB on your cluster.

Prerequisites

  • Install the OpenShift CLI (oc).

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

  • Install the MetalLB Operator.

Procedure

  1. Create a single instance of a MetalLB custom resource:

    $ cat << EOF | oc apply -f -
apiVersion: metallb.io/v1beta1
kind: MetalLB
metadata:
  name: metallb
  namespace: metallb-system
EOF
Verification

Confirm that the deployment for the MetalLB controller and the daemon set for the MetalLB speaker are running.

  1. Check that the deployment for the controller is running:

    $ oc get deployment -n metallb-system controller
    Example output
    NAME         READY   UP-TO-DATE   AVAILABLE   AGE
controller   1/1     1            1           11m

  2. Check that the daemon set for the speaker is running:

    $ oc get daemonset -n metallb-system speaker
    Example output
    NAME      DESIRED   CURRENT   READY   UP-TO-DATE   AVAILABLE   NODE SELECTOR            AGE
speaker   6         6         6       6            6           kubernetes.io/os=linux   18m

    The example output indicates 6 speaker pods. The number of speaker pods in your cluster might differ from the example output. Make sure the output indicates one pod for each node in your cluster.

Limit speaker pods to specific nodes

By default, when you start MetalLB with the MetalLB Operator, the Operator starts an instance of a speaker pod on each node in the cluster. Only the nodes with a speaker pod can advertise a load balancer IP address. You can configure the MetalLB custom resource with a node selector to specify which nodes run the speaker pods.

The most common reason to limit the speaker pods to specific nodes is to ensure that only nodes with network interfaces on specific networks advertise load balancer IP addresses. Only the nodes with a running speaker pod are advertised as destinations of the load balancer IP address.

If you limit the speaker pods to specific nodes and specify local for the external traffic policy of a service, then you must ensure that the application pods for the service are deployed to the same nodes.

Example configuration to limit speaker pods to worker nodes
apiVersion: metallb.io/v1beta1
kind: MetalLB
metadata:
  name: metallb
  namespace: metallb-system
spec:
  nodeSelector:  (1)
    node-role.kubernetes.io/worker: ""
  speakerTolerations:   (2)
  - key: "Example"
    operator: "Exists"
    effect: "NoExecute"
1 The example configuration specifies to assign the speaker pods to worker nodes, but you can specify labels that you assigned to nodes or any valid node selector.
2 In this example configuration, the pod that this toleration is attached to tolerates any taint that matches the key value and effect value using the operator.

After you apply a manifest with the spec.nodeSelector field, you can check the number of pods that the Operator deployed with the oc get daemonset -n metallb-system speaker command. Similarly, you can display the nodes that match your labels with a command like oc get nodes -l node-role.kubernetes.io/worker=.

You can optionally allow the node to control which speaker pods should, or should not, be scheduled on them by using affinity rules. You can also limit these pods by applying a list of tolerations. For more information about affinity rules, taints, and tolerations, see the additional resources.

Additional resources

Next steps