Setting up MetalLB can fSetting up MetalLB can feel like venturing into uncharted waters, but don’t worry—this guide breaks it all down step by step. By the end, you’ll have a fully functional load balancer for your Kubernetes cluster. Whether you’re a seasoned Kubernetes pro or just getting started, this tutorial has everything you need.tutorial has everything you need.
What is MetalLB?
MetalLB is a network load balancer specifically designed for bare-metal Kubernetes clusters. It provides an elegant solution for a common problem: how to expose services externally in environments where traditional cloud load balancers aren’t available. MetalLB bridges this gap by assigning IP addresses to services and routing external traffic to them.
Unlike cloud-managed Kubernetes clusters, which offer built-in load balancers, bare-metal setups need a tool like MetalLB to handle load-balancing duties. MetalLB operates at layer 2 (ARP/NDP) or layer 3 (BGP), making it flexible enough to integrate into most network environments.
Getting Ready to Install MetalLB
Before diving into the installation, you need to ensure your Kubernetes cluster is ready. Here’s a quick checklist:
- A Fully Functional Kubernetes Cluster
- Make sure your cluster is up and running. Tools like Minikube, kubeadm, or a managed solution (without built-in load balancing) are good starting points.
- Access to kubectl
- Confirm that kubectl is installed and configured to interact with your cluster.
- Cluster Network Configuration
- MetalLB works best when you understand your network setup. Decide whether you’ll use Layer 2 (for simple setups) or BGP (for advanced routing).
- An Available IP Range
- Reserve a range of IP addresses on your network to assign to services. This range should not overlap with other devices on your network.
Installing MetalLB Step by Step
Here’s how you can install MetalLB on your Kubernetes cluster.

Applying the Manifest File
The simplest way to install MetalLB is by applying its official manifest. Run the following command:
bash
Copy code
kubectl apply -f https://raw.githubusercontent.com/metallb/metallb/main/manifests/metallb.yaml
This command downloads and applies MetalLB’s configuration files to your cluster. It sets up the necessary custom resource definitions (CRDs), controllers, and daemons.
Configuring IP Address Pools
Next, you need to define the IP address pool that MetalLB will use to assign addresses. Create a configuration file named metallb-config.yaml:
In this example, the IP range 192.168.1.100-192.168.1.200 is reserved for load-balanced services. Customize it according to your network.
Verifying the Installation
To confirm that MetalLB is working correctly, check the status of the MetalLB pods:
bash
Copy code
kubectl get pods -n metallb-system
All pods should be in a Running state. If there are issues, review the logs:
bash
Copy code
kubectl logs -n metallb-system pod-name
Creating a LoadBalancer Service
With MetalLB installed, you can now expose a service using the LoadBalancer type. For example, let’s expose an NGINX deployment:
MetalLB assigns an external IP address from the reserved range to your service. Access the service via this IP address in your browser.
Testing Your Setup
Testing ensures that everything works as expected. Open your browser and navigate to the assigned IP address. You should see the default NGINX welcome page.
For more advanced testing, try deploying a web application and exposing it using MetalLB. Use tools like curl or browser-based testing to confirm external access.
Troubleshooting Common Issues
Even the best plans can hit snags. Here’s how to tackle common MetalLB problems.

External IP Pending
If the external IP stays in the Pending state, check the following:
- Ensure the MetalLB controller is running:
- bash
- Copy code
- kubectl get pods -n metallb-system
- Verify your metallb-config.yaml file for errors, particularly the IP range.
Connectivity Problems
If you can’t access your service, consider these steps:
- Confirm that the service is listening on the correct IP and port. Use:
- bash
- Copy code
- kubectl describe service service-name
- Ensure there are no firewall rules blocking the traffic.
- Test from another device on the same network to rule out client-side issues.
Wrapping Up
If issues persist, consult the MetalLB documentation or reach out to the Kubernetes community for support.
Additional Resources
For more information, consider exploring the following:
- MetalLB Official Documentation
- Kubernetes Networking Guide
- NGINX on Kubernetes
These resources provide deeper insights and examples to help you optimize your setup.
The Bottom Line
Installing MetalLB is a straightforward process, but its impact is significant. By adding load-balancing capabilities to your bare-metal Kubernetes cluster, you unlock the full potential of your applications. Follow the steps outlined here, and you’ll have a robust load balancer in no time.