src/foundation/scripts/cni/multus/README.md

   1 # Multus/SRIOV CNI&Device Plugin Support for IEC
   2
   3
   4 ## Introduction
   5 This commit provides Kubernetes networking support for Multus with SRIOV CNI support both on arm64 and amd64. A special configuration file for Broadcom smartNIC Stingray PS225 is provided as an example. So it can not only be used as a sample container networking support for Stingray PS225 with its sriov interfaces, but also a generic SRIOV support for various ethernet NICs.
   6 Here we would like to provide 2 types legacy CNIs besides the SRIOV-CNI by Multus, which are [Flannel](https://coreos.com/flannel/docs/latest/kubernetes.html), and [Calico](https://docs.projectcalico.org/v3.11/introduction/).
   7 They would be provided as the default CNIs for any pods without explicit annotations.
   8
   9 The work here is based on the following open source projects:
  10 1. [Multus](https://github.com/intel/multus-cni)
  11 1. [SRIOV Device Plugin](https://github.com/intel/sriov-network-device-plugin)
  12 1. [SRIOV CNI](https://github.com/intel/sriov-cni)
  13
  14 For Broadcom Stingray PS225, please refer its [documents](https://github.com/CCX-Stingray/Documentation).
  15
  16
  17 ## Initial setup
  18
  19 The SRIOV interfaces should be created before using the SRIOV CNI, for example, if the PF name of one of the Stingray PS225 ethernet NICs in your system is enp8s0f0np0, then you can lookup the maximum supported number of VFs under the PF and create the VFs with the command:
  20
  21 ```
  22 #ip link set enp8s0f0np0 up
  23 #cat /sys/class/net/enp8s0f0np0/device/sriov_totalvfs
  24 16
  25 #echo 16 > /sys/class/net/enp8s0f0np0/device/sriov_numvfs
  26 ```
  27 For SRIOV CNI with DPDK type drivers, such as vfio-pci, uio_pci_generic, please bind the driver by dpdk-devbind besides creating the VFs, for example:
  28 ```dpdk-devbind.py -b vfio-pci enp12s2```
  29 The `enp12s2` is the name of one of VFs of a ethernet NIC.
  30
  31 For more information, please refer the above links in the [Introduction](#Introduction).
  32
  33 ##Installation
  34
  35 To install the Multus-SRIOV-Calico or Multus-SRIOV-Flannel, the CNI_TYPE field should be set to 'multus-sriov-calico'
  36 or 'multus-sriov-flannel' correspondingly in the IEC's installation configuration file named as 'config', then do the
  37 CNI installation by setup-cni.sh.
  38
  39 For SRIOV CNI with Flannel by Multus CNI, there are 4 yaml files give:
  40 1. configMap.yaml:
  41 The resource list configuration file for SRIOV device plugin
  42 1. multus-sriov-flannel-daemonsets.yaml
  43 The Multus, SRIOV device plugin&CNI configuration file
  44 1. flannel-daemonset.yml
  45 The Flannel CNI installation file
  46 1. sriov-crd.yaml
  47 The SRIOV CNI configuration file for the attached SRIOV interface resource.
  48
  49 For SRIOV CNI with Calico by Multus CNI, there are 4 yaml files give:
  50 1. configMap.yaml:
  51 The resource list configuration file for SRIOV device plugin
  52 1. multus-sriov-calico-daemonsets.yaml
  53 The Multus, SRIOV device plugin&CNI configuration file
  54 1. calico-daemonset.yaml
  55 The Flannel CNI installation file
  56 1. sriov-crd.yaml
  57 The SRIOV CNI configuration file for the attached SRIOV interface resource.
  58
  59 Usually users should modify the `configMap.yaml` and `sriov-crd.yaml` with their own corresponding networking configuration before doing the installation.
  60
  61 A quick installation script is given as `install.sh`, and the uninstallation could be done by call the `uninstall.sh`.Before you call the install.sh manually to do the install, you should set your desired POD_NETWORK or other parameters in the installation yaml files as we do in the setup-cni.sh.
  62
  63 For Kubernets version >=1.16, there are some changes for Kubernetes API. There is a sample installation script for multus-sriov-calico named as install-k8s-v1.16.sh, which could be used as a sample when your K8s version >=1.16.
  64
  65 **The `install.sh` should be called after the Kubernetes cluster had been installed but before installing the CNIs.**
  66
  67 2 sample user pods yaml files using the SRIOV CNI are given also, please see `pod1.yaml` and `pod2.yaml` in the directory, and 2 iperfv2 based yaml files are also provided to facilitate the performance test. We choose IPerfv2 instead of the IPerfv3 because it seems can support multi-threaded sending/receiving. The 4 yaml files here are provided just for arm64 platform and they could easily be adapted to amd64 platform with corresponding images with a docker building based on the provided Dockerfile.iperf2 file.
  68
  69
  70 ## Notes
  71 Current installation files are suitable for K8s version less than 1.6, for that equal to or greater than 1.6, some modifications to the installation files should be done, which would adapt to the K8s api changes for newer versions.
  72 We would try to give a sample installation file for k8s 1.6 or above in the future, but it had not tested now.
  73
  74 The command `kubectl get node $(hostname) -o json | jq '.status.allocatable'` can be used to check whether the allocated resources are available to use or not.
  75
  76 ## Other References
  77 [Advanced Networking Features in
  78 Kubernetes and Container Bare Metal](https://builders.intel.com/docs/networkbuilders/adv-network-features-in-kubernetes-app-note.pdf)
  79
  80 [Kubernetes: Multus + SRIOV quickstart](https://zshisite.wordpress.com/2018/11/15/kubernetes-multus-sriov-quickstart/)
  81