From 539fb24b446176acf2d12f2eca428a5dcf5bdbf4 Mon Sep 17 00:00:00 2001 From: Ron Stone Date: Wed, 4 May 2022 08:19:52 -0400 Subject: [PATCH] Container Network Interface (CNI) Plugin Up-version Add descriptions and examples of new CNI plugins. Note: Bond plugin is covered in https://review.opendev.org/c/starlingx/docs/+/837599 Content restructuring per patchset 1 comments. Patchset 2 review updates. Patchset 3 review updates. Fix merge conflict. eth1001 > eth1000 for consistency in example. Patchset 6 review updates. Story: 2009832 Task: 45235 Signed-off-by: Ron Stone Change-Id: Idab0308ff8f973c4aa20b66fbcfb932bf3dcf92c --- doc/source/shared/abbrevs.txt | 3 + ...-interface-to-a-container-616bc5c5a6dd.rst | 91 ++++ .../bandwidth-plugin-3b8966c3fe47.rst | 93 ++++ .../kubernetes/bridge-plugin-7caa94024df4.rst | 96 ++++ ...reating-network-attachment-definitions.rst | 195 -------- .../host-device-plugin-714d4862a825.rst | 57 +++ .../index-usertasks-kub-1291759aa985.rst | 32 +- ...grate-the-bond-cni-plugin-2c2f14733b46.rst | 12 +- .../kubernetes/ipvlan-plugin-150be92d0538.rst | 78 +++ .../macvlan-plugin-e631cca21ffb.rst | 78 +++ .../kubernetes/ptp-plugin-bc6ed0498f4c.rst | 72 +++ ...urce-based-routing-plugin-51648f2ddff1.rst | 222 +++++++++ .../kubernetes/sriov-plugin-4229f81b27ce.rst | 452 ++++++++++++++++++ .../kubernetes/tuning-plugin-08f8cdbf1763.rst | 88 ++++ ...-attachment-definitions-in-a-container.rst | 241 ---------- ...ing-and-forwarding-plugin-0e53f2c2de21.rst | 373 +++++++++++++++ .../kubernetes/vlan-plugin-37938fe8578f.rst | 74 +++ 17 files changed, 1800 insertions(+), 457 deletions(-) create mode 100644 doc/source/usertasks/kubernetes/add-an-additional-network-interface-to-a-container-616bc5c5a6dd.rst create mode 100644 doc/source/usertasks/kubernetes/bandwidth-plugin-3b8966c3fe47.rst create mode 100644 doc/source/usertasks/kubernetes/bridge-plugin-7caa94024df4.rst delete mode 100644 doc/source/usertasks/kubernetes/creating-network-attachment-definitions.rst create mode 100644 doc/source/usertasks/kubernetes/host-device-plugin-714d4862a825.rst create mode 100644 doc/source/usertasks/kubernetes/ipvlan-plugin-150be92d0538.rst create mode 100644 doc/source/usertasks/kubernetes/macvlan-plugin-e631cca21ffb.rst create mode 100644 doc/source/usertasks/kubernetes/ptp-plugin-bc6ed0498f4c.rst create mode 100644 doc/source/usertasks/kubernetes/source-based-routing-plugin-51648f2ddff1.rst create mode 100644 doc/source/usertasks/kubernetes/sriov-plugin-4229f81b27ce.rst create mode 100644 doc/source/usertasks/kubernetes/tuning-plugin-08f8cdbf1763.rst delete mode 100644 doc/source/usertasks/kubernetes/using-network-attachment-definitions-in-a-container.rst create mode 100644 doc/source/usertasks/kubernetes/virtual-routing-and-forwarding-plugin-0e53f2c2de21.rst create mode 100644 doc/source/usertasks/kubernetes/vlan-plugin-37938fe8578f.rst diff --git a/doc/source/shared/abbrevs.txt b/doc/source/shared/abbrevs.txt index c4c5040d6..c35d8c1e3 100755 --- a/doc/source/shared/abbrevs.txt +++ b/doc/source/shared/abbrevs.txt @@ -118,6 +118,7 @@ .. |SANs| replace:: :abbr:`SANs (Subject Alternative Names)` .. |SAS| replace:: :abbr:`SAS (Serial Attached SCSI)` .. |SATA| replace:: :abbr:`SATA (Serial AT Attachment)` +.. |SBR| replace:: :abbr:`SBR (Source-Based Routing)` .. |SCTP| replace:: :abbr:`SCTP (Stream Control Transmission Protocol)` .. |SDO| replace:: :abbr:`SDO (Secure Device Onboard)` .. |SLA| replace:: :abbr:`SLA (Service Level Agreement)` @@ -135,6 +136,7 @@ .. |STP| replace:: :abbr:`STP (Spanning Tree Protocol)` .. |SWACT| replace:: :abbr:`SWACT (SWitch ACTivity)` .. |T-BC| replace:: :abbr:`T-BC (Telecom Boundary Clock)` +.. |TBF| replace:: :abbr:`TBF (Token Bucket Filter)` .. |TCP| replace:: :abbr:`TCP (Transition Control Protocol)` .. |TFTP| replace:: :abbr:`TFTP (Trivial File Transfer Protocol)` .. |T-GM| replace:: :abbr:`T-GM (Telecom Grand Primary)` @@ -164,6 +166,7 @@ .. |VPC| replace:: :abbr:`VPC (Virtual Port Channel)` .. |vRAN| replace:: :abbr:`vRAN (virtualized Radio Access Network)` .. |VRF| replace:: :abbr:`VRF (Virtual Routing and Forwarding)` +.. |VRFs| replace:: :abbr:`VRFs (Virtual Routing and Forwarding)` .. |VTEP| replace:: abbr:`VTEP (Virtual Tunnel End Point)` .. |VXLAN| replace:: :abbr:`VXLAN (Virtual eXtensible Local Area Network)` .. |VXLANs| replace:: :abbr:`VXLANs (Virtual eXtensible Local Area Networks)` diff --git a/doc/source/usertasks/kubernetes/add-an-additional-network-interface-to-a-container-616bc5c5a6dd.rst b/doc/source/usertasks/kubernetes/add-an-additional-network-interface-to-a-container-616bc5c5a6dd.rst new file mode 100644 index 000000000..d94d1697d --- /dev/null +++ b/doc/source/usertasks/kubernetes/add-an-additional-network-interface-to-a-container-616bc5c5a6dd.rst @@ -0,0 +1,91 @@ +.. _add-an-additional-network-interface-to-a-container-616bc5c5a6dd: + +================================================== +Add an Additional Network Interface to a Container +================================================== + +.. contents:: |minitoc| + :local: + :depth: 1 + +Network attachment definition specifications can be created in order to +reference / request additional interfaces or network configurations in a +container specification. + +The type of network attachment definition corresponds to a container networking +plugin which performs the actions necessary to set up the interface in the +container. Some plugins correspond directly to a new interface in the +container, while other "meta" plugins are typically chained with an +interface-plugin to perform additional network configuration. Further, +``ipam`` plugins can be used to control the IP address allocation for the +interface. + +--------------------------------- +"interface-creating" plugin types +--------------------------------- + +:ref:`sriov ` + Adds an |SRIOV| |VF| interface to a container. + +:ref:`host-device ` + Adds an already-existing device to a container. + +:ref:`macvlan ` + Creates an interface with a new |MAC| address, usually from a shared host + interface. + +:ref:`ipvlan ` + Creates an ``ipvlan`` interface in the container. + +:ref:`bridge ` + Creates a bridge on the host and adds a ``veth`` interface in the container + to it. + +:ref:`ptp ` + Creates a ``veth`` pair between the container and host. + +:ref:`vlan ` + Creates a ``vlan`` device in the container. + + See :ref:`bond ` for more information. + +``bond`` + Creates a bonded interface in the container. + +:ref:`vrf ` + Enables virtual routing and forwarding in the network namespace of the + container. + +------------------- +"meta" plugin types +------------------- + +:ref:`tuning ` + Allows some ``sysctl`` parameters of an existing interface to be modified. + +``portmap`` + Maps ports from the host's address space to the container. + +:ref:`bandwidth ` + Applies bandwidth-limiting on a container interface through use of traffic + control ``tbf``. + +:ref:`sbr ` + Enables source based routing for an interface. + +------------------- +"ipam" plugin types +------------------- + +``dhcp`` + Runs a daemon on the host which makes |DHCP| requests on behalf of the + container. Requires a |DHCP| server to be connected to the interface. + +``host-local`` + Maintains a local database of allocated IP addresses. + +``static`` + Allocate a static IPv4/IPv6 addresses to container. + +``calico-ipam`` + Use Calico managed IP pools to allocate an address to the interface. diff --git a/doc/source/usertasks/kubernetes/bandwidth-plugin-3b8966c3fe47.rst b/doc/source/usertasks/kubernetes/bandwidth-plugin-3b8966c3fe47.rst new file mode 100644 index 000000000..d1e6aa520 --- /dev/null +++ b/doc/source/usertasks/kubernetes/bandwidth-plugin-3b8966c3fe47.rst @@ -0,0 +1,93 @@ +.. _bandwidth-plugin-3b8966c3fe47: + +================ +Bandwidth Plugin +================ + +The bandwidth plugin allows the configuration of the linux traffic control +subsystem for the interface. It uses a |TBF| queuing discipline (``qdisc``) +on both ingress and egress traffic. It must be used as a chained plugin in +conjunction with another interface-creating plugin. + +See https://man7.org/linux/man-pages/man8/tbf.8.html for more +information. + +The following options are used to configure the plugin: + +``name`` (string, optional) + The name of the network. + +``type`` (string, required) + ``bandwidth`` + +``ingressRate`` (int, required) + The rate, in bits per second, at which traffic can enter an interface. + +``ingressBurst`` (int, required) + The maximum amount in bits that tokens can be made available for + instantaneously. + +``egressRate`` (int, required) + The rate, in bits per second, at which traffic can leave an interface. + +``egressBurst`` (int, required) + The maximum amount, in bits, that tokens can be made available for + instantaneously. + + +.. rubric:: |eg| + +The following example creates a pod with an additional bridge interface which +uses the bandwidth plugin to ensure the ingress/egress rate does not exceed +100Kbps. Note the chained nature of the plugins. + +.. code-block:: yaml + + apiVersion: "k8s.cni.cncf.io/v1" + kind: NetworkAttachmentDefinition + metadata: + name: bridge1 + spec: + config: '{ + "cniVersion": "0.3.1", + "name": "bridgenet1", + "plugins": [ + { + "type": "bridge", + "bridge": "br1", + "ipam": { + "type": "static", + "addresses": [ + { + "address": "10.10.10.1/24", + "gateway": "10.10.10.2" + } + ] + } + }, + { + "name": "brbw", + "type": "bandwidth", + "ingressRate": 100000, + "ingressBurst": 50000, + "egressRate": 100000, + "egressBurst": 50000 + } + ] + }' + --- + apiVersion: v1 + kind: Pod + metadata: + name: bridgepod1 + annotations: + k8s.v1.cni.cncf.io/networks: '[ + { "name": "bridge1" } + ]' + spec: + containers: + - name: bridge1 + image: networkstatic/iperf3 + imagePullPolicy: IfNotPresent + command: [ "/bin/bash", "-c", "--" ] + args: [ "while true; do sleep 300000; done;" ] diff --git a/doc/source/usertasks/kubernetes/bridge-plugin-7caa94024df4.rst b/doc/source/usertasks/kubernetes/bridge-plugin-7caa94024df4.rst new file mode 100644 index 000000000..b6e2d4624 --- /dev/null +++ b/doc/source/usertasks/kubernetes/bridge-plugin-7caa94024df4.rst @@ -0,0 +1,96 @@ +.. _bridge-plugin-7caa94024df4: + +============= +Bridge Plugin +============= + +The bridge plugin allows a virtual device to be created in the container that +is attached via a ``veth`` pair to a bridge on the host. If the bridge is not +already present, it will be created. This way, multiple pods on the same host +can achieve connectivity with each other. + +The following options are used to configure the plugin: + +``name`` (string, required) + The name of the network. + +``type`` (string, required) + ``bridge`` + +``bridge`` (string, optional) + The name of the bridge to use/create. Default: ``cni0``. + +``isGateway`` (boolean, optional) + Assign an IP address to the bridge. Default: ``false``. + +``isDefaultGateway`` (boolean, optional) + Sets isGateway to true and makes the assigned IP the default route. + Default: ``false``. + +``forceAddress`` (boolean, optional) + Indicates if a new IP address should be set if the previous value has been + changed. Default: false. + +``ipMasq`` (boolean, optional) + set up IP Masquerade on the host for traffic originating from this network + and destined outside of it. Default: ``false``. + +``mtu`` (integer, optional) + Set the |MTU| to the specified value. Default: chosen by the kernel. + +``hairpinMode`` (boolean, optional) + Set the hairpin mode for interfaces on the bridge. Default: ``false``. + +``ipam`` (dictionary, required) + The |IPAM| configuration to be used for this network. For an L2-only + network, create empty dictionary. + +``promiscMode`` (boolean, optional) + Set promiscuous mode on the bridge. Default: ``false``. + +``macspoofchk`` (boolean, optional) + Limits the traffic originating from the container to the |MAC| address of + the interface. Default: ``false``. + + +.. rubric:: |eg| + +The following example creates a pod containing an additional network +interface corresponding to a bridge device ``mybr0``. + +.. code-block:: yaml + + apiVersion: "k8s.cni.cncf.io/v1" + kind: NetworkAttachmentDefinition + metadata: + name: bridge0 + spec: + config: '{ + "cniVersion": "0.3.1", + "name": "bridgenet", + "type": "bridge", + "bridge": "mybr0", + "mtu": 1500, + "promiscMode": false, + "isGateway": false, + "ipam": { + "type": "host-local", + "subnet": "10.10.10.0/24" + } + }' + --- + apiVersion: v1 + kind: Pod + metadata: + name: bridgepod1 + annotations: + k8s.v1.cni.cncf.io/networks: '[ + { "name": "bridge0" } + ]' + spec: + containers: + - name: bridge0 + image: centos/tools + imagePullPolicy: IfNotPresent + command: [ "/bin/bash", "-c", "--" ] + args: [ "while true; do sleep 300000; done;" ] diff --git a/doc/source/usertasks/kubernetes/creating-network-attachment-definitions.rst b/doc/source/usertasks/kubernetes/creating-network-attachment-definitions.rst deleted file mode 100644 index 6d339df60..000000000 --- a/doc/source/usertasks/kubernetes/creating-network-attachment-definitions.rst +++ /dev/null @@ -1,195 +0,0 @@ - -.. uen1559067854074 -.. _creating-network-attachment-definitions: - -===================================== -Create Network Attachment Definitions -===================================== - -Network attachment definition specifications must be created in order to -reference / request an |SRIOV| interface in a container specification. - -.. rubric:: |context| - -The sample network attachments shown in this procedure can be used in a -container as shown in :ref:`Using Network Attachment Definitions in a Container -`. - -.. xreflink For information about PCI-SRIOV Interface Support, see the |datanet-doc|: - :ref:`` guide. - -.. rubric:: |prereq| - -You must have configured at least one |SRIOV| interface on a host with the -target datanetwork \(**datanet-a** or **datanet-b** in the example below\) -assigned to it before creating a **NetworkAttachmentDefinition** referencing -this data network. - -.. note:: - The configuration for this |SRIOV| interface with either a ``netdevice`` or - ``vfio`` vf-driver determines whether the **NetworkAttachmentDefinition** - will be a kernel network device or a DPDK network device. - -.. rubric:: |proc| - -.. _creating-network-attachment-definitions-steps-unordered-tbf-53z-hjb: - -#. Create a simple |SRIOV| network attachment definition file called net1.yaml - associated with the data network **datanet-a**. - - .. code-block:: yaml - - ~(keystone_admin)]$ cat < net1.yaml - apiVersion: "k8s.cni.cncf.io/v1" - kind: NetworkAttachmentDefinition - metadata: - name: net1 - annotations: - k8s.v1.cni.cncf.io/resourceName: intel.com/pci_sriov_net_datanet_a - spec: - config: '{ - "cniVersion": "0.3.0", - "type": "sriov" - }' - EOF - - - - This **NetworkAttachmentDefinition** is valid for both a kernel-based and - a DPDK \(vfio\) based device. - -#. Create an |SRIOV| network attachment. - - - The following example creates an |SRIOV| network attachment definition - configured for a VLAN with an ID of 2000. - - .. code-block:: none - - ~(keystone_admin)]$ cat < net2.yaml - apiVersion: "k8s.cni.cncf.io/v1" - kind: NetworkAttachmentDefinition - metadata: - name: net2 - annotations: - k8s.v1.cni.cncf.io/resourceName: intel.com/pci_sriov_net_datanet_b - spec: - config: '{ - "cniVersion": "0.3.0", - "type": "sriov", - "vlan": 2000 - }' - EOF - - - The following example creates an |SRIOV| network attachment definition - configured with IP Address information. - - .. code-block:: none - - ~(keystone_admin)]$ cat < net3.yaml - apiVersion: crd.projectcalico.org/v1 - kind: IPPool - metadata: - name: mypool - spec: - cidr: "10.56.219.0/24" - ipipMode: "Never" - natOutgoing: True - --- - apiVersion: "k8s.cni.cncf.io/v1" - kind: NetworkAttachmentDefinition - metadata: - name: net3 - annotations: - k8s.v1.cni.cncf.io/resourceName: intel.com/pci_sriov_net_datanet_b - spec: - config: '{ - "cniVersion": "0.3.0", - "type": "sriov", - "ipam": { - "type": "calico-ipam", - "assign_ipv4": "true", - "ipv4_pools": ["mypool"] - }, - "kubernetes": { - "kubeconfig": "/etc/cni/net.d/calico-kubeconfig" - }, - "datastore_type": "kubernetes" - }' - EOF - - - - The following example creates an |SRIOV| network attachment definition - configured with a static IP address and |MTU| of 1950. - - .. code-block:: none - - ~(keystone_admin)]$ cat < net4.yaml - apiVersion: k8s.cni.cncf.io/v1 - kind: NetworkAttachmentDefinition - metadata: - name: net4 - annotations: - k8s.v1.cni.cncf.io/resourceName: intel.com/pci_sriov_net_datanet_b - spec: - config: '{ - "cniVersion": "0.3.0", - "plugins": - [ - { - "type": "sriov", - "ipam": { - "type": "static", - "addresses": [ - { - "address": "192.168.1.2/16" - } - ] - } - }, - { - "type": "tuning", - "mtu": 1950 - } - ] - }' - EOF - -.. rubric:: |result| - -After |SRIOV| interfaces have been provisioned and the hosts labeled and -unlocked, available |SRIOV| VF resources are automatically advertised. - -They can be referenced in subsequent |prod| operations using the appropriate -**NetworkAttachmentDefinition** name and the following extended resource name: - -.. code-block:: none - - intel.com/pci_sriov_net_${DATANETWORK_NAME} - -For example, with a network called **datanet-a** the extended resource name -would be: - -.. xreflink as shown in |node-doc|: - :ref:`Provisioning SR-IOV Interfaces using the CLI - `, - -.. code-block:: none - - intel.com/pci_sriov_net_datanet_a - -.. _creating-network-attachment-definitions-ul-qjr-vnb-xhb: - -- The extended resource name will convert all dashes \('-'\) in the data - network name into underscores \('\_'\). - -- |SRIOV| enabled interfaces using the netdevice VF driver must be - administratively and operationally up to be advertised by the |SRIOV| - device plugin. - -- If multiple data networks are assigned to an interface, the VFs - resources will be shared between pools. - -.. seealso:: - - :ref:`Using Network Attachment Definitions in a Container - ` \ No newline at end of file diff --git a/doc/source/usertasks/kubernetes/host-device-plugin-714d4862a825.rst b/doc/source/usertasks/kubernetes/host-device-plugin-714d4862a825.rst new file mode 100644 index 000000000..b94be9b01 --- /dev/null +++ b/doc/source/usertasks/kubernetes/host-device-plugin-714d4862a825.rst @@ -0,0 +1,57 @@ +.. _host-device-plugin-714d4862a825: + +================== +Host-device Plugin +================== + +The host-device plugin allows a device on the host to be moved into the +container namespace as an additional interface. The device can be specified +with one of the following parameters: + +``device`` (string) + The device name. + +``hwaddr`` (string) + The |MAC| address of the device. + +``kernelpath`` (string) + The kernel device ``kobj``. For example: + ``/sys/devices/pci0000:00/0000:00:1f.6`` + +``pciBusID`` (string) + The |PCI| address of network device. For example, ``0000:00:1f.6`` + +.. rubric:: |eg| + +The following example would create a pod which contains an additional network +interface corresponding to the ``eth1000`` device: + +.. code-block:: yaml + + apiVersion: "k8s.cni.cncf.io/v1" + kind: NetworkAttachmentDefinition + metadata: + name: hd0 + spec: + config: '{ + "cniVersion": "0.3.1", + "name": "hd0", + "type": "host-device", + "device": "eth1000" + }' + --- + apiVersion: v1 + kind: Pod + metadata: + name: hdpod0 + annotations: + k8s.v1.cni.cncf.io/networks: '[ + { "name": "hd0" } + ]' + spec: + containers: + - name: hdpod0 + image: centos/tools + imagePullPolicy: IfNotPresent + command: [ "/bin/bash", "-c", "--" ] + args: [ "while true; do sleep 300000; done;" ] diff --git a/doc/source/usertasks/kubernetes/index-usertasks-kub-1291759aa985.rst b/doc/source/usertasks/kubernetes/index-usertasks-kub-1291759aa985.rst index de103b342..c6e520b62 100644 --- a/doc/source/usertasks/kubernetes/index-usertasks-kub-1291759aa985.rst +++ b/doc/source/usertasks/kubernetes/index-usertasks-kub-1291759aa985.rst @@ -157,26 +157,28 @@ Optimize application performance .. _add-sriov-interface-to-container: -------------------------------------- -Add an SRIOV interface to a container -------------------------------------- +-------------------------------------------------- +Add an Additional Network Interface to a Container +-------------------------------------------------- .. toctree:: - :maxdepth: 1 - - creating-network-attachment-definitions - using-network-attachment-definitions-in-a-container - - ------------------------ -Use the Bond CNI Plugin ------------------------ - -.. toctree:: - :maxdepth: 1 + :maxdepth: 2 + add-an-additional-network-interface-to-a-container-616bc5c5a6dd + sriov-plugin-4229f81b27ce + host-device-plugin-714d4862a825 + macvlan-plugin-e631cca21ffb + ipvlan-plugin-150be92d0538 + bridge-plugin-7caa94024df4 + ptp-plugin-bc6ed0498f4c + vlan-plugin-37938fe8578f + tuning-plugin-08f8cdbf1763 + bandwidth-plugin-3b8966c3fe47 + source-based-routing-plugin-51648f2ddff1 + virtual-routing-and-forwarding-plugin-0e53f2c2de21 integrate-the-bond-cni-plugin-2c2f14733b46 + -------------- Metrics Server -------------- diff --git a/doc/source/usertasks/kubernetes/integrate-the-bond-cni-plugin-2c2f14733b46.rst b/doc/source/usertasks/kubernetes/integrate-the-bond-cni-plugin-2c2f14733b46.rst index 138d02ec8..53fd4395d 100644 --- a/doc/source/usertasks/kubernetes/integrate-the-bond-cni-plugin-2c2f14733b46.rst +++ b/doc/source/usertasks/kubernetes/integrate-the-bond-cni-plugin-2c2f14733b46.rst @@ -1,8 +1,8 @@ .. _integrate-the-bond-cni-plugin-2c2f14733b46: -============================= -Integrate the Bond CNI Plugin -============================= +=========== +Bond Plugin +=========== The bond-cni plugin provides a method for aggregating multiple network interfaces into a single logical "bonded" interface. @@ -70,9 +70,9 @@ see: https://www.kernel.org/doc/Documentation/networking/bonding.txt ----------------------------------------------------------------------------- -Exampe: Launch a daemonset bonding two host interfaces in active-backup mode ----------------------------------------------------------------------------- +----------------------------------------------------------------------------- +Example: 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), diff --git a/doc/source/usertasks/kubernetes/ipvlan-plugin-150be92d0538.rst b/doc/source/usertasks/kubernetes/ipvlan-plugin-150be92d0538.rst new file mode 100644 index 000000000..db01ecb50 --- /dev/null +++ b/doc/source/usertasks/kubernetes/ipvlan-plugin-150be92d0538.rst @@ -0,0 +1,78 @@ +.. _ipvlan-plugin-150be92d0538: + +============= +Ipvlan Plugin +============= + +The Ipvlan plugin allows a virtual device that shares the physical capabilities +and connectivity of a device on the host to be created in the container. The +virtual device will have the same |MAC| address as the physical device. The +kernel directs traffic to and from the virtualized device based on the IP +address. + +The following options are used to configure the plugin: + +``name`` (string, required) + The name of the network. + +``type`` (string, required) + ``ipvlan`` + +``master`` (string, optional) + The name of the host interface to use. Default: the default route interface. + +``mode`` (string, optional) + One of ``l2``, ``l3``, ``l3s``. Default: ``l2``. + +``mtu`` (integer, optional) + Set the |MTU| to the specified value. Default: chosen by the kernel. + +``ipam`` (dictionary, required unless chained) + The |IPAM| configuration to be used for this network. + +.. rubric:: |eg| + +The following example would create a pod which contains an additional network +interface corresponding to an ``ipvlan`` device which uses the ``eth1000`` +interface on +the host: + +.. code-block:: yaml + + apiVersion: "k8s.cni.cncf.io/v1" + kind: NetworkAttachmentDefinition + metadata: + name: ipvlan0 + spec: + config: '{ + "cniVersion": "0.3.1", + "name": "ipvlan0", + "type": "ipvlan", + "master": "eth1000", + "mode": "l2", + "ipam": { + "type": "static", + "addresses": [ + { + "address": "10.10.10.2/24", + "gateway": "10.10.10.1" + } + ] + } + }' + --- + apiVersion: v1 + kind: Pod + metadata: + name: ipvpod0 + annotations: + k8s.v1.cni.cncf.io/networks: '[ + { "name": "ipvlan0" } + ]' + spec: + containers: + - name: ipv0 + image: centos/tools + imagePullPolicy: IfNotPresent + command: [ "/bin/bash", "-c", "--" ] + args: [ "while true; do sleep 300000; done;" ] diff --git a/doc/source/usertasks/kubernetes/macvlan-plugin-e631cca21ffb.rst b/doc/source/usertasks/kubernetes/macvlan-plugin-e631cca21ffb.rst new file mode 100644 index 000000000..bddcff175 --- /dev/null +++ b/doc/source/usertasks/kubernetes/macvlan-plugin-e631cca21ffb.rst @@ -0,0 +1,78 @@ +.. _macvlan-plugin-e631cca21ffb: + +============== +Macvlan Plugin +============== + +The Macvlan plugin allows a virtual device to be created in the container that +shares the physical capabilities and connectivity of a device on the host. The +virtual device will have a distinct |MAC| address from the physical device. As +such, multiple containers can share the device on the host. + +The following options are used to configure the plugin: + +``name`` (string, required) + The name of the network. + +``type`` (string, required) + ``macvlan`` + +``master`` (string, optional) + The name of the host interface to use. Default: default route interface. + +``mode`` (string, optional) + One of “bridge”, “private”, “vepa”, “passthru”. Default: “bridge”. + +``mtu`` (integer, optional) + Set |MTU| to the specified value. Default: the value chosen by the kernel. + +``ipam`` (dictionary, required) + The |IPAM| configuration to be used for this network. For an interface + without ip address use an empty dictionary. + +.. rubric:: |eg| + +The following example would create a pod which contains an additional network +interface corresponding to a ``macvlan`` device which uses the ``eth1000`` +interface on the host: + +.. code-block:: yaml + + apiVersion: "k8s.cni.cncf.io/v1" + kind: NetworkAttachmentDefinition + metadata: + name: macvlan0 + spec: + config: '{ + "cniVersion": "0.3.1", + "name": "macvlan0", + "type": "macvlan", + "master": "eth1000", + "mode": "bridge", + "ipam": { + "type": "static", + "addresses": [ + { + "address": "10.10.10.1/24", + "gateway": "10.10.10.2" + } + ] + } + }' + --- + apiVersion: v1 + kind: Pod + metadata: + name: mvpod0 + annotations: + k8s.v1.cni.cncf.io/networks: '[ + { "name": "macvlan0" } + ]' + spec: + containers: + - name: mv0 + image: centos/tools + imagePullPolicy: IfNotPresent + command: [ "/bin/bash", "-c", "--" ] + args: [ "while true; do sleep 300000; done;" ] + diff --git a/doc/source/usertasks/kubernetes/ptp-plugin-bc6ed0498f4c.rst b/doc/source/usertasks/kubernetes/ptp-plugin-bc6ed0498f4c.rst new file mode 100644 index 000000000..143bd69e5 --- /dev/null +++ b/doc/source/usertasks/kubernetes/ptp-plugin-bc6ed0498f4c.rst @@ -0,0 +1,72 @@ +.. _ptp-plugin-bc6ed0498f4c: + +===================== +Point-to-Point Plugin +===================== + +The |PTP| plugin allows a virtual device that is attached to a virtual +interface in the host to be created in the container. + +The following options are used to configure the plugin: + +``name`` (string, required) + The name of the network. + +``type`` (string, required) + ``ptp`` + +``ipMasq`` (boolean, optional) + Set up IP Masquerade on the host for traffic originating from the IP + address of this network and destined outside of this network. Default: + false. + +``mtu`` (integer, optional) + Set the |MTU| to the specified value. Default: chosen by the kernel. + +``ipam`` (dictionary, required) + The |IPAM| configuration to be used for this network. For an interface + without an IP address, use an empty dictionary. + + +.. rubric:: |eg| + +The following example creates a pod containing an additional network +interface corresponding to a point-to-point interface. + +.. code-block:: yaml + + apiVersion: "k8s.cni.cncf.io/v1" + kind: NetworkAttachmentDefinition + metadata: + name: ptp0 + spec: + config: '{ + "cniVersion": "0.3.1", + "name": "ptp0", + "type": "ptp", + "ipam": { + "type": "static", + "addresses": [ + { + "address": "10.10.10.2/24", + "gateway": "10.10.10.1" + } + ] + } + }' + --- + apiVersion: v1 + kind: Pod + metadata: + name: ptppod0 + annotations: + k8s.v1.cni.cncf.io/networks: '[ + { "name": "ptp0" } + ]' + spec: + containers: + - name: ptp1 + image: centos/tools + imagePullPolicy: IfNotPresent + command: [ "/bin/bash", "-c", "--" ] + args: [ "while true; do sleep 300000; done;" ] \ No newline at end of file diff --git a/doc/source/usertasks/kubernetes/source-based-routing-plugin-51648f2ddff1.rst b/doc/source/usertasks/kubernetes/source-based-routing-plugin-51648f2ddff1.rst new file mode 100644 index 000000000..9a6f2bc74 --- /dev/null +++ b/doc/source/usertasks/kubernetes/source-based-routing-plugin-51648f2ddff1.rst @@ -0,0 +1,222 @@ +.. _source-based-routing-plugin-51648f2ddff1: + +=========================== +Source-Based Routing Plugin +=========================== + +The |SBR| plugin enables source based routing on an interface. It must be used +as a chained plugin in conjunction with another interface-creating plugin. + +The following options are used to configure the plugin: + +``name`` (string, optional) + The name of the network. + +``type`` (string, required) + ``sbr`` + +.. rubric:: |eg| + +The following example creates a pod with an additional bridge interface which +has |SBR| enabled. There is also a demonstration pod without |SBR| enabled and +an ``iperf`` server pod. Note the chained nature of the plugins. + +.. code-block:: yaml + + apiVersion: "k8s.cni.cncf.io/v1" + kind: NetworkAttachmentDefinition + metadata: + name: sbrnet1 + spec: + config: '{ + "cniVersion": "0.3.1", + "name": "sbrnet", + "plugins": [ + { + "type": "bridge", + "bridge": "mybr0", + "ipam": { + "type": "static", + "addresses" : [ + { + "address": "10.10.10.98/24", + "gateway": "10.10.10.254" + } + ] + } + }, + { + "name": "brsbr", + "type": "sbr" + } + ] + + }' + --- + apiVersion: "k8s.cni.cncf.io/v1" + kind: NetworkAttachmentDefinition + metadata: + name: nosbrnet1 + spec: + config: '{ + "cniVersion": "0.3.1", + "type": "bridge", + "bridge": "mybr0", + "ipam": { + "type": "static", + "addresses" : [ + { + "address": "10.10.10.99/24", + "gateway": "10.10.10.254" + } + ] + } + }' + --- + apiVersion: "k8s.cni.cncf.io/v1" + kind: NetworkAttachmentDefinition + metadata: + name: iperfservernet0 + spec: + config: '{ + "cniVersion": "0.3.1", + "type": "bridge", + "bridge": "mybr0", + "ipam": { + "type": "static", + "addresses" : [ + { + "address": "10.10.10.254/24" + } + ] + } + }' + --- + apiVersion: "k8s.cni.cncf.io/v1" + kind: NetworkAttachmentDefinition + metadata: + name: iperfservernet1 + spec: + config: '{ + "cniVersion": "0.3.1", + "type": "bridge", + "bridge": "mybr1", + "ipam": { + "type": "static", + "addresses" : [ + { + "address": "20.20.20.254/24" + } + ] + } + }' + --- + apiVersion: v1 + kind: Pod + metadata: + name: sbrpod1 + annotations: + k8s.v1.cni.cncf.io/networks: '[ + { "name": "sbrnet1" } + ]' + spec: + containers: + - name: sbr1 + image: praqma/network-multitool:extra + imagePullPolicy: IfNotPresent + command: [ "/bin/bash", "-c", "--" ] + args: [ "while true; do sleep 300000; done;" ] + --- + apiVersion: v1 + kind: Pod + metadata: + name: nosbrpod1 + annotations: + k8s.v1.cni.cncf.io/networks: '[ + { "name": "nosbrnet1" } + ]' + spec: + containers: + - name: sbr2 + image: praqma/network-multitool:extra + imagePullPolicy: IfNotPresent + command: [ "/bin/bash", "-c", "--" ] + args: [ "while true; do sleep 300000; done;" ] + --- + apiVersion: v1 + kind: Pod + metadata: + name: iperfserverpod1 + annotations: + k8s.v1.cni.cncf.io/networks: '[ + { "name": "iperfservernet0" }, + { "name": "iperfservernet1" } + ]' + spec: + containers: + - name: iperfserver1 + image: praqma/network-multitool:extra + imagePullPolicy: IfNotPresent + command: [ "/bin/bash", "-c", "--" ] + args: [ "while true; do sleep 300000; done;" ] + +.. note:: + + The default table number will be 100. One can see the result of the |SBR| + plugin below. For an application to use source-based routing, it would + bind its socket to the source address, causing the routes in the + corresponding table to be used (rather than the default routes). + +.. rubric:: **Related commands** + +* Show the default routing table. + + .. code-block:: none + + kubectl exec -it sbrpod1 -- ip route show + default via 169.254.1.1 dev eth0 + 169.254.1.1 dev eth0 scope link + +* Show the table created by |SBR|. + + .. code-block:: none + + kubectl exec -it sbrpod1 -- ip rule list + + 0: from all lookup local + 32765: from 10.10.10.98 lookup 100 <---------- + 32766: from all lookup main + 32767: from all lookup default + +* Show the contents of table 100. + + .. code-block:: none + + kubectl exec -it sbrpod1 -- ip route show table 100 + + default via 10.10.10.254 dev net1 + 10.10.10.0/24 dev net1 proto kernel scope link src 10.10.10.98 + +* Start the iperf server. + + .. code-block:: none + + kubectl exec -it iperfserverpod1 -- iperf3 -s -B 20.20.20.254 + +* Example of failure to connect from a pod without source based routing. + + .. code-block:: none + + kubectl exec -it nosbrpod1 -- iperf3 -c 20.20.20.254 -B 10.10.10.99 -k 1 + +* Example of failure to connect without binding to the source address. + + .. code-block:: none + + kubectl exec -it sbrpod1 -- iperf3 -c 20.20.20.254 -k 1 + +* Example of connection success for application binding to the source address. + + .. code-block:: none + + kubectl exec -it sbrpod1 -- iperf3 -c 20.20.20.254 -B 10.10.10.98 -k 1 diff --git a/doc/source/usertasks/kubernetes/sriov-plugin-4229f81b27ce.rst b/doc/source/usertasks/kubernetes/sriov-plugin-4229f81b27ce.rst new file mode 100644 index 000000000..6d0e9dcce --- /dev/null +++ b/doc/source/usertasks/kubernetes/sriov-plugin-4229f81b27ce.rst @@ -0,0 +1,452 @@ +.. uen1559067854074 +.. _sriov-plugin-4229f81b27ce: + + +============= +SR-IOV plugin +============= + + +.. contents:: |minitoc| + :local: + :depth: 1 + + +.. _creating-network-attachment-definitions: + +------------------------------------- +Create Network Attachment Definitions +------------------------------------- + +Network attachment definition specifications must be created in order to +reference / request an |SRIOV| interface in a container specification. + +.. rubric:: |context| + +The sample network attachments shown in this procedure can be used in a +container as shown in :ref:`Use Network Attachment Definitions in a Container +`. + +.. xreflink For information about PCI-SRIOV Interface Support, see the |datanet-doc|: + :ref:`` guide. + +.. rubric:: |prereq| + +You must have configured at least one |SRIOV| interface on a host with the +target datanetwork \(``datanet-a`` or ``datanet-b`` in the example below\) +assigned to it before creating a ``NetworkAttachmentDefinition`` referencing +this data network. + +.. note:: + + The configuration for this |SRIOV| interface with either a ``netdevice`` or + a user space network device such as a |DPDK| poll mode drive. + +.. note:: + + Mellanox-based interfaces should be bound to the ``netdevice`` vf-driver for + both kernel and user space usage. + +After |SRIOV| interfaces have been provisioned and the hosts labeled and +unlocked, available |SRIOV| |VF| resources are automatically advertised. + +They can be referenced in subsequent |prod| operations using the appropriate +``NetworkAttachmentDefinition`` name and the following extended resource name: + +.. code-block:: none + + intel.com/pci_sriov_net_${DATANETWORK_NAME} + +For example, with a network called ``datanet-a`` the extended resource name +would be: + +.. xreflink as shown in |node-doc|: + :ref:`Provisioning SR-IOV Interfaces using the CLI + `, + +.. code-block:: none + + intel.com/pci_sriov_net_datanet_a + +.. _creating-network-attachment-definitions-ul-qjr-vnb-xhb: + +- The extended resource name will convert all dashes \('-'\) in the data + network name into underscores \('\_'\). + +- |SRIOV| enabled interfaces using the netdevice VF driver must be + administratively and operationally up to be advertised by the |SRIOV| + device plugin. + +- If multiple data networks are assigned to an interface, the |VFs| + resources will be shared between pools. + + +.. rubric:: |proc| + +.. _creating-network-attachment-definitions-steps-unordered-tbf-53z-hjb: + +#. Create a simple |SRIOV| network attachment definition file called + ``net1.yaml`` associated with the data network ``datanet-a``. + + .. code-block:: yaml + + ~(keystone_admin)]$ cat < net1.yaml + apiVersion: "k8s.cni.cncf.io/v1" + kind: NetworkAttachmentDefinition + metadata: + name: net1 + annotations: + k8s.v1.cni.cncf.io/resourceName: intel.com/pci_sriov_net_datanet_a + spec: + config: '{ + "cniVersion": "0.3.0", + "type": "sriov" + }' + EOF + + + + This ``NetworkAttachmentDefinition`` is valid for both a kernel-based and + a |DPDK| \(vfio\) based device. + +#. Create an |SRIOV| network attachment with a VLAN ID or with IP Address information. + + - The following example creates an |SRIOV| network attachment definition + configured for a |VLAN| with an ID of 2000. + + .. code-block:: none + + ~(keystone_admin)]$ cat < net2.yaml + apiVersion: "k8s.cni.cncf.io/v1" + kind: NetworkAttachmentDefinition + metadata: + name: net2 + annotations: + k8s.v1.cni.cncf.io/resourceName: intel.com/pci_sriov_net_datanet_b + spec: + config: '{ + "cniVersion": "0.3.0", + "type": "sriov", + "vlan": 2000 + }' + EOF + + - The following example creates an |SRIOV| network attachment definition + configured with IP Address information. + + .. code-block:: none + + ~(keystone_admin)]$ cat < net3.yaml + apiVersion: crd.projectcalico.org/v1 + kind: IPPool + metadata: + name: mypool + spec: + cidr: "10.56.219.0/24" + ipipMode: "Never" + natOutgoing: True + --- + apiVersion: "k8s.cni.cncf.io/v1" + kind: NetworkAttachmentDefinition + metadata: + name: net3 + annotations: + k8s.v1.cni.cncf.io/resourceName: intel.com/pci_sriov_net_datanet_b + spec: + config: '{ + "cniVersion": "0.3.0", + "type": "sriov", + "ipam": { + "type": "calico-ipam", + "assign_ipv4": "true", + "ipv4_pools": ["mypool"] + }, + "kubernetes": { + "kubeconfig": "/etc/cni/net.d/calico-kubeconfig" + }, + "datastore_type": "kubernetes" + }' + EOF + + + +.. ulm1559068249625 +.. _using-network-attachment-definitions-in-a-container: + +------------------------------------------------- +Use Network Attachment Definitions in a Container +------------------------------------------------- + +Network attachment definitions can be referenced by name when creating a +container. The extended resource name of the |SRIOV| pool should also be +referenced in the resource requests. + +.. rubric:: |context| + +The following examples use network attachment definitions ``net2`` and ``net3`` +created in :ref:`Creating Network Attachment Definitions +`. + +As shown in these examples, it is important that you request the same number of +devices as you have network annotations. + +.. only:: partner + + .. include:: /_includes/using-network-attachment-definitions-in-a-container.rest + +.. xreflink For information about PCI-SRIOV Interface Support, see the :ref:`|datanet-doc| + ` guide. + +.. rubric:: |proc| + +.. _using-network-attachment-definitions-in-a-container-steps-j2n-zqz-hjb: + +#. Create a container with one additional |SRIOV| interface using the ``net2`` + network attachment definition. + + #. Populate the configuration file ``pod1.yaml`` with the following + contents. + + .. code-block:: yaml + + apiVersion: v1 + kind: Pod + metadata: + name: pod1 + annotations: + k8s.v1.cni.cncf.io/networks: '[ + { "name": "net2", "interface": "sriov0" } + ]' + spec: + containers: + - name: pod1 + image: centos/tools + imagePullPolicy: IfNotPresent + command: [ "/bin/bash", "-c", "--" ] + args: [ "while true; do sleep 300000; done;" ] + resources: + requests: + intel.com/pci_sriov_net_datanet_b: '1' + limits: + intel.com/pci_sriov_net_datanet_b: '1' + + #. Apply the configuration to create the container. + + .. code-block:: none + + ~(keystone_admin)]$ kubectl create -f pod1.yaml + pod/pod1 created + + After creating the container, an extra network device interface, ``net2``, + which uses one |SRIOV| |VF|, will appear in the associated container\(s\). + + After creating the container, the interface ``sriov0``, which uses one + |SRIOV| |VF| will appear. + + At this point you can execute commands and review links on the container. + For example: + + .. code-block:: + + $ kubectl exec -n default -it pod1 -- ip link show + +#. Create a container with two additional |SRIOV| interfaces using the ``net2`` + network attachment definition. + + #. Populate the configuration file ``pod2.yaml`` with the following + contents. + + .. code-block:: yaml + + apiVersion: v1 + kind: Pod + metadata: + name: pod2 + annotations: + k8s.v1.cni.cncf.io/networks: '[ + { "name": "net2", "interface": "sriov0" }, + { "name": "net2", "interface": "sriov1" } + ]' + spec: + containers: + - name: pod2 + image: centos/tools + imagePullPolicy: IfNotPresent + command: [ "/bin/bash", "-c", "--" ] + args: [ "while true; do sleep 300000; done;" ] + resources: + requests: + intel.com/pci_sriov_net_datanet_b: '2' + limits: + intel.com/pci_sriov_net_datanet_b: '2' + + #. Apply the configuration to create the container. + + .. code-block:: none + + ~(keystone_admin)$ kubectl create -f pod2.yaml + pod/pod2 created + + After creating the container, two ``net2`` network device interfaces, which + each use one |SRIOV| |VF|, will appear in the associated container\(s\). + + After creating the container, the network device interfaces ``sriov0`` and + ``sriov0``, which uses one |SRIOV| |VF|, will appear in the associated + container\(s\). + + At this point you can execute commands and review links on the container. + For example: + + .. code-block:: + + $ kubectl exec -n default -it pod2 -- ip link show + +#. Create a container with two additional |SRIOV| interfaces using the + ``net2`` and ``net3`` network attachment definitions. + + #. Populate the configuration file ``pod3.yaml`` with the following + contents. + + .. code-block:: yaml + + apiVersion: v1 + kind: Pod + metadata: + name: pod3 + annotations: + k8s.v1.cni.cncf.io/networks: '[ + { "name": "net2", "interface": "sriov0" } + { "name": "net3", "interface": "sriov0" } + ]' + spec: + containers: + - name: pod3 + image: centos/tools + imagePullPolicy: IfNotPresent + command: [ "/bin/bash", "-c", "--" ] + args: [ "while true; do sleep 300000; done;" ] + resources: + requests: + intel.com/pci_sriov_net_datanet_b: '2' + limits: + intel.com/pci_sriov_net_datanet_b: '2' + + #. Apply the configuration to create the container. + + .. code-block:: none + + ~(keystone_admin)$ kubectl create -f pod3.yaml + + ``net2`` and ``net3`` will each take a device from the + ``pci_sriov_net_datanet_b`` pool and be configured on the + container/host based on the their respective + ``NetworkAttachmentDefinition`` specifications \(see :ref:`Creating Network + Attachment Definitions `\). + + After creating the pod, the network device interface ``sriov0``, which uses + one |SRIOV| |VF|, will appear in the associated container\(s\). + + After creating the container, network device interfaces ``net2`` and + ``net3``, which each use one |SRIOV| |VF|, will appear in the associated + container\(s\). + + At this point you can execute commands and review links on the container. + For example: + + .. code-block:: + + $ kubectl exec -n default -it pod3 -- ip link show + + .. note:: + + In the above examples, the |PCI| addresses allocated to the container + are exported via an environment variable. For example: + + .. code-block:: none + + ~(keystone_admin)$ kubectl exec -n default -it pod3 -- printenv + PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin + HOSTNAME=pod3 + TERM=xterm + PCIDEVICE_INTEL_COM_PCI_SRIOV_NET_DATANET_B=0000:81:0e.4,0000:81:0e.0 + KUBERNETES_PORT_443_TCP_PROTO=tcp + KUBERNETES_PORT_443_TCP_PORT=443 + KUBERNETES_PORT_443_TCP_ADDR=10.96.0.1 + KUBERNETES_SERVICE_HOST=10.96.0.1 + KUBERNETES_SERVICE_PORT=443 + KUBERNETES_SERVICE_PORT_HTTPS=443 + KUBERNETES_PORT=tcp://10.96.0.1:443 + KUBERNETES_PORT_443_TCP=tcp://10.96.0.1:443 + container=docker + HOME=/root + +#. Create a container with two additional |SRIOV| interfaces using the ``net1`` + network attachment definition for a |DPDK| based application. + + The configuration of the |SRIOV| host interface to which the datanetwork is + assigned determines whether the network attachment in the container will be + kernel or |DPDK|-based. The |SRIOV| host interface needs to be created with + a vfio ``vf-driver`` for the network attachment in the container to be + |DPDK|-based, otherwise it will be kernel-based. + + .. note:: + + Mellanox based NICs should be bound to a netdevice (default) + ``vf-driver``. + + #. Populate the configuration file ``pod4.yaml`` with the following + contents. + + .. code-block:: yaml + + apiVersion: v1 + kind: Pod + metadata: + name: testpmd + annotations: + k8s.v1.cni.cncf.io/networks: '[ + { "name": "net1" }, + { "name": "net1" } + ]' + spec: + restartPolicy: Never + containers: + - name: testpmd + image: "amirzei/mlnx_docker_dpdk:ubuntu16.04" + volumeMounts: + - mountPath: /mnt/huge-1048576kB + name: hugepage + stdin: true + tty: true + securityContext: + privileged: false + capabilities: + add: ["IPC_LOCK", "NET_ADMIN", "NET_RAW"] + resources: + requests: + memory: 10Gi + intel.com/pci_sriov_net_datanet_a: '2' + limits: + hugepages-1Gi: 4Gi + memory: 10Gi + intel.com/pci_sriov_net_datanet_a: '2' + volumes: + - name: hugepage + emptyDir: + medium: HugePages + + .. note:: + You must convert any dashes \(-\) in the datanetwork name used in + the ``NetworkAttachmentDefinition`` to underscores \(\_\). + + #. Apply the configuration to create the container. + + .. code-block:: none + + ~(keystone_admin)$ kubectl create -f pod4.yaml + pod/testpmd created + +.. note:: + For applications backed by Mellanox NICs, privileged mode is required in + the pod's security context. For Intel i40e based NICs bound to vfio, + privileged mode is not required. diff --git a/doc/source/usertasks/kubernetes/tuning-plugin-08f8cdbf1763.rst b/doc/source/usertasks/kubernetes/tuning-plugin-08f8cdbf1763.rst new file mode 100644 index 000000000..c37086ee8 --- /dev/null +++ b/doc/source/usertasks/kubernetes/tuning-plugin-08f8cdbf1763.rst @@ -0,0 +1,88 @@ +.. _tuning-plugin-08f8cdbf1763: + +============= +Tuning Plugin +============= + +The tuning plugin can change some system controls (``sysctls``) and interface +attributes. It must be used as a chained plugin in conjunction with another +interface-creating plugin. + +The following options are used to configure the plugin: + +``name`` (string, required) + The name of the network. + +``type`` (string, required) + ``tuning`` + +``mac`` (string, optional) + Set the ``MAC`` address of the interface. + +`mtu` (integer, optional) + Set the ``MTU`` of the interface. + +``promisc`` (bool, optional) + Set the promiscuous mode of interface. + +``allmulti`` (bool, optional) + Set the all-multicast mode of interface. If enabled, all multicast packets + on the network will be received by the interface. + +``sysctl`` (object, optional) + Change ``sysctls`` in the network namespace. + + +.. rubric:: |eg| + +The following example creates a pod with an additional bridge interface which +has its |MTU|, |MAC|, promiscuous mode, ``allmulti`` mode, and ``ipforwarding`` +values changed by the tuning plugin. Note the chained nature of the plugins. + +.. code-block:: yaml + + kind: NetworkAttachmentDefinitionapiVersion: "k8s.cni.cncf.io/v1" + metadata: + name: bridge1 + spec: + config: '{ + "cniVersion": "0.3.1", + "name": "bridgenet", + "plugins": [ + { + "type": "bridge", + "bridge": "mybr0", + "ipam": { + "type": "host-local", + "subnet": "10.10.10.0/24" + } + }, + { + "name": "brtuning", + "type": "tuning", + "sysctl": { + "net.ipv4.conf.net1.forwarding": "1" + }, + "mtu": 9000, + "mac": "c2:b0:57:49:47:f1", + "promisc": true, + "allmulti": true + } + ] + }' + --- + apiVersion: v1 + kind: Pod + metadata: + name: bridgepod1 + annotations: + k8s.v1.cni.cncf.io/networks: '[ + { "name": "bridge1" } + ]' + spec: + containers: + - name: bridge1 + image: centos/tools + imagePullPolicy: IfNotPresent + command: [ "/bin/bash", "-c", "--" ] + args: [ "while true; do sleep 300000; done;" ] diff --git a/doc/source/usertasks/kubernetes/using-network-attachment-definitions-in-a-container.rst b/doc/source/usertasks/kubernetes/using-network-attachment-definitions-in-a-container.rst deleted file mode 100644 index a76b4ff5b..000000000 --- a/doc/source/usertasks/kubernetes/using-network-attachment-definitions-in-a-container.rst +++ /dev/null @@ -1,241 +0,0 @@ - -.. ulm1559068249625 -.. _using-network-attachment-definitions-in-a-container: - -================================================= -Use Network Attachment Definitions in a Container -================================================= - -Network attachment definitions can be referenced by name when creating a -container. The extended resource name of the SR-IOV pool should also be -referenced in the resource requests. - -.. rubric:: |context| - -The following examples use network attachment definitions **net2** and **net3** -created in :ref:`Creating Network Attachment Definitions -`. - -As shown in these examples, it is important that you request the same number of -devices as you have network annotations. - -.. only:: partner - - .. include:: /_includes/using-network-attachment-definitions-in-a-container.rest - -.. xreflink For information about PCI-SRIOV Interface Support, see the :ref:`|datanet-doc| - ` guide. - -.. rubric:: |proc| - -.. _using-network-attachment-definitions-in-a-container-steps-j2n-zqz-hjb: - -#. Create a container with one additional SR-IOV interface using the **net2** - network attachment definition. - - #. Populate the configuration file pod1.yaml with the following contents. - - .. code-block:: yaml - - apiVersion: v1 - kind: Pod - metadata: - name: pod1 - annotations: - k8s.v1.cni.cncf.io/networks: '[ - { "name": "net2" }, - { "name": "net2" } - ]' - spec: - containers: - - name: pod1 - image: centos/tools - imagePullPolicy: IfNotPresent - command: [ "/bin/bash", "-c", "--" ] - args: [ "while true; do sleep 300000; done;" ] - resources: - requests: - intel.com/pci_sriov_net_datanet_b: '1' - limits: - intel.com/pci_sriov_net_datanet_b: '1' - - #. Apply the configuration to create the container. - - .. code-block:: none - - ~(keystone_admin)]$ kubectl create -f pod1.yaml - pod/pod1 created - - After creating the container, an extra network device interface, **net2**, - which uses one SR-IOV VF, will appear in the associated container\(s\). - -#. Create a container with two additional SR-IOV interfaces using the **net2** - network attachment definition. - - #. Populate the configuration file pod2.yaml with the following contents. - - .. code-block:: yaml - - apiVersion: v1 - kind: Pod - metadata: - name: pod2 - annotations: - k8s.v1.cni.cncf.io/networks: '[ - { "name": "net2" } - ]' - spec: - containers: - - name: pod2 - image: centos/tools - imagePullPolicy: IfNotPresent - command: [ "/bin/bash", "-c", "--" ] - args: [ "while true; do sleep 300000; done;" ] - resources: - requests: - intel.com/pci_sriov_net_datanet_b: '2' - limits: - intel.com/pci_sriov_net_datanet_b: '2' - - #. Apply the configuration to create the container. - - .. code-block:: none - - ~(keystone_admin)$ kubectl create -f pod2.yaml - pod/pod2 created - - After creating the container, network device interfaces **net2** and - **net3**, which each use one SR-IOV VF, will appear in the associated - container\(s\). - -#. Create a container with two additional SR-IOV interfaces using the **net2** - and **net3** network attachment definitions. - - #. Populate the configuration file pod3.yaml with the following contents. - - .. code-block:: yaml - - apiVersion: v1 - kind: Pod - metadata: - name: pod3 - annotations: - k8s.v1.cni.cncf.io/networks: '[ - { "name": "net2" }, - { "name": "net3" } - ]' - spec: - containers: - - name: pod3 - image: centos/tools - imagePullPolicy: IfNotPresent - command: [ "/bin/bash", "-c", "--" ] - args: [ "while true; do sleep 300000; done;" ] - resources: - requests: - intel.com/pci_sriov_net_datanet_b: '2' - limits: - intel.com/pci_sriov_net_datanet_b: '2' - - #. Apply the configuration to create the container. - - .. code-block:: none - - ~(keystone_admin)$ kubectl create -f pod3.yaml - - **net2** and **net3** will each take a device from the - **pci\_sriov\_net\_datanet\_b** pool and be configured on the - container/host based on the their respective - **NetworkAttachmentDefinition** specifications \(see :ref:`Creating Network - Attachment Definitions `\). - - After creating the container, network device interfaces **net2** and - **net3**, which each use one SR-IOV VF, will appear in the associated - container\(s\). - - .. note:: - In the above examples, the PCI addresses allocated to the container are - exported via an environment variable. For example: - - .. code-block:: none - - ~(keystone_admin)$ kubectl exec -n default -it pod3 -- printenv - PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin - HOSTNAME=pod3 - TERM=xterm - PCIDEVICE_INTEL_COM_PCI_SRIOV_NET_DATANET_B=0000:81:0e.4,0000:81:0e.0 - KUBERNETES_PORT_443_TCP_PROTO=tcp - KUBERNETES_PORT_443_TCP_PORT=443 - KUBERNETES_PORT_443_TCP_ADDR=10.96.0.1 - KUBERNETES_SERVICE_HOST=10.96.0.1 - KUBERNETES_SERVICE_PORT=443 - KUBERNETES_SERVICE_PORT_HTTPS=443 - KUBERNETES_PORT=tcp://10.96.0.1:443 - KUBERNETES_PORT_443_TCP=tcp://10.96.0.1:443 - container=docker - HOME=/root - -#. Create a container with two additional SR-IOV interfaces using the **net1** - network attachment definition for a DPDK based application. - - The configuration of the SR-IOV host interface to which the datanetwork is - assigned determines whether the network attachment in the container will be - kernel or dpdk-based. The SR-IOV host interface needs to be created with a - vfio **vf-driver** for the network attachment in the container to be - dpdk-based, otherwise it will be kernel-based. - - #. Populate the configuration file pod4.yaml with the following contents. - - .. code-block:: yaml - - apiVersion: v1 - kind: Pod - metadata: - name: testpmd - annotations: - k8s.v1.cni.cncf.io/networks: '[ - { "name": "net1" }, - { "name": "net1" } - ]' - spec: - restartPolicy: Never - containers: - - name: testpmd - image: "amirzei/mlnx_docker_dpdk:ubuntu16.04" - volumeMounts: - - mountPath: /mnt/huge-1048576kB - name: hugepage - stdin: true - tty: true - securityContext: - privileged: false - capabilities: - add: ["IPC_LOCK", "NET_ADMIN", "NET_RAW"] - resources: - requests: - memory: 10Gi - intel.com/pci_sriov_net_datanet_a: '2' - limits: - hugepages-1Gi: 4Gi - memory: 10Gi - intel.com/pci_sriov_net_datanet_a: '2' - volumes: - - name: hugepage - emptyDir: - medium: HugePages - - .. note:: - You must convert any dashes \(-\) in the datanetwork name used in - the NetworkAttachmentDefinition to underscores \(\_\). - - #. Apply the configuration to create the container. - - .. code-block:: none - - ~(keystone_admin)$ kubectl create -f pod4.yaml - pod/testpmd created - -.. note:: - For applications backed by Mellanox NICs, privileged mode is required in - the pod's security context. For Intel i40e based NICs bound to vfio, - privileged mode is not required. diff --git a/doc/source/usertasks/kubernetes/virtual-routing-and-forwarding-plugin-0e53f2c2de21.rst b/doc/source/usertasks/kubernetes/virtual-routing-and-forwarding-plugin-0e53f2c2de21.rst new file mode 100644 index 000000000..55a99eec8 --- /dev/null +++ b/doc/source/usertasks/kubernetes/virtual-routing-and-forwarding-plugin-0e53f2c2de21.rst @@ -0,0 +1,373 @@ +.. _virtual-routing-and-forwarding-plugin-0e53f2c2de21: + +===================================== +Virtual Routing and Forwarding Plugin +===================================== + +The |VRF| plugin enables virtual routing and forwarding in the network +namespace of the container and assigns it an interface. It must be used as a +chained plugin in conjunction with another interface-creating plugin. + +See https://www.kernel.org/doc/Documentation/networking/vrf.txt for more +information. + +The following options are used to configure the plugin: + +``vrfname`` (string, required) + The name of the network. + +``type`` (string, required) + ``vrf`` + +.. rubric:: |eg| + +The following example creates a pod with an additional bridge interface that +has two |VRFs| enabled (blue and red). There are also two demonstration router +pods and a demonstration endpoint pod. Note the chained nature of the plugins +and the usage of the tuning plugin to enable forwarding in the router pods. + +.. code-block:: yaml + + apiVersion: "k8s.cni.cncf.io/v1" + kind: NetworkAttachmentDefinition + metadata: + name: bluenet1 + spec: + config: '{ + "cniVersion": "0.3.1", + "name": "bluenet1", + "plugins": [ + { + "type": "bridge", + "bridge": "mybr0", + "ipam": { + "type": "static", + "addresses" : [ + { + "address": "10.10.10.2/24", + "gateway": "10.10.10.1" + } + ] + } + }, + { + "type": "vrf", + "vrfname": "blue" + } + ] + + }' + --- + apiVersion: "k8s.cni.cncf.io/v1" + kind: NetworkAttachmentDefinition + metadata: + name: bluerouter1 + spec: + config: '{ + "cniVersion": "0.3.1", + "name": "bluerouter1", + "plugins": [ + { + "type": "bridge", + "bridge": "mybr0", + "ipam": { + "type": "static", + "addresses" : [ + { + "address": "10.10.10.1/24" + } + ] + } + }, + { + "name": "brtuning", + "type": "tuning", + "sysctl": { + "net.ipv4.conf.net1.forwarding": "1" + } + } + ] + + }' + --- + apiVersion: "k8s.cni.cncf.io/v1" + kind: NetworkAttachmentDefinition + metadata: + name: bluerouter2 + spec: + config: '{ + "cniVersion": "0.3.1", + "name": "bluerouter2", + "plugins": [ + { + "type": "bridge", + "bridge": "mybr1", + "ipam": { + "type": "static", + "addresses" : [ + { + "address": "20.20.20.1/24" + } + ] + } + }, + { + "name": "brtuning", + "type": "tuning", + "sysctl": { + "net.ipv4.conf.net2.forwarding": "1" + } + } + ] + + }' + --- + apiVersion: "k8s.cni.cncf.io/v1" + kind: NetworkAttachmentDefinition + metadata: + name: rednet1 + spec: + config: '{ + "cniVersion": "0.3.1", + "name": "rednet1", + "plugins": [ + { + "type": "bridge", + "bridge": "mybr0", + "ipam": { + "type": "static", + "addresses" : [ + { + "address": "10.10.10.2/24", + "gateway": "10.10.10.254" + } + ] + } + }, + { + "type": "vrf", + "vrfname": "red" + } + ] + + }' + --- + apiVersion: "k8s.cni.cncf.io/v1" + kind: NetworkAttachmentDefinition + metadata: + name: redrouter1 + spec: + config: '{ + "cniVersion": "0.3.1", + "name": "redrouter1", + "plugins": [ + { + "type": "bridge", + "bridge": "mybr0", + "ipam": { + "type": "static", + "addresses" : [ + { + "address": "10.10.10.254/24" + } + ] + } + }, + { + "name": "brtuning", + "type": "tuning", + "sysctl": { + "net.ipv4.conf.net1.forwarding": "1" + } + } + ] + + }' + --- + apiVersion: "k8s.cni.cncf.io/v1" + kind: NetworkAttachmentDefinition + metadata: + name: redrouter2 + spec: + config: '{ + "cniVersion": "0.3.1", + "name": "redrouter2", + "plugins": [ + { + "type": "bridge", + "bridge": "mybr1", + "ipam": { + "type": "static", + "addresses" : [ + { + "address": "20.20.20.254/24" + } + ] + } + }, + { + "name": "brtuning", + "type": "tuning", + "sysctl": { + "net.ipv4.conf.net2.forwarding": "1" + } + } + ] + + }' + --- + apiVersion: "k8s.cni.cncf.io/v1" + kind: NetworkAttachmentDefinition + metadata: + name: epnet1 + spec: + config: '{ + "cniVersion": "0.3.1", + "name": "epnet1", + "plugins": [ + { + "type": "bridge", + "bridge": "mybr1", + "ipam": { + "type": "static", + "addresses" : [ + { + "address": "20.20.20.2/24", + "gateway": "20.20.20.1" + } + ], + "routes" : [ + { "dst" : "10.10.10.0/24", "gw": "20.20.20.1"} + ] + } + } + ] + + }' + --- + apiVersion: v1 + kind: Pod + metadata: + name: vrfpod1 + annotations: + k8s.v1.cni.cncf.io/networks: '[ + { "name": "bluenet1" }, + { "name": "rednet1" } + ]' + spec: + containers: + - name: vrfpod1 + image: praqma/network-multitool:extra + imagePullPolicy: IfNotPresent + command: [ "/bin/bash", "-c", "--" ] + args: [ "while true; do sleep 300000; done;" ] + securityContext: + capabilities: + add: + - NET_ADMIN + nodeName: controller-0 + --- + apiVersion: v1 + kind: Pod + metadata: + name: routerblue + annotations: + k8s.v1.cni.cncf.io/networks: '[ + { "name": "bluerouter1" }, + { "name": "bluerouter2" } + ]' + spec: + containers: + - name: routerblue + image: praqma/network-multitool:extra + imagePullPolicy: IfNotPresent + command: [ "/bin/bash", "-c", "--" ] + args: [ "while true; do sleep 300000; done;" ] + nodeName: controller-0 + --- + apiVersion: v1 + kind: Pod + metadata: + name: routerred + annotations: + k8s.v1.cni.cncf.io/networks: '[ + { "name": "redrouter1" }, + { "name": "redrouter2" } + ]' + spec: + containers: + - name: routerred + image: praqma/network-multitool:extra + imagePullPolicy: IfNotPresent + command: [ "/bin/bash", "-c", "--" ] + args: [ "while true; do sleep 300000; done;" ] + nodeName: controller-0 + --- + apiVersion: v1 + kind: Pod + metadata: + name: endpoint1 + annotations: + k8s.v1.cni.cncf.io/networks: '[ + { "name": "epnet1" } + ]' + spec: + containers: + - name: endpoint1 + image: praqma/network-multitool:extra + imagePullPolicy: IfNotPresent + command: [ "/bin/bash", "-c", "--" ] + args: [ "while true; do sleep 300000; done;" ] + nodeName: controller-0 + +Once the ``yaml`` configuration listed above has been applied, do the +following: + +#. Ensure the |VRFs| are listed in the ``vrfpod``. + + .. code-block:: none + + kubectl exec -it vrfpod1 -- ip vrf show + Name Table + ----------------------- + blue 1 + red 2 + +#. Ensure both ``net1`` and ``net2`` interfaces both have the same IP address. + + .. code-block:: none + + $ kubectl exec -it vrfpod1 -- ip addr list + +#. Add different routes through each |VRF|. + + .. code-block:: none + + $ kubectl exec -it vrfpod1 -- ip route add 20.20.20.0/24 via 10.10.10.1 vrf blue + $ kubectl exec -it vrfpod1 -- ip route add 20.20.20.0/24 via 10.10.10.254 vrf red + +#. Ping the endpoint via the blue |VRF|. + + .. code-block:: none + + kubectl exec -it vrfpod1 -- ping -I net1 20.20.20.2 + +#. Observe via tcpdump or pkt stats that the blue router gets all the traffic + + .. code-block:: none + + $ kubectl exec -it routerblue -- tcpdump -enn -i net1 + +#. Ping the endpoint via the red |VRF|. + + .. code-block:: none + + $ kubectl exec -it vrfpod -- ping -I net2 20.20.20.2 + +#. Observe via :command:`tcpdump` or :command:`pkt`` stats that the red router + gets all outgoing traffic from the ``vrfpod``. Return traffic goes via the + blue router, as that is the default ``gw`` for the endpoint. + + .. code-block:: none + + $ kubectl exec -it routerred -- tcpdump -enn -i net1 diff --git a/doc/source/usertasks/kubernetes/vlan-plugin-37938fe8578f.rst b/doc/source/usertasks/kubernetes/vlan-plugin-37938fe8578f.rst new file mode 100644 index 000000000..025985c3e --- /dev/null +++ b/doc/source/usertasks/kubernetes/vlan-plugin-37938fe8578f.rst @@ -0,0 +1,74 @@ +.. _vlan-plugin-37938fe8578f: + +=========== +VLAN Plugin +=========== + +The |VLAN| plugin allows a virtual device to be created in the container that +is attached to a physical device in the host via a ``veth`` pair. The veth in +the host namespace will be a ``VLAN`` sub-interface of the physical device. + +The following options are used to configure the plugin: + +``name`` (string, required) + The name of the network. + +``type`` (string, required) + ``vlan`` + +``master`` (string, required) + The name of the host interface to use. Default: default route interface. + +``vlanId`` (integer, required) + Id of the |VLAN|. + +``mtu`` (integer, optional) + Explicitly set |MTU| to the specified value. Default: chosen by the kernel. + +``ipam`` (dictionary, required) + |IPAM| configuration to be used for this network. For an interface without + an IP address, use an empty dictionary. + +The following example creates a pod containing an additional network +interface corresponding to a |VLAN| interface. There is no need to apply the +``vlan`` tag in the container. + +.. code-block:: yaml + + apiVersion: "k8s.cni.cncf.io/v1" + kind: NetworkAttachmentDefinition + metadata: + name: vlan0 + spec: + config: '{ + "cniVersion": "0.3.1", + "name": "vlan0", + "type": "vlan", + "master": "eth1001", + "vlanId": 100, + "ipam": { + "type": "static", + "addresses": [ + { + "address": "10.10.10.1/24", + "gateway": "10.10.10.2" + } + ] + } + }' + --- + apiVersion: v1 + kind: Pod + metadata: + name: vlanpod0 + annotations: + k8s.v1.cni.cncf.io/networks: '[ + { "name": "vlan0" } + ]' + spec: + containers: + - name: vlan0 + image: centos/tools + imagePullPolicy: IfNotPresent + command: [ "/bin/bash", "-c", "--" ] + args: [ "while true; do sleep 300000; done;" ] \ No newline at end of file