The module lifecycle stage: Preview

Introduction

This guide is dedicated to creating user resources based on existing administrative resources that have been received from the cluster or network administrator.

User resources/Custom resources

Network

To create a network for a specific project, use the Network and networkClass resources provided to you by the administrator:

apiVersion: network.deckhouse.io/v1alpha1
kind: Network
metadata:
  name: my-network
  namespace: my-namespace
spec:
  networkClass: my-network-class # mandatory

After creating the Network resource you can check its status:

d8 k -n my-namespace get network my-network -o yaml
Example of the status of a `Network' resource 
apiVersion: network.deckhouse.io/v1alpha1
kind: Network
metadata:
...
status:
  bridgeName: d8-br-600
  conditions:
  - lastTransitionTime: "2025-09-29T14:51:26Z"
    message: All node interface attachments are ready
    reason: AllNodeInterfaceAttachmentsAreReady
    status: "True"
    type: AllNodeAttachementsAreReady
  - lastTransitionTime: "2025-09-29T14:51:26Z"
    message: Network is operational
    reason: NetworkReady
    status: "True"
    type: Ready
  nodeAttachementsCount: 1
  observedGeneration: 1
  readyNodeAttachementsCount: 1
  vlanID: 600

Static identification of the VLAN ID number from the pool assigned by the cluster or network administrator is supported. If the value of the spec.vlan.id field is not specified in the resource specification, the VLAN ID will be assigned dynamically.

Connecting additional networks to pods

Additional networks are configured using a pod annotation:

network.deckhouse.io/networks-spec: |
  [
    {
      "type": "Network",
      "name": "my-network",
      "ifName": "veth_mynet",    # TAP interface name inside the pod (optional).
      "mac": "aa:bb:cc:dd:ee:ff" # MAC address to assign to the TAP interface (optional).
    },
    {
      "type": "ClusterNetwork",
      "name": "my-cluster-network",
      "ifName": "veth_public",
    }
  ]

Connecting physical network interfaces to pods (DPDK workloads)

To use physical network interfaces (PF/VF) directly in pods for DPDK applications, you need to:

  1. Ensure your namespace has been labeled by the administrator to allow UnderlayNetwork usage (see Admin Guide)
  2. Create a pod with an annotation requesting the UnderlayNetwork device
Creating a pod with UnderlayNetwork device

Create a pod that requests a device from an UnderlayNetwork. The pod annotation should specify:

  • type: "UnderlayNetwork" — indicates this is a physical device request
  • name: "underlay-network-name" — the name of the UnderlayNetwork resource created by the administrator
  • bindingMode — the binding mode for the device (VFIO-PCI, DPDK, or NetDev)

Example pod configuration for DPDK mode (universal mode that automatically selects the appropriate driver for the network adapter vendor):

apiVersion: v1
kind: Pod
metadata:
  name: dpdk-app
  namespace: mydpdk
  annotations:
    network.deckhouse.io/networks-spec: |
      [
        {
          "type": "UnderlayNetwork",
          "name": "dpdk-shared-network",
          "bindingMode": "DPDK"
        }
      ]
spec:
  containers:
  - name: dpdk-container
    image: dpdk-app:latest
    securityContext:
      privileged: false
      capabilities:
        add:
        - NET_ADMIN
        - NET_RAW
        - IPC_LOCK
    volumeMounts:
    - mountPath: /hugepages
      name: hugepage
    resources:
      limits:
        hugepages-2Mi: 4Gi
        memory: 4Gi
        cpu: 4
      requests:
        cpu: 4
        memory: 4Gi
    command: ["/bin/sh", "-c", "sleep infinity"]
  volumes:
  - name: hugepage
    emptyDir:
      medium: HugePages

For DPDK applications, it is important to:

  • Configure capabilities (NET_ADMIN, NET_RAW, IPC_LOCK) to run in non-privileged mode instead of using privileged: true
  • Mount hugepages volumes, as DPDK requires hugepages for efficient memory management

For VF devices in Shared mode, you can optionally specify a vlanID in the annotation to configure VLAN tagging on the VF:

network.deckhouse.io/networks-spec: |
  [
    {
      "type": "UnderlayNetwork",
      "name": "dpdk-shared-network",
      "bindingMode": "VFIO-PCI",
      "vlanID": 100
    }
  ]

After creating the pod, verify that the device was allocated by checking the network.deckhouse.io/networks-status annotation:

d8 k -n mydpdk get pod dpdk-app -o jsonpath='{.metadata.annotations.network\.deckhouse\.io/networks-status}' | jq

You can also check the ResourceClaim that was automatically created:

d8 k -n mydpdk get resourceclaim
Example pod status with allocated UnderlayNetwork device 
apiVersion: v1
kind: Pod
metadata:
  name: dpdk-app
  namespace: mydpdk
  annotations:
    network.deckhouse.io/networks-spec: |
      [
        {
          "type": "UnderlayNetwork",
          "name": "dpdk-shared-network",
          "bindingMode": "DPDK"
        }
      ]
    network.deckhouse.io/networks-status: |
      [
        {
          "type": "UnderlayNetwork",
          "name": "dpdk-shared-network",
          "bindingMode": "DPDK",
          "netDevInterfaces": [
            {
              "name": "ens1f0",
              "mac": "00:1b:21:bb:aa:cc"
            }
          ],
          "conditions": [
            {
              "type": "Configured",
              "status": "True",
              "reason": "InterfaceConfiguredSuccessfully",
              "message": "",
              "lastTransitionTime": "2025-01-15T10:35:00Z"
            },
            {
              "type": "Negotiated",
              "status": "True",
              "reason": "Up",
              "message": "",
              "lastTransitionTime": "2025-01-15T10:35:00Z"
            }
          ]
        }
      ]
status:
  phase: Running
  ...