XTesting/kubespray/docs/metallb.md

   1 # MetalLB
   2
   3 MetalLB hooks into your Kubernetes cluster, and provides a network load-balancer implementation.
   4 It allows you to create Kubernetes services of type "LoadBalancer" in clusters that don't run on a cloud provider, and thus cannot simply hook into 3rd party products to provide load-balancers.
   5 The default operationg mode of MetalLB is in ["Layer2"](https://metallb.universe.tf/concepts/layer2/) but it can also operate in ["BGP"](https://metallb.universe.tf/concepts/bgp/) mode.
   6
   7 ## Prerequisites
   8
   9 You have to configure arp_ignore and arp_announce to avoid answering ARP queries from kube-ipvs0 interface for MetalLB to work.
  10
  11 ```yaml
  12 kube_proxy_strict_arp: true
  13 ```
  14
  15 ## Install
  16
  17 You have to explicitly enable the MetalLB extension and set an IP address range from which to allocate LoadBalancer IPs.
  18
  19 ```yaml
  20 metallb_enabled: true
  21 metallb_speaker_enabled: true
  22 metallb_avoid_buggy_ips: true
  23 metallb_ip_range:
  24   - 10.5.0.0/16
  25 ```
  26
  27 By default only the MetalLB BGP speaker is allowed to run on control plane nodes. If you have a single node cluster or a cluster where control plane are also worker nodes you may need to enable tolerations for the MetalLB controller:
  28
  29 ```yaml
  30 metallb_controller_tolerations:
  31   - key: "node-role.kubernetes.io/master"
  32     operator: "Equal"
  33     value: ""
  34     effect: "NoSchedule"
  35   - key: "node-role.kubernetes.io/control-plane"
  36     operator: "Equal"
  37     value: ""
  38     effect: "NoSchedule"
  39 ```
  40
  41 ## BGP Mode
  42
  43 When operating in BGP Mode MetalLB needs to have defined upstream peers:
  44
  45 ```yaml
  46 metallb_protocol: bgp
  47 metallb_ip_range:
  48   - 10.5.0.0/16
  49 metallb_peers:
  50   - peer_address: 192.0.2.1
  51     peer_asn: 64512
  52     my_asn: 4200000000
  53   - peer_address: 192.0.2.2
  54     peer_asn: 64513
  55     my_asn: 4200000000
  56 ```
  57
  58 Some upstream BGP peers may require password authentication:
  59
  60 ```yaml
  61 metallb_protocol: bgp
  62 metallb_ip_range:
  63   - 10.5.0.0/16
  64 metallb_peers:
  65   - peer_address: 192.0.2.1
  66     peer_asn: 64512
  67     my_asn: 4200000000
  68     password: "changeme"
  69 ```
  70
  71 When using calico >= 3.18 you can replace MetalLB speaker by calico Service LoadBalancer IP advertisement.
  72 See [calico service IPs advertisement documentation](https://docs.projectcalico.org/archive/v3.18/networking/advertise-service-ips#advertise-service-load-balancer-ip-addresses).
  73 In this scenarion you should disable the MetalLB speaker and configure the `calico_advertise_service_loadbalancer_ips` to match your `metallb_ip_range`
  74
  75 ```yaml
  76 metallb_speaker_enabled: false
  77 metallb_avoid_buggy_ips: true
  78 metallb_ip_range:
  79   - 10.5.0.0/16
  80 calico_advertise_service_loadbalancer_ips: "{{ metallb_ip_range }}"
  81 ```
  82
  83 If you have additional loadbalancer IP pool in `metallb_additional_address_pools` , ensure to add them to the list.
  84
  85 ```yaml
  86 metallb_speaker_enabled: false
  87 metallb_ip_range:
  88   - 10.5.0.0/16
  89 metallb_additional_address_pools:
  90   kube_service_pool_1:
  91     ip_range:
  92       - 10.6.0.0/16
  93     protocol: "bgp"
  94     auto_assign: false
  95     avoid_buggy_ips: true
  96   kube_service_pool_2:
  97     ip_range:
  98       - 10.10.0.0/16
  99     protocol: "bgp"
 100     auto_assign: false
 101     avoid_buggy_ips: true
 102 calico_advertise_service_loadbalancer_ips:
 103   - 10.5.0.0/16
 104   - 10.6.0.0/16
 105   - 10.10.0.0/16
 106 ```