docs/release/installation/contiv-vpp_setup.rst

   1 Contiv-VPP Setup
   2 ================
   3
   4 This document describes how to deployment IEC platform with Contiv-VPP
   5 networking on bare metal hosts.The automatic deployment script provided
   6 by IEC uses calico CNI by default. To enable Contiv-VPP network solution
   7 for Kubernetes, you need to make some minor modifications.Now the IEC
   8 only supports multiple NICs deployment, and does not support Configuring
   9 STN for the time being.In addition, the deployment methods of IEC type1
  10 and type2 are slightly different, and will be introduced in different
  11 chapters.
  12
  13 Setting up for IEC type2
  14 ------------------------
  15
  16 IEC type2 deploy on large and powerful business servers.The main
  17 installation steps as following:
  18
  19 Setting up DPDK
  20 ~~~~~~~~~~~~~~~
  21
  22 ALL port that are to be used by an DPDK aplication must be bound to the
  23 uio_pci_generic, igb_uio or vfio-pci module before the application is
  24 run, more detail info please refer `DPDK DOC`_.
  25
  26 The following guide will use vfio-pci. Load kernel module
  27
  28 ::
  29
  30     $ sudo modprobe vfio-pci
  31
  32 Verify that PCI driver has loaded successfully
  33
  34 ::
  35
  36     $ lsmod |grep pci
  37     vfio_pci               49152  0
  38     vfio_virqfd            16384  1 vfio_pci
  39     vfio_iommu_type1       24576  0
  40     vfio                   40960  2 vfio_iommu_type1,vfio_pci
  41
  42 Determining network adapter that vpp to use
  43
  44 ::
  45
  46     $ sudo lshw -class network -businfo
  47     Bus info          Device       Class      Description
  48     ================================================
  49     pci@0000:89:00.0  enp137s0f0   network    Ethernet Controller X710 for 10GbE SFP+
  50     pci@0000:89:00.1  enp137s0f1   network    Ethernet Controller X710 for 10GbE SFP+
  51
  52 In this example, enp137s0f1 used by vpp and binding to kernel module:
  53
  54 ::
  55
  56     $ sudo ~/dpdk/usertools/dpdk-devbind.py --bind=vfio-pci enp137s0f1
  57
  58 The script dpdk-devbind.py in `DPDK`_ repo.
  59
  60 Automation deployment
  61 ~~~~~~~~~~~~~~~~~~~~~
  62
  63 As a minimum requirement 3 nodes are needed: jumpserver, master node and
  64 worker node. The two kinds nodes are configured by different script.
  65
  66 -  Modify default network solution
  67
  68 .. code:: diff
  69
  70     --- a/src/foundation/scripts/config
  71     +++ b/src/foundation/scripts/config
  72     @@ -30,7 +30,7 @@ K8S_WORKER_GROUP=(
  73      CLUSTER_IP=172.16.1.136 # Align with the value in our K8s setup script
  74      POD_NETWORK_CIDR=192.168.0.0/16
  75      #IEC support three kinds network solution for Kubernetes: calico,flannel,contivpp
  76     -CNI_TYPE=calico
  77     +CNI_TYPE=contivpp
  78      #kubernetes-cni version 0.7.5/ 0.6.0
  79      CNI_VERSION=0.6.0
  80
  81 -  Master node configuration
  82
  83 Initialize DEV_NAME for master node,Instantiate the fourth argument of the setup-cni.sh script
  84
  85 .. code:: diff
  86
  87     --- a/src/foundation/scripts/startup.sh
  88     +++ b/src/foundation/scripts/startup.sh
  89     @@ -99,7 +99,7 @@ deploy_k8s () {
  90        #Deploy etcd & CNI from master node
  91     -  SETUP_CNI="cd iec/src/foundation/scripts && source setup-cni.sh $CLUSTER_IP $POD_NETWORK_CIDR $CNI_TYPE"
  92     +  SETUP_CNI="cd iec/src/foundation/scripts && source setup-cni.sh $CLUSTER_IP $POD_NETWORK_CIDR $CNI_TYPE enp137s0f1"
  93        sshpass -p ${K8S_MASTERPW} ssh -o StrictHostKeyChecking=no ${HOST_USER}@${K8S_MASTER_IP} ${SETUP_CNI}
  94        SETUP_HELM="cd iec/src/foundation/scripts && source helm.sh"
  95
  96 The modified result is as follows
  97
  98 .. code:: diff
  99
 100     --- a/src/foundation/scripts/setup-cni.sh
 101     +++ b/src/foundation/scripts/setup-cni.sh
 102     @@ -11,7 +11,7 @@ fi
 103      CLUSTER_IP=${1:-172.16.1.136} # Align with the value in our K8s setup script
 104      POD_NETWORK_CIDR=${2:-192.168.0.0/16}
 105      CNI_TYPE=${3:-calico}
 106     -DEV_NAME=${4:-}
 107     +DEV_NAME=${4:-enp137s0f1}
 108
 109 -  Worker node configuration
 110
 111 The same as master node, worker node need setting up DPDK and
 112 determining network adapter. Initialize DEV_NAME for work node
 113
 114 .. code:: diff
 115
 116     --- a/src/foundation/scripts/config
 117     +++ b/src/foundation/scripts/config
 118     @@ -42,4 +42,4 @@ KUBE_VERSION=1.13.0
 119      #  [10.169.40.106]="enp137s0f0"
 120      #  )
 121      declare -A DEV_NAME
 122     -DEV_NAME=()
 123     +DEV_NAME=([10.169.40.106]="enp137s0f0")
 124
 125 DEV_NAME is an associative array, list network interface device names
 126 used by contivpp. Use IP address of K8S_WORKER_GROUP as key.
 127
 128 -  Launch setup
 129
 130 Simply start the installation script startup.sh on jumpserver:
 131
 132 ::
 133
 134     jenkins@jumpserver:~/iec/src/foundation/scripts$ ./startup.sh
 135
 136 for more details and information refer to `installation.instruction.rst`_
 137
 138 Setting up for IEC type1
 139 ------------------------
 140
 141 IEC type1 device is suitable for low power device.Now we choose
 142 `MACCHIATObin`_ board as the main hardware
 143 platform.
 144
 145 Install MUSDK
 146 ~~~~~~~~~~~~~
 147
 148 Marvell User-Space SDK(`MUSDK`_)
 149 is a light-weight user-space I/O driver for Marvell's Embedded
 150 Networking SoC's, more detail info please refer `VPP Marvell plugin`_
 151
 152 Automation deployment
 153 ~~~~~~~~~~~~~~~~~~~~~
 154
 155 -  Modify default yaml
 156
 157 .. code:: diff
 158
 159     diff --git a/src/foundation/scripts/setup-cni.sh b/src/foundation/scripts/setup-cni.sh
 160     index d466831..6993006 100755
 161     --- a/src/foundation/scripts/setup-cni.sh
 162     +++ b/src/foundation/scripts/setup-cni.sh
 163     @@ -43,7 +43,7 @@ install_contivpp(){
 164
 165        # Install contivpp CNI
 166        sed -i "s@10.1.0.0/16@${POD_NETWORK_CIDR}@" "${SCRIPTS_DIR}/cni/contivpp/contiv-vpp.yaml"
 167     -  kubectl apply -f "${SCRIPTS_DIR}/cni/contivpp/contiv-vpp.yaml"
 168     +  kubectl apply -f "${SCRIPTS_DIR}/cni/contivpp/contiv-vpp-macbin.yaml"
 169      }
 170
 171 -  Configuration
 172
 173 To configure a PP2 interface, MainVppInterface with the prefix mv-ppio-
 174 must be configured in the NodeConfig section of the deployment yaml.
 175 mv-ppio-X/Y is VPP interface name where X is PP2 device ID and Y is PPIO
 176 ID Interface needs to be assigned to MUSDK in FDT configuration and
 177 linux interface state must be up. Example configuration:
 178
 179 ::
 180
 181     ~/iec/src/foundation/scripts/cni/contivpp/contiv-vpp-macbin.yaml
 182         nodeConfig:
 183         - nodeName: net-arm-mcbin-iec
 184           mainVppInterface:
 185             interfaceName: mv-ppio-0/0
 186         - nodeName: net-arm-mcbin-iec-1
 187           mainVppInterface:
 188             interfaceName: mv-ppio-0/0
 189
 190 PP2 doesn't have any dependency on DPDK or DPDK plugin but it can work
 191 with DPDK plugin enabled or disabled.It is observed that performace is
 192 better around 30% when DPDK plugin is disabled. DPKD plugin can be
 193 disabled by adding following config to the contiv-vswitch.conf.
 194
 195 .. code:: diff
 196
 197     --- a/src/foundation/scripts/cni/contivpp/contiv-vswitch.conf
 198     +++ b/src/foundation/scripts/cni/contivpp/contiv-vswitch.conf
 199     @@ -24,3 +24,7 @@ socksvr {
 200      statseg {
 201         default
 202      }
 203     +plugins {
 204     +        plugin vpp_plugin.so { enable }
 205     +        plugin dpdk_plugin.so { disable }
 206     +}
 207
 208 -  Modify scripts
 209
 210 It`s necessary to modify relevant script as IEC type2 to support automatic deployment.
 211
 212 -  Launch setup
 213
 214 Simply start the installation script startup.sh on jumpserver:
 215
 216 ::
 217
 218     jenkins@jumpserver:~/iec/src/foundation/scripts$ ./startup.sh
 219
 220 for more details and information refer to
 221 `installation.instruction.rst`_
 222
 223 Deployment Verification
 224 -----------------------
 225
 226 invok ./src/foundation/scripts/nginx.sh install nginx; to test if CNI
 227 enviroment is ready.
 228
 229 Uninstalling Contiv-VPP
 230 -----------------------
 231
 232 To uninstall the network plugin for type2:
 233
 234 ::
 235
 236     kubectl delete -f  ./iec/src/foundation/scripts/cni/contivpp/contiv-vpp.yaml
 237
 238 To uninstall the network plugin for type1:
 239
 240 ::
 241
 242     kubectl delete -f  ./iec/src/foundation/scripts/cni/contivpp/contiv-vpp-macbin.yaml
 243
 244 In order to remove the persisted config, cleanup the bolt and ETCD
 245 storage:
 246
 247 ::
 248
 249     rm -rf /var/etcd/contiv-data
 250
 251 .. All links go below this line
 252 .. _`DPDK DOC`: https://doc.dpdk.org/guides/linux_gsg/linux_drivers.html#binding-and-unbinding-network-ports-to-from-the-kernel-modules
 253 .. _`DPDK`: https://github.com/DPDK/dpdk/blob/master/usertools/dpdk-devbind.py
 254 .. _`installation.instruction.rst`: ./installation.instruction.rst
 255 .. _`MACCHIATObin`: http://macchiatobin.net
 256 .. _`MUSDK`: https://github.com/MarvellEmbeddedProcessors/musdk-marvell
 257 .. _`VPP Marvell plugin`: https://github.com/FDio/vpp/blob/master/src/plugins/marvell/README.md