Installation

Before starting with installation, make sure you meet all the requirements. In particular, you should pay attention to network addon compatibility.

If you’re trying to run MetalLB on a cloud platform, you should also look at the cloud compatibility page and make sure your cloud platform can work with MetalLB (most cannot).

There are three supported ways to install MetalLB: using plain Kubernetes manifests, using Kustomize, or using Helm.

Preparation

If you’re using kube-proxy in IPVS mode, since Kubernetes v1.14.2 you have to enable strict ARP mode.

Note, you don’t need this if you’re using kube-router as service-proxy because it is enabling strict ARP by default.

You can achieve this by editing kube-proxy config in current cluster:

kubectl edit configmap -n kube-system kube-proxy

and set:

apiVersion: kubeproxy.config.k8s.io/v1alpha1
kind: KubeProxyConfiguration
mode: "ipvs"
ipvs:
  strictARP: true

You can also add this configuration snippet to your kubeadm-config, just append it with --- after the main configuration.

If you are trying to automate this change, these shell snippets may help you:

# see what changes would be made, returns nonzero returncode if different
kubectl get configmap kube-proxy -n kube-system -o yaml | \
sed -e "s/strictARP: false/strictARP: true/" | \
kubectl diff -f - -n kube-system

# actually apply the changes, returns nonzero returncode on errors only
kubectl get configmap kube-proxy -n kube-system -o yaml | \
sed -e "s/strictARP: false/strictARP: true/" | \
kubectl apply -f - -n kube-system

Installation by manifest

MetalLB offers different manifests depending on which BGP backend you need. Choose the one that fits your deployment:

FRR-K8s mode (recommended) – includes the FRR-K8s backend, which provides BGP with BFD support, IPv6, and the ability to merge additional FRR configuration:

kubectl apply -f https://raw.githubusercontent.com/metallb/metallb/v0.16.0/config/manifests/metallb-frr-k8s.yaml

Native mode – a lightweight deployment with the built-in native BGP implementation (no BFD, no IPv6 BGP). Suitable for L2-only or simple BGP setups:

kubectl apply -f https://raw.githubusercontent.com/metallb/metallb/v0.16.0/config/manifests/metallb-native.yaml

FRR mode (deprecated) – configures FRR directly without the FRR-K8s layer. Migrate to FRR-K8s mode instead:

kubectl apply -f https://raw.githubusercontent.com/metallb/metallb/v0.16.0/config/manifests/metallb-frr.yaml

This will deploy MetalLB to your cluster, under the metallb-system namespace. The components in the manifest are:

• The metallb-system/controller deployment. This is the cluster-wide controller that handles IP address assignments.
• The metallb-system/speaker daemonset. This is the component that speaks the protocol(s) of your choice to make the services reachable.
• Service accounts for the controller and speaker, along with the RBAC permissions that the components need to function.

The installation manifest does not include a configuration file. MetalLB’s components will still start, but will remain idle until you start deploying resources.

There are also two all-in-one manifests to allow the integration with prometheus. They assume that the prometheus operator is deployed in the monitoring namespace using the prometheus-k8s service account. It is suggested to use either the charts or kustomize if they need to be changed.

Installation with kustomize

You can install MetalLB with Kustomize by pointing at the remote kustomization file.

To deploy with the FRR-K8s mode (recommended):

# kustomization.yml
namespace: metallb-system

resources:
  - github.com/metallb/metallb/config/frr-k8s?ref=main

To deploy with the native BGP implementation:

# kustomization.yml
namespace: metallb-system

resources:
  - github.com/metallb/metallb/config/native?ref=v0.16.0

To deploy with the FRR mode (deprecated):

# kustomization.yml
namespace: metallb-system

resources:
  - github.com/metallb/metallb/config/frr?ref=v0.16.0

Installation with Helm

You can install MetalLB with Helm by using the Helm chart repository: https://metallb.github.io/metallb

helm repo add metallb https://metallb.github.io/metallb
helm install metallb metallb/metallb

A values file may be specified on installation. This is recommended for providing configs in Helm values:

helm install metallb metallb/metallb -f values.yaml

  labels:
    pod-security.kubernetes.io/enforce: privileged
    pod-security.kubernetes.io/audit: privileged
    pod-security.kubernetes.io/warn: privileged

speaker:
  frr:
    enabled: true
frrk8s:
  enabled: false

speaker:
  frr:
    enabled: false
frrk8s:
  enabled: false

Using the MetalLB Operator

The MetalLB Operator is available on OperatorHub at operatorhub.io/operator/metallb-operator. It eases the deployment and life-cycle of MetalLB in a cluster and allows configuring MetalLB via CRDs.

kubectl edit csv metallb-operator

- name: METALLB_BGP_TYPE
  value: frr-k8s

- name: METALLB_BGP_TYPE
  value: frr

FRR daemons logging level

The FRR daemons logging level are configured using the speaker --log-level argument following the below mapping:

To override this behavior, you can set the FRR_LOGGING_LEVEL speaker’s environment to any FRR supported value.

Upgrade

When upgrading MetalLB, always check the release notes to see the changes and required actions, if any. Pay special attention to the release notes when upgrading to newer major/minor releases.

Unless specified otherwise in the release notes, upgrade MetalLB using one of the methods described above:

• Plain manifests
• Kustomize
• Helm

When upgrading via Helm, note that the chart is designed to automatically upgrade the CRDs; there is no need to upgrade them manually.

speaker:
  frr:
    enabled: true
frrk8s:
  enabled: false

Please take the known limitations for layer2 and bgp into account when performing an upgrade.

Setting the LoadBalancer Class

MetalLB supports LoadBalancerClass, which allows multiple load balancer implementations to co-exist. In order to set the loadbalancer class MetalLB should be listening for, the --lb-class=<CLASS_NAME> parameter must be provided to both the speaker and the controller.

The helm charts support it via the loadBalancerClass parameter.