src/plugins/kubeproxy/kp_plugin_doc.md

   1 # Kube-proxy plugin for VPP    {#kp_plugin_doc}
   2
   3 ## Overview
   4
   5 This plugin provides kube-proxy data plane on user space,
   6 which is used to replace linux kernal's kube-proxy based on iptables.
   7 The idea is largely inspired from VPP LB plugin.
   8
   9 Currently, kube-proxy plugin supports three service types:
  10 1) Cluster IP plus Port: support any protocols, including TCP, UDP.
  11 2) Node IP plus Node Port: currently only support UDP.
  12 3) External Load Balancer.
  13
  14 For Cluster IP plus Port case:
  15 kube-proxy is configured with a set of Virtual IPs (VIP, which can be
  16 prefixes), and for each VIP, with a set of POD addresses (PODs).
  17
  18 For a specific session received for a given VIP (or VIP prefix),
  19 first packet selects a Pod according to internal load balancing algorithm,
  20 then does DNAT operation and sent to chosen Pod.
  21 At the same time, will create a session entry to store Pod chosen result.
  22 Following packets for that session will look up session table first,
  23 which ensures that a given session will always be routed to the same Pod.
  24
  25 For returned packet from Pod, it will do SNAT operation and sent out.
  26
  27 Please refer to below for details:
  28 https://schd.ws/hosted_files/ossna2017/1e/VPP_K8S_GTPU_OSSNA.pdf
  29
  30
  31 ## Configuration
  32
  33 ### Global KP parameters
  34
  35 The kube-proxy needs to be configured with some parameters:
  36
  37         ku conf [buckets <n>] [timeout <s>]
  38
  39 buckets: the *per-thread* established-connections-table number of buckets.
  40
  41 timeout: the number of seconds a connection will remain in the
  42          established-connections-table while no packet for this flow
  43          is received.
  44
  45 ### Configure VIPs and Ports
  46
  47     ku vip <prefix>  port <n> target_port <n> node_port <n> \
  48       [nat4|nat6)] [new_len <n>] [del]
  49
  50 new_len is the size of the new-connection-table. It should be 1 or 2 orders of
  51 magnitude bigger than the number of PODs for the VIP in order to ensure a good
  52 load balancing.
  53
  54 Examples:
  55
  56     ku vip 90.0.0.0/8 nat44 new_len 2048
  57     ku vip 2003::/16 nat66 new_len 2048
  58
  59 ### Configure PODs (for each VIP)
  60
  61     ku pod <vip-prefix> [<address> [<address> [...]]] [del]
  62
  63 You can add (or delete) as many PODs at a time (for a single VIP).
  64
  65 Examples:
  66
  67     ku pod 90.0.0.0/8 10.0.0.1
  68     ku pod 2002::/16 2001::2 2001::3 2001::4
  69
  70 ### Configure SNAT
  71
  72     ku set interface nat4 in <intfc> [del]
  73
  74 Set SNAT feature in a specific interface.
  75
  76
  77 ## Monitoring
  78
  79 The plugin provides quite a bunch of counters and information.
  80
  81     show ku
  82     show ku vip verbose
  83     show node counters
  84
  85
  86 ## Design notes
  87
  88 ### Multi-Threading
  89
  90 This implementation implement parallelism by using
  91 one established-connections table per thread. This is equivalent to assuming
  92 that RSS will make a job similar to ECMP, and is pretty useful as threads don't
  93 need to get a lock in order to write in the table.
  94
  95 ### Hash Table
  96
  97 A kube-proxy requires an efficient read and write Hash table. The Hash table
  98 used by ip6-forward is very read-efficient, but not so much for writing. In
  99 addition, it is not a big deal if writing into the Hash table fails.
 100
 101 The plugin therefore uses a very specific Hash table.
 102         - Fixed (and power of 2) number of buckets (configured at runtime)
 103         - Fixed (and power of 2) elements per buckets (configured at compilation time)
 104
 105