diff --git a/docs/metallb.md b/docs/metallb.md
index faeb351ac..a750641d2 100644
--- a/docs/metallb.md
+++ b/docs/metallb.md
@@ -14,7 +14,7 @@ kube_proxy_strict_arp: true
 
 ## Install
 
-You have to explicitly enable the MetalLB extension and set an IP address range from which to allocate LoadBalancer IPs.
+You have to explicitly enable the MetalLB extension.
 
 ```yaml
 metallb_enabled: true
@@ -38,34 +38,101 @@ metallb_controller_tolerations:
     effect: "NoSchedule"
 ```
 
-## BGP Mode
+## Pools
 
-When operating in BGP Mode MetalLB needs to have defined upstream peers:
+First you need to specify all of the pools you are going to use:
 
 ```yaml
-metallb_protocol: bgp
-metallb_ip_range:
-  - 10.5.0.0/16
-metallb_peers:
-  - peer_address: 192.0.2.1
-    peer_asn: 64512
-    my_asn: 4200000000
-  - peer_address: 192.0.2.2
-    peer_asn: 64513
-    my_asn: 4200000000
+metallb_config:
+
+  address_pools:
+
+    primary:
+      ip_range:
+        - 172.18.113.167-172.18.113.169
+      auto_assign: true
+
+    pool1:
+      ip_range:
+        - 172.18.113.20-172.18.113.39
+        - 172.18.113.120-172.18.113.139
+      auto_assign: false # When set to false, you need to explicitly set the loadBalancerIP in the service!
+
+    pool2:
+      ip_range:
+        - 172.18.113.40-172.18.113.59
+        - 172.18.113.140-172.18.113.159
+      auto_assign: false
 ```
 
-Some upstream BGP peers may require password authentication:
+## Layer2 Mode
+
+Pools that need to be configured in layer2 mode, need to be specified in a list:
 
 ```yaml
-metallb_protocol: bgp
-metallb_ip_range:
-  - 10.5.0.0/16
-metallb_peers:
-  - peer_address: 192.0.2.1
-    peer_asn: 64512
-    my_asn: 4200000000
-    password: "changeme"
+metallb_config:
+
+  layer2:
+    - primary
+```
+
+## BGP Mode
+
+When operating in BGP Mode MetalLB needs to have defined upstream peers and link the pool(s) specified above to the correct peer:
+
+```yaml
+metallb_config:
+
+  layer3:
+    defaults:
+
+      peer_port: 179 # The TCP port to talk to. Defaults to 179, you shouldn't need to set this in production.
+      hold_time: 120s # Requested BGP hold time, per RFC4271.
+      keepalive_time: 120s # Requested BGP keepalive time, per RFC4271.
+
+    communities:
+      vpn-only: "1234:1"
+      NO_ADVERTISE: "65535:65282"
+
+    metallb_peers:
+
+        JRITEST:
+          peer_address: 192.0.2.1
+          peer_asn: 64512
+          my_asn: 4200000000
+          communities:
+            - vpn-only
+          address_pool:
+            - pool1
+
+          # (optional) The source IP address to use when establishing the BGP session. In most cases the source-address field should only be used with per-node peers, i.e. peers with node selectors which select only one node. CURRENTLY NOT SUPPORTED BY US (ACC ICT)
+          source_address: 172.18.113.161
+
+          # (optional) The router ID to use when connecting to this peer. Defaults to the node IP address.
+          # Generally only useful when you need to peer with another BGP router running on the same machine as MetalLB.
+          router_id: 1.2.3.4
+
+          # (optional) Password for TCPMD5 authenticated BGP sessions offered by some peers.
+          password: "changeme"
+
+        JRITEST2:
+          peer_address: 192.0.2.2
+          peer_asn: 64513
+          my_asn: 4200000000
+          communities:
+            - NO_ADVERTISE
+          address_pool:
+            - pool2
+
+          # (optional) The source IP address to use when establishing the BGP session. In most cases the source-address field should only be used with per-node peers, i.e. peers with node selectors which select only one node. CURRENTLY NOT SUPPORTED BY US (ACC ICT)
+          source_address: 172.18.113.162
+
+          # (optional) The router ID to use when connecting to this peer. Defaults to the node IP address.
+          # Generally only useful when you need to peer with another BGP router running on the same machine as MetalLB.
+          router_id: 1.2.3.5
+
+          # (optional) Password for TCPMD5 authenticated BGP sessions offered by some peers.
+          password: "changeme"
 ```
 
 When using calico >= 3.18 you can replace MetalLB speaker by calico Service LoadBalancer IP advertisement.