mikrolb

MikroLB

MikroLB is a Kubernetes controller that turns a MikroTik RouterOS v7 device into a LoadBalancer provider for your cluster. It allocates external IPs from cluster-scoped pools and programs the router (load balancing rules, optional SNAT, and address advertisement) through the RouterOS HTTPS REST API.

Full documentation lives at mikrolb.de.

Features

• Kubernetes-native — manage address pools and allocations via CRDs (IPPool, IPAllocation)
• RouterOS v7 support — programs load balancing and SNAT through the HTTPS REST API
• Dual-stack — separate IPv4 and IPv6 pools, combined per Service
• Flexible allocation — auto-assign from a pool, request a pool by name, or pin specific IPs via annotations
• Secure by default — Secret-based configuration with optional custom CA support

How It Works

1. You create one or more IPPool resources describing the IPv4/IPv6 ranges MikroLB may hand out.
2. A user creates a LoadBalancer Service with loadBalancerClass: mikrolb.de/controller (or relies on the default class).
3. MikroLB allocates an address (tracked as an IPAllocation), programs the corresponding load balancing rules on the RouterOS device, and optionally configures SNAT and interface advertisement.

Prerequisites

• Kubernetes cluster (v1.25+)
• cert-manager installed
• kubectl with Kustomize support
• MikroTik device
  • RouterOS v7
  • HTTPS REST API enabled (and reachable from the cluster)
  • can route cluster Pod-CIDRs (e.g. via BGP-peering)

Quick Start

Prepare a RouterOS user with read,write,rest-api policy (see Installation for details), then deploy the controller:

kubectl create namespace mikrolb-system

kubectl -n mikrolb-system create secret generic mikrolb-config \
  --from-literal=ROUTEROS_URL="https://router.example.net" \
  --from-literal=ROUTEROS_USERNAME="mikrolb" \
  --from-literal=ROUTEROS_PASSWORD="change-me" \
  --from-file=ROUTEROS_CA_CERT=./router-ca.crt

kubectl apply -k https://github.com/gerolf-vent/mikrolb/config/default

You might have to adjust the order of firewall rules in RouterOS after MikroLB has run at least once (see Installation for details).

Create an IP pool:

apiVersion: mikrolb.de/v1alpha1
kind: IPPool
metadata:
  name: external-v4
spec:
  ipFamily: IPv4
  addresses:
    - 192.0.2.10-192.0.2.25
  autoAssign: true
  advertise: true
  interfaceName: ether1

Then expose a workload:

apiVersion: v1
kind: Service
metadata:
  name: demo
  annotations:
    mikrolb.de/load-balancer-pools: external-v4
    mikrolb.de/snat-ips: use-lb-ips
spec:
  type: LoadBalancer
  loadBalancerClass: mikrolb.de/controller
  selector:
    app: demo
  ports:
    - port: 80
      targetPort: 8080

Configuration

The controller is configured entirely through environment variables (typically supplied by the mikrolb-config Secret). The most important ones:

See the configuration reference for the complete list.

Documentation

• Getting Started
• Installation
• IP Pools
• Services
• Debugging IPAllocations
• API Reference
• Annotation Reference

License

Licensed under the Apache License 2.0.