Merge "Integrate Bond CNI Plugin"

doc/source/shared/abbrevs.txt

@@ -9,6 +9,7 @@
 .. |AIO| replace:: :abbr:`AIO (All-In-One)`
 .. |AIO-DX| replace:: :abbr:`AIO-DX (All-In-One Duplex)`
 .. |AIO-SX| replace:: :abbr:`AIO-SX (All-In-One Simplex)`
+.. |ARP| replace:: :abbr:`ARP (Address Resolution Protocol)`
 .. |AVP| replace:: :abbr:`AVP (Accelerated Virtual Port)`
 .. |AVPs| replace:: :abbr:`AVPs (Accelerated Virtual Ports)`
 .. |AWS| replace:: :abbr:`AWS (Amazon Web Services)`
@@ -59,6 +60,7 @@
 .. |IEEE| replace:: :abbr:`IEEE (Institute of Electrical and Electronics Engineers)`
 .. |IGMP| replace:: :abbr:`IGMP (Internet Group Management Protocol)`
 .. |IoT| replace:: :abbr:`IoT (Internet of Things)`
+.. |IPAM| replace:: :abbr:`IPAM (IP Address Management)`
 .. |IPMI| replace:: :abbr:`IPMI (Intelligent Platform Management Interface)`
 .. |IOPS| replace:: :abbr:`IOPS (I/O operations per second)`
 .. |IRQ| replace:: :abbr:`IRQ (Interrupt Request)`

doc/source/usertasks/kubernetes/index-usertasks-kub-1291759aa985.rst

@@ -154,9 +154,12 @@ Optimize application performance
    using-kubernetes-cpu-manager-static-policy
    use-application-isolated-cores
 
-----------------------------------------
+
-Adding an SRIOV interface to a container
+.. _add-sriov-interface-to-container:
-----------------------------------------
+
+-------------------------------------
+Add an SRIOV interface to a container
+-------------------------------------
 
 .. toctree::
    :maxdepth: 1
@@ -164,6 +167,16 @@ Adding an SRIOV interface to a container
    creating-network-attachment-definitions
    using-network-attachment-definitions-in-a-container
 
+
+-----------------------
+Use the Bond CNI Plugin
+-----------------------
+
+.. toctree::
+   :maxdepth: 1
+
+   integrate-the-bond-cni-plugin-2c2f14733b46
+
 --------------
 Metrics Server
 --------------

doc/source/usertasks/kubernetes/integrate-the-bond-cni-plugin-2c2f14733b46.rst

@@ -0,0 +1,258 @@
+.. _integrate-the-bond-cni-plugin-2c2f14733b46:
+
+=============================
+Integrate the Bond CNI Plugin
+=============================
+
+The bond-cni plugin provides a method for aggregating multiple network
+interfaces into a single logical "bonded" interface.
+
+.. contents:: |minitoc|
+   :local:
+   :depth: 1
+
+To add a bonded interface to a container, a network attachment definition of
+type ``bond`` must be created and added as a network annotation in the pod
+specification. The bonded interfaces can either be taken from the host or
+container based on the value of the ``linksInContainer`` parameter in the
+network attachment definition.
+
+For more information on network attachment definitions and how to apply them,
+see :ref:`add-sriov-interface-to-container`.
+
+For more information on the Bond CNI plugin, see:
+
+https://github.com/k8snetworkplumbingwg/bond-cni
+
+The general bonding |CNI| configuration parameters are:
+
+``name``
+   (``string``, required): The name of the network.
+
+``type``
+   (``string``, required): ``bond``
+
+``ifname``
+   (``string``, optional): The name of the bond interface that will be created
+   in the container.
+
+``miimon``
+   (``int``, required): Specifies the |ARP| link monitoring frequency in
+   milliseconds.
+
+``mode``
+   (``string``, required): Specifies the mode of the bonding interface (one of
+   ``active-backup``, ``balance-xor``, ``broadcast``, ``802.3ad``,
+   ``balance-tlb``, ``balance-alb``).
+
+``mtu``
+   (``int``, optional): The |MTU| of the bond. The default is 1500.
+
+``failOverMac``
+   (``int``, optional): Specifies the ``failOverMac`` setting for the bond.
+   Should be set to 1 for active-backup bond modes. Default is 0.
+
+``linksInContainer``
+   (``boolean``, optional): Specifies whether slave links are in the container
+   to start. Default is ``false``, that is, look for interfaces on host before
+   bonding.
+
+``links``
+   (``dictionary``, required): Master interface names.
+
+``ipam``
+   (``dictionary``, required): |IPAM| configuration to be used for this
+   network, The mode can be one of: ``static``, ``host-local``, ``dhcp``,
+   or ``calico-ipam``.
+
+For more information on each mode, ``miimon``, and ``failOverMac`` behavior,
+see:
+
+https://www.kernel.org/doc/Documentation/networking/bonding.txt
+
+----------------------------------------------------------------------------
+Exampe: Launch a daemonset bonding two host interfaces in active-backup mode
+----------------------------------------------------------------------------
+
+The following example launches a daemonset bonding two host interfaces in
+active-backup mode.  Since the ``linksInContainer`` value is not set (default),
+the links list indicates the interfaces should be looked up on the host.
+
+.. code-block:: yaml
+
+   ---
+   apiVersion: crd.projectcalico.org/v1
+   kind: IPPool
+   metadata:
+     name: mypool
+   spec:
+     cidr: "10.10.20.0/24"
+     ipipMode: "Never"
+     natOutgoing: True
+   ---
+   apiVersion: "k8s.cni.cncf.io/v1"
+   kind: NetworkAttachmentDefinition
+   metadata:
+     name: bond0
+   spec:
+     config: '{
+       "cniVersion": "0.3.1",
+       "name": "bond0",
+       "type": "bond",
+       "ifname": "net1",
+       "mode": "active-backup",
+       "miimon": "100",
+       "failOverMac": 1,
+       "links": [
+         {
+           "name": "eth1000"
+         },
+         {
+           "name": "eth1001"
+         }
+       ],
+       "ipam": {
+         "type": "calico-ipam",
+         "assign_ipv4": "true",
+         "ipv4_pools": ["mypool"]
+       },
+       "kubernetes": {
+         "kubeconfig": "/etc/cni/net.d/calico-kubeconfig"
+       },
+       "datastore_type": "kubernetes"
+     }'
+   ---
+   apiVersion: apps/v1
+   kind: DaemonSet
+   metadata:
+     name: bonding
+     namespace: default
+     labels:
+       tier: node
+   spec:
+     selector:
+       matchLabels:
+         tier: node
+     template:
+       metadata:
+         labels:
+           tier: node
+           app: bonding
+         annotations:
+           cni.projectcalico.org/ipv4pools: '["default-ipv4-ippool"]'
+           k8s.v1.cni.cncf.io/networks: '[
+                   { "name": "bond0" }
+           ]'
+       spec:
+         containers:
+         - name: bonding1
+           image: centos/tools
+           imagePullPolicy: IfNotPresent
+           command: [ "/bin/bash", "-c", "--" ]
+           args: [ "while true; do sleep 300000; done;" ]
+           securityContext:
+             capabilities:
+               add:
+                 - NET_ADMIN
+
+---------------------------------------------------------------------------
+Example: Launch a pod with a bonded SR-IOV interface in 802.3ad (LACP) mode
+---------------------------------------------------------------------------
+
+The following example launches a pod with a bonded |SRIOV| interface in
+802.3ad (|LACP|) mode.  Since the ``linksInContainer`` value is ``true``, the
+defined links are made up of the ``net1`` and ``net2`` interfaces representing
+the individual |SRIOV| interfaces.
+
+The addition of ``"spoofchk": "off"`` in the ``pci_sriov_net_group0_data0``
+``config`` block ensures that applications within the container have 
+permission to change the |MAC| address of the |VF|.
+
+.. code-block:: yaml
+
+   ---
+   apiVersion: "k8s.cni.cncf.io/v1"
+   kind: NetworkAttachmentDefinition
+   metadata:
+     name: sriov0
+     annotations:
+       k8s.v1.cni.cncf.io/resourceName: intel.com/pci_sriov_net_group0_data0
+   spec:
+     config: '{
+       "cniVersion": "0.3.1",
+       "type": "sriov",
+       "vlan": 1350
+       "spoofchk": "off"
+     }'
+   ---
+   apiVersion: "k8s.cni.cncf.io/v1"
+   kind: NetworkAttachmentDefinition
+   metadata:
+     name: sriov1
+     annotations:
+       k8s.v1.cni.cncf.io/resourceName: intel.com/pci_sriov_net_group0_data1
+   spec:
+     config: '{
+       "cniVersion": "0.3.1",
+       "type": "sriov",
+       "vlan": 1350
+       "spoofchk": "off"
+     }'
+   ---
+   apiVersion: "k8s.cni.cncf.io/v1"
+   kind: NetworkAttachmentDefinition
+   metadata:
+     name: bond0
+   spec:
+     config: '{
+       "cniVersion": "0.3.1",
+       "name": "bond0",
+       "ifname": "bond0",
+       "type": "bond",
+       "mode": "802.3ad",
+       "miimon": "100",
+       "linksInContainer": true,
+       "links": [
+         {
+           "name": "net1"
+         },
+         {
+           "name": "net2"
+         }
+       ],
+       "ipam": {
+         "type": "static",
+         "addresses": [{
+           "address": "192.168.0.1/24"}]
+       }
+     }'
+   ---
+   apiVersion: v1
+   kind: Pod
+   metadata:
+     name: bond0
+     annotations:
+       k8s.v1.cni.cncf.io/networks: '[
+         { "name": "sriov0" },
+         { "name": "sriov1" },
+         { "name": "bond0" }
+       ]'
+   spec:
+     restartPolicy: Never
+     containers:
+     - name: bond0
+       image: centos/tools
+       imagePullPolicy: IfNotPresent
+       command: [ "/bin/bash", "-c", "--" ]
+       args: [ "while true; do sleep 300000; done;" ]
+       securityContext:
+         capabilities:
+           add:
+             - NET_ADMIN
+       resources:
+         requests:
+           intel.com/pci_sriov_net_group0_data0: '1'
+           intel.com/pci_sriov_net_group0_data1: '1'
+         limits:
+           intel.com/pci_sriov_net_group0_data0: '1'
+           intel.com/pci_sriov_net_group0_data1: '1'