Deploy Multus CNI

Learn how to install and configure Multus CNI on Talos Linux to attach multiple network interfaces to a pod.

Multus CNI is a container network interface (CNI) plugin for Kubernetes that enables attaching multiple network interfaces to pods. Typically, in Kubernetes each pod only has one network interface (apart from a loopback). With Multus, you can create a multi-homed pod that has multiple interfaces. This is accomplished by Multus acting as a “meta-plugin”, a CNI plugin that can call multiple other CNI plugins.

This guide covers:

• Install Multus for Talos: Deploy the Multus DaemonSet, and how to check whether a netns path patch is needed on your Talos version.
• Configure a multi-homed pod: Define a NetworkAttachmentDefinition and attach it to a pod, giving it a second network interface.
• Known issues: Current upstream bugs and their workarounds.
• Compatibility notes: What changes when running Multus alongside KubeVirt or Cilium.

Install Multus for Talos

1. Deploy the thick DaemonSet with kubectl:

   kubectl apply -f https://raw.githubusercontent.com/k8snetworkplumbingwg/multus-cni/master/deployments/multus-daemonset-thick.yml
   

   This creates a DaemonSet and a CRD, NetworkAttachmentDefinition, which you’ll use to specify your network configuration in Configure a multi-homed pod.

2. Check whether the netns path patch applies to your Talos version. The upstream manifest mounts the host-run-netns volume at /run/netns. On Talos versions where /var/run is a symlink to /run, /run/netns and /var/run/netns are the same location, and no patch is needed.

   Check your node:

   talosctl --nodes <node-ip> list -l /var
   

   If the output shows run -> /run, the paths are identical and the DaemonSet works as deployed, with no patch required. This was confirmed on Talos v1.13.7 / Kubernetes v1.36.2: with /var/run symlinked to /run, the unpatched DaemonSet created pod network interfaces via the primary CNI with no netns errors.

   If /var/run is not a symlink to /run on your version, edit the DaemonSet and change the volume path:

   ...
           - name: host-run-netns
             hostPath:
               path: /var/run/netns/
   

   Skipping the patch in that case can prevent new pods from scheduling, surfacing in the pod’s events as:

   Warning  FailedCreatePodSandBox  ...  no net namespace /var/run/netns/cni-... found: failed to Statfs ...: no such file or directory
   

Configure a multi-homed pod

Installing Multus doesn’t do anything on its own: A pod only gets a second network interface once you define a NetworkAttachmentDefinition and attach it to that pod.

The steps below use the bridge CNI type, which connects two Ethernet segments together in a protocol-independent way — packets are forwarded based on Ethernet address rather than IP address, so all protocols pass through transparently at Layer 2. For containers or VMs, a bridge connects each one’s virtual interface to the host network, letting them communicate.

1. Configure a bridge interface on your Talos node. Replace <INTERFACE_NAME> with your node’s actual interface (for example, eno1).

Check whether your node’s interface is DHCP-managed:

  talosctl --nodes <node-ip> get operatorspecs

If this lists an entry like dhcp4/<interface>, your node is DHCP-managed — use the DHCP tab below. Otherwise, use the Static IP tab.

When using the bridge interface you must also configure a bridge on your Talos nodes. That can be done by updating Talos Linux machine configuration:

Static IP

Assigns the bridge a fixed address on your network:

Talos v1.14+

Sets the address directly on the BridgeConfig document:

cat <<EOF > br0-patch.yaml
apiVersion: v1alpha1
kind: BridgeConfig
name: br0
links:
  - <INTERFACE_NAME>
stp:
  enabled: true
addresses:
  - 172.16.1.60/24
routes:
  - destination: 0.0.0.0/0 # The route's destination network.
    gateway: 172.16.1.254 # The route's gateway (if empty, creates link scope route).
    metric: 1024 # The optional metric for the route.
EOF

Talos < v1.14

Sets the address on the legacy machine.network.interfaces field:

cat <<EOF > br0-patch.yaml
machine:
  network:
    interfaces:
      - interface: br0
        addresses:
          - 172.16.1.60/24
        bridge:
          stp:
            enabled: true
          interfaces:
            - <INTERFACE_NAME>
        routes:
          - network: 0.0.0.0/0 # The route's network (destination).
            gateway: 172.16.1.254 # The route's gateway (if empty, creates link scope route).
            metric: 1024 # The optional metric for the route.
EOF

DHCP

Uses DHCP instead of a static address, so the bridge requests its own lease and the node stays reachable at the same address:

Talos v1.14+

DHCP is enabled on a bridge the same way as any other link: pair the BridgeConfig (with no addresses) with a DHCPv4Config document whose name matches the bridge:

cat <<EOF > br0-patch.yaml
apiVersion: v1alpha1
kind: BridgeConfig
name: br0
links:
  - <INTERFACE_NAME>
stp:
  enabled: true
---
apiVersion: v1alpha1
kind: DHCPv4Config
name: br0
EOF

Talos < v1.14

Uses dhcp: true instead of a static address:

cat <<EOF > br0-patch.yaml
machine:
  network:
    interfaces:
      - interface: br0
        dhcp: true
        bridge:
          stp:
            enabled: true
          interfaces:
            - <INTERFACE_NAME>
EOF

Apply the patch:

talosctl --nodes <node-ip> patch machineconfig --patch @br0-patch.yaml

2. Create a NetworkAttachmentDefinition referencing the bridge. Choose an IPAM subnet that doesn’t overlap with any subnet already in use on your network (including any DHCP pool), to avoid address conflicts:

   apiVersion: "k8s.cni.cncf.io/v1"
   kind: NetworkAttachmentDefinition
   metadata:
     name: bridge-conf
   spec:
     config: '{
         "cniVersion": "0.3.0",
         "type": "bridge",
         "bridge": "br0",
         "ipam": {
           "type": "host-local",
           "subnet": "192.168.100.0/24",
           "rangeStart": "192.168.100.10",
           "rangeEnd": "192.168.100.50",
           "gateway": "192.168.100.1"
         }
       }'
   

3. Attach the NetworkAttachmentDefinition to a pod or deployment. Reference it by name in the pod’s annotations:

   apiVersion: v1
   kind: Pod
   metadata:
     name: samplepod
     annotations:
       k8s.v1.cni.cncf.io/networks: bridge-conf
   spec:
     containers:
     - name: samplepod
       command: ["/bin/ash", "-c", "trap : TERM INT; sleep infinity & wait"]
       image: alpine
   

   On clusters with the restricted Pod Security Admission policy enforced, this pod definition triggers a non-blocking admission warning (allowPrivilegeEscalation, capabilities, runAsNonRoot, seccompProfile are unset). The pod still creates and runs successfully; add a securityContext matching your cluster’s policy if you want to avoid the warning.

   This walkthrough was confirmed end to end: the resulting pod reached Running with both interfaces present — the default network interface from the primary CNI, and a second interface from bridge-conf with an address in the configured subnet, both visible in the pod’s k8s.v1.cni.cncf.io/network-status annotation.

Known issues

The following are known issues when running Multus on Talos Linux. Each entry includes a workaround where one exists; these are pinned to the date they were last verified, so check the linked issue for current status before relying on them.

• install-multus-binary race condition after reboot (last verified August 13, 2026): A known bug in the install-multus-binary container can cause race problems after a node reboot. The issue is closed. Rebooting a node running Multus and checking the install-multus-binary init container’s logs afterward showed no error — the copy completed successfully with no Text file busy failure. Patch the container’s command if you do encounter it:

        initContainers:
          - name: install-multus-binary
            command:
              - "/usr/src/multus-cni/bin/install_multus"
              - "-d"
              - "/host/opt/cni/bin"
              - "-t"
              - "thick"
  

• Primary CNI plugin OOM-killed (last verified February 3, 2025): The default 50Mi memory limit on the kube-multus-ds DaemonSet is too low, which can OOM-kill the primary CNI plugin. The issue is closed. Increase the resource limits on the DaemonSet’s container:

    resources:
      limits:
        cpu: 300m
        memory: 150Mi
      requests:
        cpu: 200m
        memory: 100Mi
  

  As of PR #1510 (merged May 29, 2026), multus-daemon also supports a connectionLimit option (an integer) in daemon-config.json — for example:

  {
    "connectionLimit": 50
  }
  

Compatibility notes

Running Multus alongside certain other tools requires extra configuration. This section covers KubeVirt and Cilium specifically. If you’re not using either, you can skip it.

Using Multus with KubeVirt

If you want to use KubeVirt and expose a virtual machine to the outside world with Multus, configure the bridge type instead of macvlan or ipvlan; neither works for this case.

The KubeVirt documentation lists macvlan and ipvlan as invalid CNIs for secondary networks using a bridge interface, since a bridge interface moves the pod interface’s MAC address to the VM, leaving the pod interface with a different address, but macvlan and ipvlan require the pod interface to keep its original MAC address.

See the KubeVirt documentation for details.

Using Cilium with Multus

Cilium needs one adjustment to work correctly alongside Multus: by default, Cilium is an exclusive CNI, meaning it removes other CNI configuration files. Disable this by setting the Helm variable cni.exclusive=false. See the Cilium documentation for more.

Confirm the setting has actually taken effect before assuming it’s working. If cni.exclusive=false isn’t applied correctly, Cilium silently renames 00-multus.conf to 00-multus.conf.cilium_bak in /etc/cni/net.d/, with no error from Multus, making the failure hard to diagnose. See siderolabs/talos issue #10468.