XTesting/kubespray/docs/multus.md

   1 # Multus
   2
   3 Multus is a meta CNI plugin that provides multiple network interface support to
   4 pods. For each interface, Multus delegates CNI calls to secondary CNI plugins
   5 such as Calico, macvlan, etc.
   6
   7 See [multus documentation](https://github.com/intel/multus-cni).
   8
   9 ## Multus installation
  10
  11 Since Multus itself does not implement networking, it requires a master plugin, which is specified through the variable `kube_network_plugin`. To enable Multus an additional variable `kube_network_plugin_multus` must be set to `true`. For example,
  12
  13 ```yml
  14 kube_network_plugin: calico
  15 kube_network_plugin_multus: true
  16 ```
  17
  18 will install Multus and Calico and configure Multus to use Calico as the primary network plugin.
  19
  20 ## Using Multus
  21
  22 Once Multus is installed, you can create CNI configurations (as a CRD objects) for additional networks, in this case a macvlan CNI configuration is defined. You may replace the config field with any valid CNI configuration where the CNI binary is available on the nodes.
  23
  24 ```ShellSession
  25 cat <<EOF | kubectl create -f -
  26 apiVersion: "k8s.cni.cncf.io/v1"
  27 kind: NetworkAttachmentDefinition
  28 metadata:
  29   name: macvlan-conf
  30 spec:
  31   config: '{
  32       "cniVersion": "0.4.0",
  33       "type": "macvlan",
  34       "master": "eth0",
  35       "mode": "bridge",
  36       "ipam": {
  37         "type": "host-local",
  38         "subnet": "192.168.1.0/24",
  39         "rangeStart": "192.168.1.200",
  40         "rangeEnd": "192.168.1.216",
  41         "routes": [
  42           { "dst": "0.0.0.0/0" }
  43         ],
  44         "gateway": "192.168.1.1"
  45       }
  46     }'
  47 EOF
  48 ```
  49
  50 You may then create a pod with and additional interface that connects to this network using annotations. The annotation correlates to the name in the NetworkAttachmentDefinition above.
  51
  52 ```ShellSession
  53 cat <<EOF | kubectl create -f -
  54 apiVersion: v1
  55 kind: Pod
  56 metadata:
  57   name: samplepod
  58   annotations:
  59     k8s.v1.cni.cncf.io/networks: macvlan-conf
  60 spec:
  61   containers:
  62   - name: samplepod
  63     command: ["/bin/bash", "-c", "sleep 2000000000000"]
  64     image: dougbtv/centos-network
  65 EOF
  66 ```
  67
  68 You may now inspect the pod and see that there is an additional interface configured:
  69
  70 ```ShellSession
  71 kubectl exec -it samplepod -- ip a
  72 ```
  73
  74 For more details on how to use Multus, please visit <https://github.com/intel/multus-cni>