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 from OperatorHub using the web console

You can install and subscribe to an Operator from OperatorHub using the OKD web console.

Procedure

  1. Navigate in the web console to the Operators → OperatorHub page.

  2. Scroll or type a keyword into the Filter by keyword box to find the Operator you want. For example, type metallb to find the MetalLB Operator.

    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. Select the Operator to display additional information.

    Choosing a Community Operator warns that Red Hat does not certify Community Operators; you must acknowledge the warning before continuing.

  4. Read the information about the Operator and click Install.

  5. On the Install Operator page:

    1. Select an Update Channel (if more than one is available).

    2. Select Automatic or Manual approval strategy, as described earlier.

  6. Click Install to make the Operator available to the selected namespaces on this OKD cluster.

    1. If you selected a Manual approval strategy, the upgrade status of the subscription remains Upgrading until you review and approve the install plan.

      After approving on the Install Plan page, the subscription upgrade status moves to Up to date.

    2. If you selected an Automatic approval strategy, the upgrade status should resolve to Up to date without intervention.

  7. After the upgrade status of the subscription is Up to date, select Operators → Installed Operators to verify that the cluster service version (CSV) of the installed Operator eventually shows up. The Status should ultimately resolve to InstallSucceeded in the relevant namespace.

    For the All namespaces…​ installation mode, the status resolves to InstallSucceeded in the openshift-operators namespace, but the status is Copied if you check in other namespaces.

    If it does not:

    1. Check the logs in any pods in the openshift-operators project (or other relevant namespace if A specific namespace…​ installation mode was selected) on the Workloads → Pods page that are reporting issues to troubleshoot further.

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:

    1. $ oc get packagemanifests -n openshift-marketplace metallb-operator

    Example output

    1. NAME               CATALOG                AGE
    2. metallb-operator   Red Hat Operators      9h

  2. Create the metallb-system namespace:

    1. $ cat << EOF | oc apply -f -
    2. apiVersion: v1
    3. kind: Namespace
    4. metadata:
    5.   name: metallb-system
    6. EOF

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

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

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

    1. $ cat << EOF | oc apply -f -
    2. apiVersion: operators.coreos.com/v1
    3. kind: OperatorGroup
    4. metadata:
    5.   name: metallb-operator
    6.   namespace: metallb-system
    7. spec:
    8.   targetNamespaces:
    9.   - metallb-system
    10. EOF

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

    1. $ oc get operatorgroup -n metallb-system

    Example output

    1. NAME               AGE
    2. 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.

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

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

      1. $ cat << EOF| oc apply -f -
      2. apiVersion: operators.coreos.com/v1alpha1
      3. kind: Subscription
      4. metadata:
      5.   name: metallb-operator-sub
      6.   namespace: metallb-system
      7. spec:
      8.   channel: "${OC_VERSION}"
      9.   name: metallb-operator
      10.   source: redhat-operators
      11.   sourceNamespace: openshift-marketplace
      12. EOF

  7. Confirm the install plan is in the namespace:

    1. $ oc get installplan -n metallb-system

    Example output

    1. NAME            CSV                                   APPROVAL    APPROVED
    2. install-wzg94   metallb-operator.4.10.0-nnnnnnnnnnnn   Automatic   true

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

    1. $ oc get clusterserviceversion -n metallb-system \
    2.   -o custom-columns=Name:.metadata.name,Phase:.status.phase

    Example output

    1. Name                                  Phase
    2. 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:

    1. $ cat << EOF | oc apply -f -
    2. apiVersion: metallb.io/v1beta1
    3. kind: MetalLB
    4. metadata:
    5.   name: metallb
    6.   namespace: metallb-system
    7. 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:

    1. $ oc get deployment -n metallb-system controller

    Example output

    1. NAME         READY   UP-TO-DATE   AVAILABLE   AGE
    2. controller   1/1     1            1           11m

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

    1. $ oc get daemonset -n metallb-system speaker

    Example output

    1. NAME      DESIRED   CURRENT   READY   UP-TO-DATE   AVAILABLE   NODE SELECTOR            AGE
    2. 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

  1. apiVersion: metallb.io/v1beta1
  2. kind: MetalLB
  3. metadata:
  4.   name: metallb
  5.   namespace: metallb-system
  6. spec:
  7.   nodeSelector:  (1)
  8.     node-role.kubernetes.io/worker: ""
  9.   speakerTolerations:   (2)
  10.     key: "Example"
  11.     operator: "Exists"
  12.     effect: "NoExecute"
1The 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.
2In 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 applying a list of tolerations. For more information about taints and tolerations, see the additional resources.

Additional resources

Next steps