Multus Secondary Interface Attachment Fix

Threat/Impact Level: HIGH | Downtime Risk: HIGH | Time to Fix: 15–30 mins

TL;DR

• What broke: Multus CNI cannot attach a secondary interface to your pod. The pod enters ContainerCreating indefinitely or crashes. Network-dependent workloads (SR-IOV, DPDK, storage replication) are dead.
• How to fix it: Validate the NetworkAttachmentDefinition IPAM config, confirm the master NIC exists on the node, verify the Multus pod annotation syntax, and check RBAC permissions for the net-attach-def resource.
• Shortcut: Use our Client-Side Sandbox above to auto-refactor your failing NAD YAML or pod annotation without leaking your cluster config.

Warning  FailedCreatePodSandBox  kubelet  Failed to create pod sandbox:
  rpc error: code = Unknown desc = failed to create pod network sandbox:
  [failed to create network attachment for pod "default/my-app-7d4f9b-xkp2q"
  in namespace "default": error adding container to network "sriov-net":
  failed to create network attachment: no IP addresses available in range set:
  192.168.1.0/24

failed to find network attachment definition "default/macvlan-conf"
failed to delegate add: failed to find plugin "macvlan" in path [/opt/cni/bin]
cannot find IPAM plugin "whereabouts" in /opt/cni/bin

How to Fix It (The Solution)

Step 1 — Confirm the NAD exists in the correct namespace

kubectl get network-attachment-definitions -n <pod-namespace>

The NAD must be in the same namespace as the pod unless you've configured cluster-scoped NADs. This is the #1 mistake.

Step 2 — Validate the annotation syntax on the pod spec

# Pod metadata annotations
- annotations:
-   k8s.v1.cni.cncf.io/networks: macvlan-conf   # WRONG: bare string, no namespace
+ annotations:
+   k8s.v1.cni.cncf.io/networks: default/macvlan-conf  # CORRECT: namespace/name

Step 3 — Fix the NetworkAttachmentDefinition IPAM block

Most no IP addresses available errors are a misconfigured or missing IPAM range, or Whereabouts not installed.

apiVersion: k8s.cni.cncf.io/v1
kind: NetworkAttachmentDefinition
metadata:
  name: macvlan-conf
  namespace: default
spec:
  config: '{
    "cniVersion": "0.3.1",
    "type": "macvlan",
-   "master": "eth0",
+   "master": "ens3f0",
    "mode": "bridge",
    "ipam": {
-     "type": "host-local",
-     "subnet": "192.168.1.0/24"
+     "type": "whereabouts",
+     "range": "192.168.100.0/24",
+     "exclude": [
+       "192.168.100.0/32",
+       "192.168.100.255/32"
+     ]
    }
  }'

Why whereabouts over host-local: host-local is node-local only — it cannot deduplicate IPs across nodes. In any multi-node scenario, you will get IP collisions. Whereabouts uses etcd/Kubernetes API as a distributed lock.

Step 4 — Confirm the CNI plugin binary exists on the node

# SSH to the affected node
ls /opt/cni/bin/ | grep -E 'macvlan|sriov|whereabouts'

If the binary is missing, the fix is to redeploy the correct CNI plugin DaemonSet — not to patch the NAD.

Step 5 — Fix RBAC for Multus to read NADs

# ClusterRole for multus
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: multus
rules:
- apiGroups: ["k8s.cni.cncf.io"]
  resources: ["network-attachment-definitions"]
- verbs: ["get", "list", "watch"]
+ verbs: ["get", "list", "watch", "create", "update"]  # only if using auto-provisioning

For read-only Multus deployments, get/list/watch is sufficient and correct. If your Multus pods are running as a non-default service account, verify the ClusterRoleBinding maps to the actual service account in the kube-system namespace.

Enterprise Best Practice

• Pin NAD configs to a dedicated namespace (network-infra) and use NetworkPolicy to restrict who can create/modify NADs. Treat NAD write access as equivalent to node network access.
• Use Whereabouts with a dedicated etcd backend in high-churn environments (>500 pod/min). The default Kubernetes API store for Whereabouts IP allocations becomes a bottleneck under heavy pod scheduling.
• Label nodes with available master interfaces and use nodeSelector or nodeAffinity on pods requiring specific secondary NICs. Scheduling a pod requiring ens3f0 onto a node that only has ens4f0 is a guaranteed attach failure.

💡 Tired of pasting proprietary infrastructure configs into public LLMs? Generic AI interfaces log your company's ARNs, connection strings, and private keys. StackEngine enforces client-side zero-trust boundaries—the sandbox above executes 100% locally in your browser. Drop your broken manifest above to redact secrets locally and synthesize deterministic patch drafts with your own API key.

(For CI/CD pipeline automation, install via npm i -g stackengine).

package multus.nadnamespace

violation[{"msg": msg}] {
  input.review.object.kind == "Pod"
  annotation := input.review.object.metadata.annotations["k8s.v1.cni.cncf.io/networks"]
  not contains(annotation, "/")
  msg := sprintf("Multus network annotation must be namespace-qualified: got '%v'", [annotation])
}

checkov -f nad.yaml --check CKV_K8S_MULTUS_IPAM

#!/bin/bash
# Verify master interface and CNI binary exist before workload deploy
for node in $(kubectl get nodes -o jsonpath='{.items[*].metadata.name}'); do
  kubectl debug node/$node -it --image=busybox -- \
    sh -c "ls /host/opt/cni/bin/whereabouts && ip link show ens3f0" 2>&1
done

# Prometheus alerting rule
- alert: WhereaboutsIPPoolExhausted
  expr: |
    (whereabouts_ip_allocations_total / whereabouts_ip_pool_size) > 0.85
  for: 5m
  labels:
    severity: warning
  annotations:
    summary: "Whereabouts IP pool >85% utilized — pod attach failures imminent"