plugins/lb-plugin/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 Traffic received for a given VIP (or VIP prefix) is tunneled using GRE towards
  18 the different ASs in a way that (tries to) ensure that a given session will
  19 always be tunneled to the same AS.
  20
  21 Both VIPs or ASs can be IPv4 or IPv6, but for a given VIP, all ASs must be using
  22 the same encap. type (i.e. IPv4+GRE or IPv6+GRE). Meaning that for a given VIP,
  23 all AS addresses must be of the same family.
  24
  25 ## Performances
  26
  27 The load balancer has been tested up to 1 millions flows and still forwards more
  28 than 3Mpps per core in such circumstances.
  29 Although 3Mpps seems already good, it is likely that performances will be improved
  30 in next versions.
  31
  32 ## Configuration
  33
  34 ### Global LB parameters
  35
  36 The load balancer needs to be configured with some parameters:
  37
  38         lb conf [ip4-src-address <addr>] [ip6-src-address <addr>]
  39                 [buckets <n>] [timeout <s>]
  40
  41 ip4-src-address: the source address used to send encap. packets using IPv4.
  42
  43 ip6-src-address: the source address used to send encap. packets using IPv6.
  44
  45 buckets:         the *per-thread* established-connexions-table number of buckets.
  46
  47 timeout:         the number of seconds a connection will remain in the
  48                  established-connexions-table while no packet for this flow
  49                  is received.
  50
  51
  52 ### Configure the VIPs
  53
  54     lb vip <prefix> [encap (gre6|gre4)] [new_len <n>] [del]
  55
  56 new_len is the size of the new-connection-table. It should be 1 or 2 orders of
  57 magnitude bigger than the number of ASs for the VIP in order to ensure a good
  58 load balancing.
  59
  60 Examples:
  61
  62     lb vip 2002::/16 encap gre6 new_len 1024
  63     lb vip 2003::/16 encap gre4 new_len 2048
  64     lb vip 80.0.0.0/8 encap gre6 new_len 16
  65     lb vip 90.0.0.0/8 encap gre4 new_len 1024
  66
  67 ### Configure the ASs (for each VIP)
  68
  69     lb as <vip-prefix> [<address> [<address> [...]]] [del]
  70
  71 You can add (or delete) as many ASs at a time (for a single VIP).
  72 Note that the AS address family must correspond to the VIP encap. IP family.
  73
  74 Examples:
  75
  76     lb as 2002::/16 2001::2 2001::3 2001::4
  77     lb as 2003::/16 10.0.0.1 10.0.0.2
  78     lb as 80.0.0.0/8 2001::2
  79     lb as 90.0.0.0/8 10.0.0.1
  80
  81
  82
  83 ## Monitoring
  84
  85 The plugin provides quite a bunch of counters and information.
  86 These are still subject to quite significant changes.
  87
  88     show lb
  89     show lb vip
  90     show lb vip verbose
  91
  92     show node counters
  93
  94
  95 ## Design notes
  96
  97 ### Multi-Threading
  98
  99 MagLev is a distributed system which pseudo-randomly generates a
 100 new-connections-table based on AS names such that each server configured with
 101 the same set of ASs ends up with the same table. Connection stickyness is then
 102 ensured with an established-connections-table. Using ECMP, it is assumed (but
 103 not relied on) that servers will mostly receive traffic for different flows.
 104
 105 This implementation pushes the parallelism a little bit further by using
 106 one established-connections table per thread. This is equivalent to assuming
 107 that RSS will make a job similar to ECMP, and is pretty useful as threads don't
 108 need to get a lock in order to write in the table.
 109
 110 ### Hash Table
 111
 112 A load balancer requires an efficient read and write hash table. The hash table
 113 used by ip6-forward is very read-efficient, but not so much for writing. In
 114 addition, it is not a big deal if writing into the hash table fails (again,
 115 MagLev uses a flow table but does not heaviliy relies on it).
 116
 117 The plugin therefore uses a very specific (and stupid) hash table.
 118         - Fixed (and power of 2) number of buckets (configured at runtime)
 119         - Fixed (and power of 2) elements per buckets (configured at compilation time)
 120
 121 ### Reference counting
 122
 123 When an AS is removed, there is two possible ways to react.
 124         - Keep using the AS for established connections
 125         - Change AS for established connections (likely to cause error for TCP)
 126
 127 In the first case, although an AS is removed from the configuration, its
 128 associated state needs to stay around as long as it is used by at least one
 129 thread.
 130
 131 In order to avoid locks, a specific reference counter is used. The design is quite
 132 similar to clib counters but:
 133         - It is possible to decrease the value
 134         - Summing will not zero the per-thread counters
 135         - Only the thread can reallocate its own counters vector (to avoid concurrency issues)
 136
 137 This reference counter is lock free, but reading a count of 0 does not mean
 138 the value can be freed unless it is ensured by *other* means that no other thread
 139 is concurrently referencing the object. In the case of this plugin, it is assumed
 140 that no concurrent event will take place after a few seconds.
 141