How to fix cni plugin not initialized in Kubernetes

KubernetesINTERMEDIATEHIGHUpdated Dec 6, 2025· 116 views

Azure CNI overlay networking fails due to Network Security Group (NSG) misconfigurations, SNAT routing issues, or IP address exhaustion. Pods cannot communicate across nodes or reach external services. Fix by reviewing NSG rules, ensuring pod CIDR capacity, and verifying CNI plugin initialization.

Quick fix

Fixes cni plugin not initialized

kubectl get nodes -o wide
kubectl describe node <node-name> | grep -A5 "Conditions"
kubectl get pods -n kube-system | grep cni
  1. Verify node and CNI plugin status
  2. Check NSG rules for pod traffic
  3. Verify pod CIDR availability
  4. Check azure-ip-masq-agent configuration
kubernetes — error
kubectl get nodes -o wide
kubectl describe node <node-name> | grep -A5 "Conditions"
kubectl get pods -n kube-system | grep cni
cni plugin not initialized

What this error means

Azure CNI overlay enables pods to use Azure virtual network IP addresses directly (no encapsulation). When overlay fails, the CNI plugin cannot initialize on nodes, preventing pods from receiving network interfaces. Common causes: NSG blocking pod traffic, SNAT misconfiguration, or node IP pool exhaustion.

Typical symptoms

  • Nodes show "cni plugin not initialized" condition
  • Pods pending indefinitely, unable to schedule
  • Pod-to-pod connectivity broken across nodes
  • External traffic from pods fails (DNS, HTTP)
  • Intermittent connectivity (routing inconsistent)
  • Windows cluster: "CniDownloadTimeoutVMExtensionError"
  • Cluster upgrade to overlay mode stuck

Common causes

  1. NSG (Network Security Group) denying pod CIDR traffic
  2. External hosts IP range conflicts with pod CIDR
  3. SNAT misconfiguration via azure-ip-masq-agent
  4. Pod CIDR or subnet IP pool exhausted
  5. CNI plugin download failed (firewall/networking)
  6. Overlay mode upgrade on unsupported Kubernetes version
  7. Network policies incompatible with overlay mode

How to fix "cni plugin not initialized"

1Verify node and CNI plugin status

Check if nodes are ready and CNI initialized:

bash
kubectl get nodes -o wide
kubectl describe node <node-name> | grep -A5 "Conditions"
kubectl get pods -n kube-system | grep cni

Look for "cni plugin not initialized" condition. If present, CNI pods may not be running.

2Check NSG rules for pod traffic

Azure NSG rules may block overlay traffic:

bash
az network nsg rule list --resource-group <rg> --nsg-name <nsg-name> -o table

Ensure rules allow:
- Node CIDR ↔ Pod CIDR (all ports/protocols)
- Pod CIDR ↔ Pod CIDR (all ports/protocols)
- Pod CIDR → External (outbound)

Add missing rules if needed.

3Verify pod CIDR availability

Check if pod IP pool is exhausted:

bash
kubectl get nodes -o wide
kubectl describe node <node-name> | grep -A2 "Pod CIDR"

Ensure:
- Pod CIDR range is large enough (default 192.168.0.0/16)
- Nodes have available IPs (check allocatable IPs)
- No external hosts using pod CIDR range

4Check azure-ip-masq-agent configuration

SNAT routing misconfiguration breaks outbound traffic:

bash
kubectl get configmap -n kube-system azure-ip-masq-agent-config -o yaml

If problematic nonMasqueradeCIDR entries exist, fix them:

bash
kubectl edit configmap -n kube-system azure-ip-masq-agent-config
# Remove problematic CIDR entries
kubectl rollout restart daemonset -n kube-system azure-ip-masq-agent
5Test pod connectivity

Debug networking with a test pod:

bash
kubectl run -it --rm debug --image=busybox --restart=Never -- sh
# Inside pod:
ping <external-host>
nslookup kubernetes.default
nc -zv <service-ip> <port>

If connectivity fails, network rules are blocking traffic.

6Verify cluster configuration

Check AKS cluster overlay settings:

bash
az aks show --resource-group <rg> --name <cluster> --query networkProfile

Should show:
- networkPlugin: azure
- networkPluginMode: overlay (for overlay)
- podCidr configured

7Check CNI logs for errors

Review CNI plugin logs:

bash
kubectl logs -n kube-system -l k8s-app=azure-cni -f
kubectl logs -n kube-system -l k8s-app=azure-ip-masq-agent

Look for download failures, IP allocation errors, or SNAT issues.

Advanced notes

Azure CNI overlay differs from kubenet; pods use cluster IPs directly. NSG rules are the primary cause (80%+ of issues)—review all rules carefully. Overlay upgrade requires Kubernetes 1.22+ and clean migration path (remove network policies first). Dynamic IP Allocation incompatible with overlay. Use new Microsoft Connectivity Analysis Tool for complex diagnostics.

Frequently asked questions

What does "cni plugin not initialized" mean?
Azure CNI overlay enables pods to use Azure virtual network IP addresses directly (no encapsulation). When overlay fails, the CNI plugin cannot initialize on nodes, preventing pods from receiving network interfaces. Common causes: NSG blocking pod traffic, SNAT misconfiguration, or node IP pool exhaustion.
How do I fix "cni plugin not initialized"?
Azure CNI overlay networking fails due to Network Security Group (NSG) misconfigurations, SNAT routing issues, or IP address exhaustion. Pods cannot communicate across nodes or reach external services. Fix by reviewing NSG rules, ensuring pod CIDR capacity, and verifying CNI plugin initialization.
What causes "cni plugin not initialized"?
NSG (Network Security Group) denying pod CIDR traffic External hosts IP range conflicts with pod CIDR SNAT misconfiguration via azure-ip-masq-agent
Is the "cni plugin not initialized" error serious?
Yes. This is a high-severity error that usually blocks work until it is fixed, but the steps above resolve it.

Official resources & further reading