src/plugins/lb/lb_plugin_doc.md

   1 # Load Balancer plugin for VPP    {#lb_plugin_doc}
   2
   3 ## Version
   4
   5 The load balancer plugin is currently in *beta* version.
   6 Both CLIs and APIs are subject to *heavy* changes.
   7 Wich also means feedback is really welcome regarding features, apis, etc...
   8
   9 ## Overview
  10
  11 This plugin provides load balancing for VPP in a way that is largely inspired
  12 from Google's MagLev: http://research.google.com/pubs/pub44824.html
  13
  14 The load balancer is configured with a set of Virtual IPs (VIP, which can be
  15 prefixes), and for each VIP, with a set of Application Server addresses (ASs).
  16
  17 There are four encap types to steer traffic to different ASs:
  18 1). IPv4+GRE ad IPv6+GRE encap types:
  19 Traffic received for a given VIP (or VIP prefix) is tunneled using GRE towards
  20 the different ASs in a way that (tries to) ensure that a given session will
  21 always be tunneled to the same AS.
  22
  23 2). IPv4+L3DSR encap types:
  24 L3DSR is used to overcome Layer 2 limitations of Direct Server Return Load Balancing.
  25 It maps VIP to DSCP bits, and reuse TOS bits to transfer DSCP bits
  26 to server, and then server will get VIP from DSCP-to-VIP mapping.
  27
  28 Both VIPs or ASs can be IPv4 or IPv6, but for a given VIP, all ASs must be using
  29 the same encap. type (i.e. IPv4+GRE or IPv6+GRE or IPv4+L3DSR).
  30 Meaning that for a given VIP, all AS addresses must be of the same family.
  31
  32 3). IPv4/IPv6 + NAT4/NAT6 encap types:
  33 This type provides kube-proxy data plane on user space,
  34 which is used to replace linux kernal's kube-proxy based on iptables.
  35
  36 Currently, load balancer plugin supports three service types:
  37 a) Cluster IP plus Port: support any protocols, including TCP, UDP.
  38 b) Node IP plus Node Port: currently only support UDP.
  39 c) External Load Balancer.
  40
  41 For Cluster IP plus Port case:
  42 kube-proxy is configured with a set of Virtual IPs (VIP, which can be
  43 prefixes), and for each VIP, with a set of AS addresses (ASs).
  44
  45 For a specific session received for a given VIP (or VIP prefix),
  46 first packet selects a AS according to internal load balancing algorithm,
  47 then does DNAT operation and sent to chosen AS.
  48 At the same time, will create a session entry to store AS chosen result.
  49 Following packets for that session will look up session table first,
  50 which ensures that a given session will always be routed to the same AS.
  51
  52 For returned packet from AS, it will do SNAT operation and sent out.
  53
  54 Please refer to below for details:
  55 https://schd.ws/hosted_files/ossna2017/1e/VPP_K8S_GTPU_OSSNA.pdf
  56
  57
  58 ## Performances
  59
  60 The load balancer has been tested up to 1 millions flows and still forwards more
  61 than 3Mpps per core in such circumstances.
  62 Although 3Mpps seems already good, it is likely that performances will be improved
  63 in next versions.
  64
  65 ## Configuration
  66
  67 ### Global LB parameters
  68
  69 The load balancer needs to be configured with some parameters:
  70
  71         lb conf [ip4-src-address <addr>] [ip6-src-address <addr>]
  72                 [buckets <n>] [timeout <s>]
  73
  74 ip4-src-address: the source address used to send encap. packets using IPv4 for GRE4 mode.
  75                  or Node IP4 address for NAT4 mode.
  76
  77 ip6-src-address: the source address used to send encap. packets using IPv6 for GRE6 mode.
  78                  or Node IP6 address for NAT6 mode.
  79
  80 buckets:         the *per-thread* established-connexions-table number of buckets.
  81
  82 timeout:         the number of seconds a connection will remain in the
  83                  established-connexions-table while no packet for this flow
  84                  is received.
  85
  86 ### Configure the VIPs
  87
  88     lb vip <prefix> [encap (gre6|gre4|l3dsr|nat4|nat6)] \
  89       [dscp <n>] [port <n> target_port <n> node_port <n>] [new_len <n>] [del]
  90
  91 new_len is the size of the new-connection-table. It should be 1 or 2 orders of
  92 magnitude bigger than the number of ASs for the VIP in order to ensure a good
  93 load balancing.
  94 Encap l3dsr and dscp is used to map VIP to dscp bit and rewrite DSCP bit in packets.
  95 So the selected server could get VIP from DSCP bit in this packet and perform DSR.
  96 Encap nat4/nat6 and port/target_port/node_port is used to do kube-proxy data plane.
  97
  98 Examples:
  99
 100     lb vip 2002::/16 encap gre6 new_len 1024
 101     lb vip 2003::/16 encap gre4 new_len 2048
 102     lb vip 80.0.0.0/8 encap gre6 new_len 16
 103     lb vip 90.0.0.0/8 encap gre4 new_len 1024
 104     lb vip 100.0.0.0/8 encap l3dsr dscp 2 new_len 32
 105     lb vip 90.1.2.1/32 encap nat4 port 3306 target_port 3307 node_port 30964 new_len 1024
 106     lb vip 2004::/16 encap nat6 port 6306 target_port 6307 node_port 30966 new_len 1024
 107
 108 ### Configure the ASs (for each VIP)
 109
 110     lb as <vip-prefix> [<address> [<address> [...]]] [del]
 111
 112 You can add (or delete) as many ASs at a time (for a single VIP).
 113 Note that the AS address family must correspond to the VIP encap. IP family.
 114
 115 Examples:
 116
 117     lb as 2002::/16 2001::2 2001::3 2001::4
 118     lb as 2003::/16 10.0.0.1 10.0.0.2
 119     lb as 80.0.0.0/8 2001::2
 120     lb as 90.0.0.0/8 10.0.0.1
 121
 122 ### Configure SNAT
 123
 124     lb set interface nat4 in <intfc> [del]
 125
 126 Set SNAT feature in a specific interface.
 127 (applicable in NAT4 mode only)
 128
 129     lb set interface nat6 in <intfc> [del]
 130
 131 Set SNAT feature in a specific interface.
 132 (applicable in NAT6 mode only)
 133
 134 ## Monitoring
 135
 136 The plugin provides quite a bunch of counters and information.
 137 These are still subject to quite significant changes.
 138
 139     show lb
 140     show lb vip
 141     show lb vip verbose
 142
 143     show node counters
 144
 145
 146 ## Design notes
 147
 148 ### Multi-Threading
 149
 150 MagLev is a distributed system which pseudo-randomly generates a
 151 new-connections-table based on AS names such that each server configured with
 152 the same set of ASs ends up with the same table. Connection stickyness is then
 153 ensured with an established-connections-table. Using ECMP, it is assumed (but
 154 not relied on) that servers will mostly receive traffic for different flows.
 155
 156 This implementation pushes the parallelism a little bit further by using
 157 one established-connections table per thread. This is equivalent to assuming
 158 that RSS will make a job similar to ECMP, and is pretty useful as threads don't
 159 need to get a lock in order to write in the table.
 160
 161 ### Hash Table
 162
 163 A load balancer requires an efficient read and write hash table. The hash table
 164 used by ip6-forward is very read-efficient, but not so much for writing. In
 165 addition, it is not a big deal if writing into the hash table fails (again,
 166 MagLev uses a flow table but does not heaviliy relies on it).
 167
 168 The plugin therefore uses a very specific (and stupid) hash table.
 169         - Fixed (and power of 2) number of buckets (configured at runtime)
 170         - Fixed (and power of 2) elements per buckets (configured at compilation time)
 171
 172 ### Reference counting
 173
 174 When an AS is removed, there is two possible ways to react.
 175         - Keep using the AS for established connections
 176         - Change AS for established connections (likely to cause error for TCP)
 177
 178 In the first case, although an AS is removed from the configuration, its
 179 associated state needs to stay around as long as it is used by at least one
 180 thread.
 181
 182 In order to avoid locks, a specific reference counter is used. The design is quite
 183 similar to clib counters but:
 184         - It is possible to decrease the value
 185         - Summing will not zero the per-thread counters
 186         - Only the thread can reallocate its own counters vector (to avoid concurrency issues)
 187
 188 This reference counter is lock free, but reading a count of 0 does not mean
 189 the value can be freed unless it is ensured by *other* means that no other thread
 190 is concurrently referencing the object. In the case of this plugin, it is assumed
 191 that no concurrent event will take place after a few seconds.
 192