Prometheus Metrics

MetalLB exposes different Prometheus metrics that are listed below.

Configuring Prometheus

MetalLB does not bundle a full Prometheus stack. You wire your cluster Prometheus (or the Prometheus Operator) to scrape MetalLB and optionally load alert rules.

Scraping with the Prometheus Operator

Manifests under config/prometheus-native, config/prometheus-frr, and config/prometheus-frr-k8s define ServiceMonitor objects plus metrics Services for the controller and speaker. Combined install overlays also exist under config/manifests/ (for example metallb-native-prometheus.yaml).

Apply the overlay that matches your MetalLB mode, then ensure your Prometheus instance selects the MetalLB ServiceMonitor labels (and that RBAC allows it to read endpoints in the MetalLB namespace).

With Helm, enable scraping via the chart values under prometheus (ServiceMonitor or PodMonitor, scrape annotations, and related settings). See the Helm chart README.

Sample alert rules

Deployments should alert on stale config, failed config load, exhausted address pools, and down BGP sessions. The Helm chart can emit a PrometheusRule when prometheus.prometheusRule.enabled is true. Equivalent expressions you can load into any Prometheus are:

groups:
  - name: metallb
    rules:
      - alert: MetalLBStaleConfig
        expr: metallb_k8s_client_config_stale_bool == 1
        for: 1m
        labels:
          severity: warning
        annotations:
          summary: "MetalLB {{ $labels.pod }} is running on a stale config"

      - alert: MetalLBConfigNotLoaded
        expr: metallb_k8s_client_config_loaded_bool == 0
        for: 1m
        labels:
          severity: critical
        annotations:
          summary: "MetalLB {{ $labels.pod }} has not loaded a config"

      - alert: MetalLBAddressPoolExhausted
        expr: metallb_allocator_addresses_in_use_total >= metallb_allocator_addresses_total
        for: 1m
        labels:
          severity: critical
        annotations:
          summary: "MetalLB pool {{ $labels.pool }} has no free addresses"

      - alert: MetalLBBGPSessionDown
        expr: metallb_bgp_session_up == 0
        for: 1m
        labels:
          severity: critical
        annotations:
          summary: "MetalLB BGP session to {{ $labels.peer }} is down"

Helm users can toggle individual rules and add extraAlerts under prometheus.prometheusRule in chart values. The rule templates live in charts/metallb/templates/prometheusrules.yaml.

MetalLB Allocator Addresses metrics

MetalLB K8S client metrics

MetalLB BGP metrics

These metrics are emitted with the metallb_bgp_ prefix in both native BGP mode (by the speaker) and the deprecated FRR mode (by the FRR metrics sidecar). In the default FRR-K8s mode, the equivalent metrics use the frrk8s_ prefix instead (see FRR-K8s BGP metrics below).

FRR-K8s BGP and BFD metrics

When running in the default FRR-K8s mode, additional BGP and BFD metrics are exposed by the FRR-K8s pods. These metrics use the frrk8s_ prefix and the peer label contains only the peer IP address (without port).

For example:

# HELP frrk8s_bgp_updates_total Number of BGP UPDATE messages sent
# TYPE frrk8s_bgp_updates_total counter
frrk8s_bgp_updates_total{peer="172.23.0.5"} 1
frrk8s_bgp_updates_total{peer="172.23.0.6"} 1
frrk8s_bgp_updates_total{peer="172.30.0.2"} 1
frrk8s_bgp_updates_total{peer="172.30.0.3"} 1

When using BGP with a VRF, an additional label with the name of the VRF is added:

frrk8s_bgp_updates_total{peer="172.23.0.5"} 1
frrk8s_bgp_updates_total{peer="172.23.0.5",vrf="red"} 1

FRR-K8s BGP metrics

FRR-K8s BFD metrics

Backward-compatible metric relabeling

In previous versions of MetalLB, the FRR-based BGP and BFD metrics were exposed with the metallb_ prefix (e.g. metallb_bgp_session_up) and the BGP peer label included the port (e.g. peer="172.23.0.5:179").

If you are migrating from the deprecated FRR mode and need to preserve the metallb_ prefix for compatibility with existing dashboards or alerts, you can configure Prometheus metric relabeling on the FRR-K8s ServiceMonitor to rename the metrics at ingestion time:

metricRelabelings:
- sourceLabels: [__name__]
  regex: "frrk8s_bgp_(.*)"
  targetLabel: "__name__"
  replacement: "metallb_bgp_$1"
- sourceLabels: [__name__]
  regex: "frrk8s_bfd_(.*)"
  targetLabel: "__name__"
  replacement: "metallb_bfd_$1"

When deploying via Helm, this can be configured on the FRR-K8s subchart’s ServiceMonitor (see the commented example in values.yaml). When deploying via kustomize, the config/prometheus-frr-k8s overlay includes these relabeling rules.