This section describe examples on how to use a Kairos bundle to deploy MetalLB on top of K3s

Welcome to the guide on setting up MetalLB on a Kairos cluster with K3s! This tutorial will walk you through the steps of using a Kairos bundle to automatically configure MetalLB on your local network with an IP range of Check out the MetalLB example to configure it without a bundle.

For those unfamiliar with MetalLB, it is an open-source load balancer implementation for bare metal Kubernetes clusters that utilizes standard routing protocols. When used with K3s on Kairos, it provides load balancing capabilities and helps manage IP addresses within a cluster.


Before we begin, you will need to have the following:

  1. A Kairos standard image which includes K3s
  2. A baremetal node to run the installation


  1. Follow the Installation documentation for Kairos.
  2. Use the following cloud configuration file when setting up Kairos:

hostname: metal-{{ trunc 4 .MachineID }}
- name: kairos
  # Change to your pass here
  passwd: kairos
  # Replace with your github user and un-comment the line below:
  # - github:mudler

  enabled: true
  - --disable=traefik,servicelb

# Specify the bundle to use
- targets:
  - run://quay.io/kairos/community-bundles:metallb_latest

# Specify metallb settings, available only with the bundle.
  version: 0.13.7

There are a few key points to note in the configuration file:

  • The metallb block is provided by the MetalLB bundle and allows us to specify the version of MetalLB that we want to deploy, as well as the address_pool available for our services.
  • The bundles block enables the run bundle type. The bundle we are using is part of the community-bundles repository.

And that’s it! With these steps, you should now have MetalLB configured and ready to use on your Kairos cluster. If you have any questions or run into any issues, don’t hesitate to check out the bundle documentation or reach out to the community for support.

Last modified February 23, 2024: Reduce sizes and remove warnings (0e183ae)