Руководство описывает порядок создания и изменения ресурсов для управления программно-определяемой сетью.

Подготовка кластера к использованию модуля

Предварительная подготовка инфраструктуры:

  • Для создания дополнительных сетей на основе тегированных VLAN:
    • Выделите диапазоны VLAN ID на коммутаторах в ЦОД и настройте их на соответствующих сетевых интерфейсах коммутаторов.
    • Выберите физические интерфейсы на узлах для последующей настройки тегированных VLAN-интерфейсов. Допускается использование интерфейсов, уже задействованных под служебную локальную межузловую сеть DKP.
  • Для создания дополнительных сетей на основе прямого, нетегированного доступа в сетевой интерфейс:
    • Выделите отдельные физические интерфейсы на узлах и скоммутируйте их в единую локальную сеть на уровне ЦОД.

Далее, после включения модуля, в кластере автоматически появятся ресурсы NodeNetworkInterface, которые отражают текущее состояние интерфейсов на узлах.

Чтобы проверить наличие ресурсов, используйте команду:

d8 k get nodenetworkinterface

Пример вывода:

NAME                            MANAGEDBY   NODE           TYPE     IFNAME           IFINDEX   STATE      AGE
virtlab-ap-0-nic-1c61b4a68c2a   Deckhouse   virtlab-ap-0   NIC      eth1             3         Up         35d
virtlab-ap-0-nic-fc34970f5d1f   Deckhouse   virtlab-ap-0   NIC      eth0             2         Up         35d
virtlab-ap-1-nic-1c61b4a6a0e7   Deckhouse   virtlab-ap-1   NIC      eth1             3         Up         35d
virtlab-ap-1-nic-fc34970f5c8e   Deckhouse   virtlab-ap-1   NIC      eth0             2         Up         35d
virtlab-ap-2-nic-1c61b4a6800c   Deckhouse   virtlab-ap-2   NIC      eth1             3         Up         35d
virtlab-ap-2-nic-fc34970e7ddb   Deckhouse   virtlab-ap-2   NIC      eth0             2         Up         35d

При обнаружении интерфейсов узлов контроллер устанавливает следующие служебные метки:

    labels:
      network.deckhouse.io/interface-mac-address: fa163eebea7b
      network.deckhouse.io/interface-type: NIC
      network.deckhouse.io/nic-pci-bus-info: 0000-17-00.0
      network.deckhouse.io/nic-pci-type: PF
      network.deckhouse.io/node-name: worker-01
    annotations:
      network.deckhouse.io/heritage: NetworkController

В этом примере у каждого узла в кластере есть по два сетевых интерфейса — eth0 (DKP LAN) и eth1 (выделенный интерфейс для организации дополнительных сетей).

Для дальнейшей работы разметьте выделенные интерфейсы под организацию дополнительных сетей подходящим лейблом:

d8 k label nodenetworkinterface virtlab-ap-0-nic-1c61b4a68c2a nic-group=extra
d8 k label nodenetworkinterface virtlab-ap-1-nic-1c61b4a6a0e7 nic-group=extra
d8 k label nodenetworkinterface virtlab-ap-2-nic-1c61b4a6800c nic-group=extra

Также для повышения пропускной способности или резервирования возможно объединение нескольких физических интерфейсов в Bond.

Интерфейс Bond может быть создан только между сетевыми интерфейсами, расположенными на одном физическом или виртуальном хосте.

Пример создания интерфейса Bond:

Ресурс nodenetworkinterface может быть сокращён до nni.

Установить на интерфейсы, предназначенные для объединения в Bond-интерфейс, пользовательские лейблы:

d8 k label nni right-worker-b23d3a26-5fb4b-f545g-nic-fa163efbde48 nni.example.com/bond-group=bond0
d8 k label nni right-worker-b23d3a26-5fb4b-f545g-nic-fa40asdxzx78 nni.example.com/bond-group=bond0

Подготовить конфигурацию для создания интерфейса и применить:

apiVersion: network.deckhouse.io/v1alpha1
kind: NodeNetworkInterface
metadata:
  name: nni-worker-01-bond0
spec:
  nodeName: worker-01
  type: Bond
  heritage: Manual
  bond:
    bondName: bond0
    memberNetworkInterfaces:
      - labelSelector:
          matchLabels:
            network.deckhouse.io/node-name: worker-01 # Это служебная метка, которую необходимо указывать для объединения с интерфейсом Bond на определенном узле.
            nni.example.com/bond-group: bond0 # Пользовательский лейбл, вы должны установить самостоятельно на выбранные интерфейсы.
Пример проверки статуса созданного интерфейса Bond

Для получения списка интерфейсов Bond используйте команду:

d8 k get nni

Пример вывода:

NAME                                                          MANAGEDBY   NODE                             TYPE     IFNAME      IFINDEX   STATE   AGE
nni-worker-01-bond0                                           Manual      worker-01-b23d3a26-5fb4b-5s9fp   Bond     bond0       76        Up      7m48s
...

Чтобы получить информацию о статусе интерфейса используйте команду

d8 k get nni nni-worker-01-bond0 -o yaml

Пример статуса интерфейса:

apiVersion: network.deckhouse.io/v1alpha1
kind: NodeNetworkInterface
metadata:
...
status:
  conditions:
  - lastProbeTime: "2025-09-30T09:00:54Z"
    lastTransitionTime: "2025-09-30T09:00:39Z"
    message: Interface created
    reason: Created
    status: "True"
    type: Exists
  - lastProbeTime: "2025-09-30T09:00:54Z"
    lastTransitionTime: "2025-09-30T09:00:39Z"
    message: Interface is up and ready to send packets
    reason: Up
    status: "True"
    type: Operational
  deviceMAC: 6a:c7:ab:2a:a6:1e
  groupedLinks:
  - deviceMAC: fa:16:3e:92:14:40
    type: NIC
  ifIndex: 76
  ifName: bond0
  managedBy: Manual
  operationalState: Up
  permanentMAC: ""

Настройка и подключение дополнительных виртуальных сетей для использования в прикладных подах

Административные ресурсы

ClusterNetwork

Для создания сети, доступной к использованию в любом проекте, используется интерфейс ClusterNetwork.

Пример для сети, основанной на тегированном трафике:

apiVersion: network.deckhouse.io/v1alpha1
kind: ClusterNetwork
metadata:
  name: my-cluster-network
spec:
  type: VLAN
  vlan:
    id: 900
  parentNodeNetworkInterfaces:
    labelSelector:
      matchLabels:
        nic-group: extra # Лейбл, вручную установленный на ресурсы NodeNetworkInterface.

После того как вы создали ресурс ClusterNetwork, можете проверить его состояние командой:

d8 k get clusternetworks.network.deckhouse.io my-cluster-network -o yaml
Пример статуса ресурса ClusterNetwork 
apiVersion: network.deckhouse.io/v1alpha1
kind: ClusterNetwork
metadata:
...
status:
  bridgeName: d8-br-900
  conditions:
  - lastTransitionTime: "2025-09-29T14:39:20Z"
    message: All node interface attachments are ready
    reason: AllNodeInterfaceAttachmentsAreReady
    status: "True"
    type: AllNodeAttachementsAreReady
  - lastTransitionTime: "2025-09-29T14:39:20Z"
    message: Network is operational
    reason: NetworkReady
    status: "True"
    type: Ready
  nodeAttachementsCount: 1
  observedGeneration: 1
  readyNodeAttachementsCount: 1

После создания ресурсов Network или ClusterNetwork будет автоматически создан ресурс NodeNetworkInterfaceAttachment, отражающий присоединение данной сети к интерфейсам на узлах.

Для получения списка ресурсов NodeNetworkInterfaceAttachment и информации о конкретном ресурсе используйте команды:

d8 k get nnia
d8 k get nnia my-cluster-network-... -o yaml
Пример ресурса NodeNetworkInterfaceAttachment 
apiVersion: network.deckhouse.io/v1alpha1
kind: NodeNetworkInterfaceAttachment
metadata:
...
  finalizers:
    - network.deckhouse.io/nni-network-interface-attachment
    - network.deckhouse.io/pod-network-interface-attachment
  generation: 1
  name: my-cluster-network-...
...
spec:
  networkRef:
    kind: ClusterNetwork
    name: my-cluster-network
  parentNetworkInterfaceRef:
    name: right-worker-b23d3a26-5fb4b-h2bkv-nic-fa163eebea7b
  type: VLAN
status:
  bridgeNodeNetworkInterfaceName: right-worker-b23d3a26-5fb4b-h2bkv-bridge-900
  conditions:
    - lastTransitionTime: "2025-09-29T14:39:06Z"
      message: Vlan created
      reason: VLANCreated
      status: "True"
      type: Exist
    - lastTransitionTime: "2025-09-29T14:39:06Z"
      message: Bridged successfully
      reason: VLANBridged
      status: "True"
      type: Ready
  nodeName: right-worker-b23d3a26-5fb4b-h2bkv
  vlanNodeNetworkInterfaceName: right-worker-b23d3a26-5fb4b-h2bkv-vlan-900-60f3dc

Если в ресурсах Network или ClusterNetwork был указан тип VLAN, также создадутся NodeNetworkInterface для VLAN и Bridge.

Статус NodeNetworkInterfaceAttachment изменится на True сразу после того как соответствующие NodeNetworkInterface появятся и перейдут в состояние Up.

Для проверки статусов NodeNetworkInterface используйте команду:

d8 k get nni

Пример вывода:

NAME                                                 MANAGEDBY   NODE                                TYPE     IFNAME      IFINDEX   STATE   AGE
...
right-worker-b23d3a26-5fb4b-h2bkv-bridge-900         Deckhouse   right-worker-b23d3a26-5fb4b-h2bkv   Bridge   d8-br-900   684       Up      14h
right-worker-b23d3a26-5fb4b-h2bkv-nic-fa163eebea7b   Deckhouse   right-worker-b23d3a26-5fb4b-h2bkv   NIC      ens3        2         Up      19d
right-worker-b23d3a26-5fb4b-h2bkv-vlan-900-60f3dc    Deckhouse   right-worker-b23d3a26-5fb4b-h2bkv   VLAN     ens3.900    683       Up      14h
...

Пример для сети, основанной на прямом доступе в интерфейс:

apiVersion: network.deckhouse.io/v1alpha1
kind: ClusterNetwork
metadata:
  name: my-cluster-network
spec:
  type: Access
  parentNodeNetworkInterfaces:
    labelSelector:
      matchLabels:
        nic-group: extra # Лейбл, вручную установленный на ресурсы NodeNetworkInterface.

NetworkClass

Чтобы пользователи имели возможность создавать собственные выделенные сети, основанные на тегированном трафике, необходимо предварительно описать доступный им диапазон тегов и определить сетевые интерфейсы, на которых они могут быть настроены. Для этого используется интерфейс NetworkClass.

Пример:

apiVersion: network.deckhouse.io/v1alpha1
kind: NetworkClass
metadata:
  name: my-network-class
spec:
  vlan:
    idPool:
    - 600-800
    - 1200
    parentNodeNetworkInterfaces:
      labelSelector:
        matchLabels:
          nic-group: extra

IPAM: пулы IP-адресов для дополнительных сетей

Механизм IPAM позволяет автоматически выделять и назначать IPv4-адреса для дополнительных сетевых интерфейсов подов, подключаемых к кластерным сетям и сетям проекта.

Принципы и особенности работы IPAM в DKP

Для каждого требуемого IP-адреса создаётся и используется namespaced-объект IPAddress (ClusterIPAddress), который ссылается на сеть проекта (Network) или кластерную сеть (ClusterNetwork). Контроллер выделяет адрес из пула и сохраняет результат в status.address, status.network, status.routes объекта IPAddress. Агент на узле назначает IP-адрес и маршруты на интерфейс внутри пода и выставляет IPAddress.status.conditions[Attached] и status.usedByPods.

Для защиты от конфликтов создаётся cluster-scoped объект IPAddressLease, который резервирует IP-адрес. При удалении объекта IPAddress соответствующий ему IPAddressLease помечается как orphaned (для этого используется поле status.orphaningTimestamp) и удерживает адрес в течение времени, указанном в параметре spec.ttl (чтобы избежать быстрых переиспользований).

Детали использования механизма (включая ipAddressNames/skipIPAssignment) см. в Руководстве пользователя.

Пример назначения IP-адресов для дополнительных сетевых интерфейсов подов, подключаемых к сети проекта

Чтобы выделить пул адресов для сети проекта (Network), создайте ресурс IPAddressPool в том же неймспейсе, что и сеть проекта (поды, подключаемые к сети).

Для выделения пула адресов и их назначения на сетевые интерфейсы подов, подключаемых к сети проекта, выполните следующие действия:

  1. Создайте пул адресов. Для этого используйте ресурс IPAddressPool.

    Пример:

    apiVersion: network.deckhouse.io/v1alpha1
kind: IPAddressPool
metadata:
  name: my-net-pool
  namespace: my-namespace
spec:
  leaseTTL: 1h
  pools:
    - network: 192.168.10.0/24
      ranges:
        - 192.168.10.50-192.168.10.200
      routes:
        - destination: 10.10.0.0/16
          via: 192.168.10.1

    Параметр spec.pools[].ranges опционален. Если он не указан, доступным считается весь CIDR из spec.pools[].network (за исключением network/broadcast адресов, см. поведение /31 и /32).

  2. Включите IPAM в сети. Для этого в параметре spec.ipam.ipAddressPoolRef ресурса Network укажите параметры созданного на предыдущем шаге IPAddressPool.

    Пример:

    apiVersion: network.deckhouse.io/v1alpha1
kind: Network
metadata:
  name: my-network
  namespace: my-namespace
spec:
  networkClass: my-network-class
  ipam:
    ipAddressPoolRef:
      kind: IPAddressPool
      name: my-net-pool

Пример назначения IP-адресов для дополнительных сетевых интерфейсов подов, подключаемых к кластерной сети

Чтобы выделить пул адресов для кластерной сети (создается с помощью ресурса ClusterNetwork), используйте ресурс ClusterIPAddressPool.

Для выделения пула адресов и их назначения на сетевые интерфейсы подов, подключаемых к кластерной сети, выполните следующие действия:

  1. Создайте пул адресов. Для этого используйте ресурс ClusterIPAddressPool.

    Пример:

    apiVersion: network.deckhouse.io/v1alpha1
kind: ClusterIPAddressPool
metadata:
  name: public-net-pool
spec:
  leaseTTL: 24h
  pools:
    - network: 203.0.113.0/24
      ranges:
        - 203.0.113.10-203.0.113.200

    Параметр spec.pools[].ranges опционален. Если он не указан, доступным считается весь CIDR из spec.pools[].network (за исключением network/broadcast адресов, см. поведение /31 и /32).

  2. Включите IPAM в сети. Для этого в параметре spec.ipam.ipAddressPoolRef ресурса ClusterNetwork укажите параметры созданного на предыдущем шаге lusterIPAddressPool.

    apiVersion: network.deckhouse.io/v1alpha1
kind: ClusterNetwork
metadata:
  name: my-cluster-network
spec:
  type: VLAN
  vlan:
    id: 900
  parentNodeNetworkInterfaces:
    labelSelector:
      matchLabels:
        nic-group: extra
  ipam:
    ipAddressPoolRef:
      kind: ClusterIPAddressPool
      name: public-net-pool

Настройка и подключение физических интерфейсов в прикладные поды

Ресурс UnderlayNetwork обеспечивает прямой проброс аппаратных устройств в поды через Kubernetes Dynamic Resource Allocation (DRA). Это позволяет приложениям DPDK и другим высокопроизводительным рабочим нагрузкам получать прямой доступ к физическим сетевым интерфейсам (PF/VF), обходя сетевой стек ядра.

Предварительные требования для DPDK-приложений

Перед настройкой ресурсов UnderlayNetwork необходимо подготовить рабочие узлы кластера для DPDK-приложений:

Настройка hugepages

DPDK-приложения требуют hugepages для эффективного управления памятью. Настройте hugepages на всех рабочих узлах с помощью NodeGroupConfiguration:

apiVersion: deckhouse.io/v1alpha1
kind: NodeGroupConfiguration
metadata:
  name: hugepages-for-dpdk
spec:
  nodeGroups:
    - '*'  # Применить ко всем группам узлов.
  weight: 100
  content: |
    #!/bin/bash
    echo "vm.nr_hugepages = 4096" > /etc/sysctl.d/99-hugepages.conf
    sysctl -p /etc/sysctl.d/99-hugepages.conf

Эта конфигурация устанавливает vm.nr_hugepages = 4096 на всех узлах, предоставляя 8 GiB hugepages (4096 страниц × 2 MiB на страницу).

Настройка Topology Manager

Включите Topology Manager на NodeGroup рабочих узлов, где будут запускаться DPDK-приложения. Это обеспечивает выделение ресурсов CPU, памяти и устройств из одного NUMA узла.

Пример конфигурации NodeGroup:

apiVersion: deckhouse.io/v1
kind: NodeGroup
metadata:
  name: worker
spec:
  kubelet:
    topologyManager:
      enabled: true
      policy: SingleNumaNode
      scope: Container
  nodeType: Static

Для получения дополнительной информации см.:

Предварительные требования

Перед созданием UnderlayNetwork убедитесь, что:

  1. Физические сетевые интерфейсы (NIC) доступны на узлах и обнаружены как ресурсы NodeNetworkInterface.
  2. Интерфейсы, которые вы планируете использовать, являются Physical Functions (PF), а не Virtual Functions (VF).
  3. Для режима Shared сетевые карты должны поддерживать SR-IOV.

Подготовка ресурсов NodeNetworkInterface

Сначала проверьте, какие Physical Functions доступны на ваших узлах:

d8 k get nni -l network.deckhouse.io/nic-pci-type=PF

Пример вывода:

NAME                            MANAGEDBY   NODE           TYPE   IFNAME   IFINDEX   STATE   VF/PF   Binding   Driver      Vendor   AGE
worker-01-nic-0000:17:00.0      Deckhouse   worker-01     NIC    ens3f0   3         Up      PF      NetDev    ixgbe       Intel    35d
worker-01-nic-0000:17:00.1      Deckhouse   worker-01     NIC    ens3f1   4         Up      PF      NetDev    ixgbe       Intel    35d
worker-02-nic-0000:17:00.0      Deckhouse   worker-02     NIC    ens3f0   3         Up      PF      NetDev    ixgbe       Intel    35d
worker-02-nic-0000:17:00.1      Deckhouse   worker-02     NIC    ens3f1   4         Up      PF      NetDev    ixgbe       Intel    35d

Пометьте интерфейсы, которые будут использоваться для UnderlayNetwork:

d8 k label nni worker-01-nic-0000:17:00.0 nic-group=dpdk
d8 k label nni worker-01-nic-0000:17:00.1 nic-group=dpdk
d8 k label nni worker-02-nic-0000:17:00.0 nic-group=dpdk
d8 k label nni worker-02-nic-0000:17:00.1 nic-group=dpdk

Вы можете проверить PCI информацию и статус поддержки SR-IOV для каждого интерфейса:

d8 k get nni worker-01-nic-0000:17:00.0 -o json | jq '.status.nic.pci.pf'

Ищите status.nic.pci.pf.sriov.supported для проверки поддержки SR-IOV.

Создание UnderlayNetwork в режиме Dedicated

В режиме Dedicated каждый Physical Function предоставляется как эксклюзивное устройство. Этот режим подходит, когда:

  • SR-IOV недоступен или не нужен;
  • каждому поду требуется эксклюзивный доступ к полному PF.

Пример конфигурации:

apiVersion: network.deckhouse.io/v1alpha1
kind: UnderlayNetwork
metadata:
  name: dpdk-dedicated-network
spec:
  mode: Dedicated
  autoBonding: false
  memberNodeNetworkInterfaces:
    - labelSelector:
        matchLabels:
          nic-group: dpdk

Когда autoBonding установлен в true, все совпавшие PF на узле группируются в одно DRA устройство, предоставляя поду все PF как отдельные интерфейсы. Когда false, — каждый PF публикуется как отдельное DRA устройство.

Проверьте статус созданного UnderlayNetwork:

d8 k get underlaynetwork dpdk-dedicated-network -o yaml
Пример статуса UnderlayNetwork в режиме Dedicated 
apiVersion: network.deckhouse.io/v1alpha1
kind: UnderlayNetwork
metadata:
  name: dpdk-dedicated-network
...
status:
  observedGeneration: 1
  conditions:
  - message: All 2 member node network interface selectors have matches
    observedGeneration: 1
    reason: AllInterfacesAvailable
    status: "True"
    type: InterfacesAvailable

Создание UnderlayNetwork в режиме Shared

В режиме Shared создаются Virtual Functions (VF) из Physical Functions (PF) с использованием SR-IOV, позволяя нескольким подам совместно использовать одно и то же оборудование. Этот режим требует поддержки SR-IOV на сетевых картах.

Пример конфигурации:

apiVersion: network.deckhouse.io/v1alpha1
kind: UnderlayNetwork
metadata:
  name: dpdk-shared-network
spec:
  mode: Shared
  autoBonding: true
  memberNodeNetworkInterfaces:
    - labelSelector:
        matchLabels:
          nic-group: dpdk
  shared:
    sriov:
      enabled: true
      numVFs: 8

В этом примере:

  • mode: Shared включает SR-IOV и создание VF;
  • autoBonding: true группирует одну VF от каждого совпавшего PF в одно DRA устройство;
  • shared.sriov.enabled: true включает SR-IOV на выбранных PF;
  • shared.sriov.numVFs: 8 создает 8 Virtual Functions на каждый Physical Function.

Поля mode и autoBonding неизменяемы после установки. Тщательно спланируйте конфигурацию перед созданием ресурса.

После создания UnderlayNetwork отслеживайте статус конфигурации SR-IOV:

d8 k get underlaynetwork dpdk-shared-network -o yaml
Пример статуса UnderlayNetwork в режиме Shared 
apiVersion: network.deckhouse.io/v1alpha1
kind: UnderlayNetwork
metadata:
  name: dpdk-shared-network
...
status:
  observedGeneration: 1
  sriov:
    supportedNICs: 4
    enabledNICs: 4
  conditions:
  - lastTransitionTime: "2025-01-15T10:30:00Z"
    observedGeneration: 1
    message: SR-IOV configured on 4 NICs
    reason: SRIOVConfigured
    status: "True"
    type: SRIOVConfigured
  - lastTransitionTime: "2025-01-15T10:30:05Z"
    observedGeneration: 1
    message: Interfaces are available for allocation
    reason: InterfacesAvailable
    status: "True"
    type: InterfacesAvailable

Вы можете проверить, что VF были созданы, проверив ресурсы NodeNetworkInterface:

d8 k get nni -l network.deckhouse.io/nic-pci-type=VF

Подготовка неймспейса для использования UnderlayNetwork

Перед тем как пользователи смогут запрашивать устройства UnderlayNetwork в своих подах, неймспейс должен быть помечен для включения поддержки UnderlayNetwork. Это административная задача, которая должна быть выполнена для неймспейса, где будут запускаться DPDK-приложения:

d8 k label namespace mydpdk direct-nic-access.network.deckhouse.io/enabled=""