Skip to content

metallb

Metadata

Field Value
Service metallb
Purpose Allocate and advertise external IPs for Service objects of type LoadBalancer
Criticality Tier 0
Owner Platform / Networking owner
Clusters homelab via legacy prod overlay, local, jls
Namespace metallb-system
Exposure Internal platform service with direct impact on externally reachable IPs
Stateful no
Backup class Git-backed only
RPO / RTO Git state authoritative, 15 to 30 minutes to restore address allocation policy
Last reviewed 2026-04-17

1. Service Overview

MetalLB provides the LoadBalancer implementation for clusters that do not have a cloud-native load balancer. Traefik and any other LoadBalancer services rely on MetalLB to obtain and advertise reachable IP addresses.

Summary

If MetalLB fails, LoadBalancer services remain pending or lose their external reachability. The repository uses a simple pattern per cluster: the upstream MetalLB manifests plus a local config.yaml declaring an IPAddressPool and L2Advertisement.

Dependencies

Dependency Type Why it matters
Layer 2 adjacency on the target network network Advertised addresses must be reachable on the cluster's local network segment
Consumer services such as Traefik runtime consumer LoadBalancer services depend on an available address pool
Kubernetes nodes running speaker pods runtime L2Advertisement depends on the speaker daemonset being healthy on the nodes

2. Architecture Diagram

[Service type LoadBalancer]
  -> [MetalLB controller]
  -> [IPAddressPool selection]
  -> [speaker daemonset announces address via L2Advertisement]
  -> [Traffic reaches the selected node and service]

3. Deployment Specifications

Item Value
Source path metallb/base plus metallb/prod, metallb/layer7, metallb/jls
Deployment model Kustomize
Namespace metallb-system
Workload kind Upstream controller deployment, speaker daemonset, IPAddressPool, L2Advertisement
Chart or image version Base tracks github.com/metallb/metallb/config/native ref v0.15.3, while the legacy prod overlay still pins v0.14.9 directly
Config files base/kustomization.yml, /config.yaml, /kustomization.yml

Cluster mapping

Cluster Overlay path Notes
homelab metallb/prod Legacy overlay using address range 192.168.1.40-192.168.1.89 and upstream ref v0.14.9
local metallb/layer7 Single-address pool 185.55.240.102/32; overlay dir pending rename to local; speaker pinned to node.io/ingress=true (oci-arm)
jls metallb/jls Two-address pool 172.16.8.109/32 and 172.16.8.111/32

4. Configuration Guide

MetalLB configuration is intentionally small and cluster-specific.

Environment variables

Variable Source Purpose Secret?
N/A N/A Upstream manifests own controller runtime configuration no

ConfigMaps

Resource Path Purpose
None in current overlays N/A The repository uses IPAddressPool and L2Advertisement CRs instead of the legacy config ConfigMap

Secrets management

  • Secret names: none in current repository overlays
  • Source of truth: not applicable
  • Rotation trigger: not applicable
  • Recovery note: pool changes are made directly in config.yaml and reapplied through Kustomize

5. Access Protocols

Path URL or endpoint Audience Auth TLS terminates at
Internal Kubernetes API access to IPAddressPool and L2Advertisement resources in metallb-system Platform operators kubeconfig and cluster RBAC Kubernetes API server
External Advertised IPs consumed by LoadBalancer services such as Traefik End users indirectly through consumer services Consumer-service specific Consumer-service specific

6. Operations and Observability

  • Primary health indicators: controller and speaker pods Ready, LoadBalancer services receive external IPs, and IPAddressPool resources remain valid.
  • Dashboards or alerts: service pending events, controller logs, and speaker logs.
  • Log locations: metallb-system controller and speaker pod logs.
  • Known failure modes: address exhaustion, overlapping or invalid pools, speaker scheduling failures, and upstream version skew between the legacy prod overlay and the shared base.

7. Backup and Recovery Notes

  • Backup method: Git is the authoritative record for pool assignments and overlay selection.
  • Restore prerequisites: working cluster networking and node reachability on the advertised L2 segment.
  • Related runbook: ../runbooks/metallb.md

8. Release and Change Notes

  • Current deployed app version: upstream MetalLB native manifests, mostly v0.15.3 except legacy prod.
  • Current chart version: N/A, deployed from upstream native manifests and local CRs.
  • Last significant change: migration to CR-based IPAddressPool and L2Advertisement configuration per cluster.
  • Rollback reference: restore the previous config.yaml and overlay kustomization revision, then reapply the overlay.