1. Using a CNI with the AF_XDP driver

1.1. Introduction

CNI, the Container Network Interface, is a technology for configuring container network interfaces and which can be used to setup Kubernetes networking. AF_XDP is a Linux socket Address Family that enables an XDP program to redirect packets to a memory buffer in userspace.

This document explains how to enable the AF_XDP Plugin for Kubernetes within a DPDK application using the AF_XDP PMD to connect and use these technologies.

1.2. Background

The standard AF_XDP PMD initialization process involves loading an eBPF program onto the kernel netdev to be used by the PMD. This operation requires root or escalated Linux privileges and thus prevents the PMD from working in an unprivileged container. The AF_XDP CNI plugin handles this situation by providing a device plugin that performs the program loading.

At a technical level the CNI opens a Unix Domain Socket and listens for a client to make requests over that socket. A DPDK application acting as a client connects and initiates a configuration “handshake”. The client then receives a file descriptor which points to the XSKMAP associated with the loaded eBPF program. The XSKMAP is a BPF map of AF_XDP sockets (XSK). The client can then proceed with creating an AF_XDP socket and inserting that socket into the XSKMAP pointed to by the descriptor.

The EAL vdev argument use_cni is used to indicate that the user wishes to run the PMD in unprivileged mode and to receive the XSKMAP file descriptor from the CNI. When this flag is set, the XSK_LIBBPF_FLAGS__INHIBIT_PROG_LOAD libbpf flag should be used when creating the socket to instruct libbpf not to load the default libbpf program on the netdev. Instead the loading is handled by the CNI.

Note

The Unix Domain Socket file path appear in the end user is “/tmp/afxdp.sock”.

1.3. Prerequisites

Docker and container prerequisites:

Set up the device plugin as described in the instructions for AF_XDP Plugin for Kubernetes.
The Docker image should contain the libbpf and libxdp libraries, which are dependencies for AF_XDP, and should include support for the ethtool command.
The Pod should have enabled the capabilities CAP_NET_RAW and CAP_BPF for AF_XDP along with support for hugepages.

Increase locked memory limit so containers have enough memory for packet buffers. For example:

cat << EOF | sudo tee /etc/systemd/system/containerd.service.d/limits.conf
[Service]
LimitMEMLOCK=infinity
EOF

dpdk-testpmd application should have AF_XDP feature enabled.

For further information see the docs for the: AF_XDP Poll Mode Driver.

1.4. Example

Howto run dpdk-testpmd with CNI plugin:

Clone the CNI plugin

# git clone https://github.com/intel/afxdp-plugins-for-kubernetes.git

Build the CNI plugin

# cd afxdp-plugins-for-kubernetes/
# make build

Note

CNI plugin has a dependence on the config.json.

Sample Config.json

{
   "logLevel":"debug",
   "logFile":"afxdp-dp-e2e.log",
   "pools":[
      {
         "name":"e2e",
         "mode":"primary",
         "timeout":30,
         "ethtoolCmds" : ["-L -device- combined 1"],
         "devices":[
            {
               "name":"ens785f0"
            }
         ]
      }
   ]
}

For further reference please use the config.json

Create the Network Attachment definition

# kubectl create -f nad.yaml

Sample nad.yml

apiVersion: "k8s.cni.cncf.io/v1"
kind: NetworkAttachmentDefinition
metadata:
  name: afxdp-e2e-test
  annotations:
    k8s.v1.cni.cncf.io/resourceName: afxdp/e2e
spec:
  config: '{
      "cniVersion": "0.3.0",
      "type": "afxdp",
      "mode": "cdq",
      "logFile": "afxdp-cni-e2e.log",
      "logLevel": "debug",
      "ipam": {
        "type": "host-local",
        "subnet": "192.168.1.0/24",
        "rangeStart": "192.168.1.200",
        "rangeEnd": "192.168.1.216",
        "routes": [
          { "dst": "0.0.0.0/0" }
        ],
        "gateway": "192.168.1.1"
      }
    }'

For further reference please use the nad.yaml

Build the Docker image

# docker build -t afxdp-e2e-test -f Dockerfile .

Sample Dockerfile:

FROM ubuntu:20.04
RUN apt-get update -y
RUN apt install build-essential libelf-dev -y
RUN apt-get install iproute2  acl -y
RUN apt install python3-pyelftools ethtool -y
RUN apt install libnuma-dev libjansson-dev libpcap-dev net-tools -y
RUN apt-get install clang llvm -y
COPY ./libbpf<version>.tar.gz /tmp
RUN cd /tmp && tar -xvmf libbpf<version>.tar.gz && cd libbpf/src && make install
COPY ./libxdp<version>.tar.gz /tmp
RUN cd /tmp && tar -xvmf libxdp<version>.tar.gz && cd libxdp && make install

Note

All the files that need to COPY-ed should be in the same directory as the Dockerfile

Run the Pod

# kubectl create -f pod.yaml

Sample pod.yaml:

apiVersion: v1
kind: Pod
metadata:
  name: afxdp-e2e-test
  annotations:
    k8s.v1.cni.cncf.io/networks: afxdp-e2e-test
spec:
  containers:
  - name: afxdp
    image: afxdp-e2e-test:latest
    imagePullPolicy: Never
    env:
    - name: LD_LIBRARY_PATH
      value: /usr/lib64/:/usr/local/lib/
    command: ["tail", "-f", "/dev/null"]
    securityContext:
     capabilities:
        add:
          - CAP_NET_RAW
          - CAP_BPF
    resources:
      requests:
        hugepages-2Mi: 2Gi
        memory: 2Gi
        afxdp/e2e: '1'
      limits:
        hugepages-2Mi: 2Gi
        memory: 2Gi
        afxdp/e2e: '1'

For further reference please use the pod.yaml

Run DPDK with a command like the following:

kubectl exec -i <Pod name> --container <containers name> -- \
      /<Path>/dpdk-testpmd -l 0,1 --no-pci \
      --vdev=net_af_xdp0,use_cni=1,iface=<interface name> \
      -- --no-mlockall --in-memory

For further reference please use the e2e test case in AF_XDP Plugin for Kubernetes