starlingx/docs
Code Issues Proposed changes

Container Network Interface (CNI) Plugin Up-version

Browse Source 
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 <ronald.stone@windriver.com>
Change-Id: Idab0308ff8f973c4aa20b66fbcfb932bf3dcf92c
This commit is contained in:
Ron Stone 2022-05-04 08:19:52 -04:00
parent d6f65b4cba
commit 539fb24b44
17 changed files with 1800 additions and 457 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
doc/source/shared/abbrevs.txt
View File

@ -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)`

91
doc/source/usertasks/kubernetes/add-an-additional-network-interface-to-a-container-616bc5c5a6dd.rst Normal file
View File

@ -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 <sriov-plugin-4229f81b27ce>`
Adds an |SRIOV| |VF| interface to a container.
:ref:`host-device <host-device-plugin-714d4862a825>`
Adds an already-existing device to a container.
:ref:`macvlan <macvlan-plugin-e631cca21ffb>`
Creates an interface with a new |MAC| address, usually from a shared host
interface.
:ref:`ipvlan <ipvlan-plugin-150be92d0538>`
Creates an ``ipvlan`` interface in the container.
:ref:`bridge <bridge-plugin-7caa94024df4>`
Creates a bridge on the host and adds a ``veth`` interface in the container
to it.
:ref:`ptp <ptp-plugin-bc6ed0498f4c>`
Creates a ``veth`` pair between the container and host.
:ref:`vlan <vlan-plugin-37938fe8578f>`
Creates a ``vlan`` device in the container.
See :ref:`bond <integrate-the-bond-cni-plugin-2c2f14733b46>` for more information.
``bond``
Creates a bonded interface in the container.
:ref:`vrf <virtual-routing-and-forwarding-plugin-0e53f2c2de21>`
Enables virtual routing and forwarding in the network namespace of the
container.
-------------------
"meta" plugin types
-------------------
:ref:`tuning <tuning-plugin-08f8cdbf1763>`
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 <bandwidth-plugin-3b8966c3fe47>`
Applies bandwidth-limiting on a container interface through use of traffic
control ``tbf``.
:ref:`sbr <source-based-routing-plugin-51648f2ddff1>`
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.

93
doc/source/usertasks/kubernetes/bandwidth-plugin-3b8966c3fe47.rst Normal file
View File

@ -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;" ]

96
doc/source/usertasks/kubernetes/bridge-plugin-7caa94024df4.rst Normal file
View File

@ -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;" ]

195
doc/source/usertasks/kubernetes/creating-network-attachment-definitions.rst
View File

@ -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
<using-network-attachment-definitions-in-a-container>`.
.. xreflink For information about PCI-SRIOV Interface Support, see the |datanet-doc|:
:ref:`<data-network-management-data-networks>` 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 <<EOF > 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 <<EOF > 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 <<EOF > 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 <<EOF > 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
<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
<using-network-attachment-definitions-in-a-container>`

57
doc/source/usertasks/kubernetes/host-device-plugin-714d4862a825.rst Normal file
View File

@ -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;" ]

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

@ -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
--------------

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

@ -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),

78
doc/source/usertasks/kubernetes/ipvlan-plugin-150be92d0538.rst Normal file
View File

@ -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;" ]

78
doc/source/usertasks/kubernetes/macvlan-plugin-e631cca21ffb.rst Normal file
View File

@ -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;" ]

72
doc/source/usertasks/kubernetes/ptp-plugin-bc6ed0498f4c.rst Normal file
View File

@ -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;" ]

222
doc/source/usertasks/kubernetes/source-based-routing-plugin-51648f2ddff1.rst Normal file
View File

@ -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

452
doc/source/usertasks/kubernetes/sriov-plugin-4229f81b27ce.rst Normal file
View File

@ -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
<using-network-attachment-definitions-in-a-container>`.
.. xreflink For information about PCI-SRIOV Interface Support, see the |datanet-doc|:
:ref:`<data-network-management-data-networks>` 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
<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 <<EOF > 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 <<EOF > 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 <<EOF > 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
<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|
<data-network-management-data-networks>` 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 <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.

88
doc/source/usertasks/kubernetes/tuning-plugin-08f8cdbf1763.rst Normal file
View File

@ -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;" ]

241
doc/source/usertasks/kubernetes/using-network-attachment-definitions-in-a-container.rst
View File

@ -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
<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|
<data-network-management-data-networks>` 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 <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.

373
doc/source/usertasks/kubernetes/virtual-routing-and-forwarding-plugin-0e53f2c2de21.rst Normal file
View File

@ -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

74
doc/source/usertasks/kubernetes/vlan-plugin-37938fe8578f.rst Normal file
View File

@ -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;" ]