CNI (Container Network Interface)

The CNCF standard that Kubernetes uses for pod networking

What Is CNI?

CNI (Container Network Interface) is a CNCF specification that defines a standard interface between container runtimes and network plugins. It answers one question: how does a container get a network interface, an IP address, and connectivity?

The Plugin Contract

CNI plugins are ordinary executables. The container runtime invokes them with environment variables and a JSON config on stdin. The plugin performs its work and returns a JSON result on stdout.

How the Runtime Invokes a Plugin

    # Example: runtime invoking the bridge plugin for ADD

    $ CNI_COMMAND=ADD \

      CNI_CONTAINERID=abc123def456 \

      CNI_NETNS=/var/run/netns/abc123 \

      CNI_IFNAME=eth0 \

      CNI_PATH=/opt/cni/bin \

      /opt/cni/bin/bridge < /etc/cni/net.d/10-bridge.conflist


    # Plugin returns JSON result on stdout:

    {
  "cniVersion": "1.0.0",
  "interfaces": [{ "name": "eth0", "sandbox": "/var/run/netns/abc123" }],
  "ips": [{ "address": "10.244.1.5/24", "gateway": "10.244.1.1" }],
  "routes": [{ "dst": "0.0.0.0/0", "gw": "10.244.1.1" }],
  "dns": { "nameservers": ["10.96.0.10"] }
}
  

File Locations

    /opt/cni/bin/            Plugin binaries

      bridge

      ptp

      macvlan

      ipvlan

      vlan

      host-local          IPAM plugin

      dhcp                IPAM plugin

      static              IPAM plugin

      portmap             Meta plugin

      bandwidth           Meta plugin

      flannel             3rd-party plugin

      calico              3rd-party plugin


    /etc/cni/net.d/           Configuration files

      10-bridge.conflist  Loaded in alphabetical order

      99-loopback.conf
  

IPAM (IP Address Management) Plugins

IPAM is separated from network plumbing by design. The network plugin calls the IPAM plugin to allocate/release IPs. This separation means any network plugin can work with any IPAM plugin.

host-local Configuration Example

{
  "type": "host-local",
  "ranges": [
    [{
      "subnet": "10.244.1.0/24",
      "rangeStart": "10.244.1.10",
      "rangeEnd": "10.244.1.250",
      "gateway": "10.244.1.1"
    }]
  ],
  "routes": [{ "dst": "0.0.0.0/0" }],
  "dataDir": "/var/lib/cni/networks"
}

Network Plugins (Reference Implementations)

The CNI project ships several reference plugins that handle the actual network plumbing. Third-party plugins (Calico, Cilium, Flannel) often build on or replace these.

Plugin Chaining

CNI supports executing multiple plugins in sequence via a conflist (configuration list). Each plugin receives the result of the previous plugin and can augment it. This is how additional features like port mapping and bandwidth limiting are layered on.

1. bridge

   Create veth, attach to bridge, assign IP

2. portmap

   Setup iptables DNAT for hostPort

3. bandwidth

   Apply tc (traffic control) rate limits

Conflist Example

{
  "cniVersion": "1.0.0",
  "name": "my-k8s-network",
  "plugins": [
    {
      "type": "bridge",
      "bridge": "cni0",
      "isGateway": true,
      "ipMasq": true,
      "ipam": {
        "type": "host-local",
        "ranges": [[{ "subnet": "10.244.1.0/24" }]],
        "routes": [{ "dst": "0.0.0.0/0" }]
      }
    },
    {
      "type": "portmap",
      "capabilities": { "portMappings": true }
    },
    {
      "type": "bandwidth",
      "capabilities": { "bandwidth": true }
    }
  ]
}

How CNI Wires a Pod (Detailed Flow)

This is the full sequence from kubelet deciding to create a pod to the pod having a working network interface. Understanding this flow is essential for debugging networking failures.

1. kubelet creates pod sandbox
   kubelet calls CRI RunPodSandbox(). The CRI runtime (containerd/CRI-O) creates a pause container — a minimal container whose sole purpose is to hold the network namespace. All other containers in the pod will share this namespace.
2. CRI creates network namespace
   The runtime calls unshare(CLONE_NEWNET) to create a new network namespace for the sandbox. At this point it has only a loopback interface.
3. CRI invokes CNI ADD
   The runtime sets CNI_COMMAND=ADD, CNI_NETNS=/proc/<pid>/ns/net, CNI_IFNAME=eth0, and pipes the conflist JSON to the first plugin binary on stdin.
4. CNI plugin creates veth pair
   The plugin creates a veth pair. One end stays in the host namespace (attached to a bridge or routed), the other is moved into the pod's network namespace.
5. Attach to bridge or setup routing
   Bridge plugins attach the host-side veth to a bridge (e.g., cni0). Routing plugins (Calico/ptp) add a host route for the pod IP instead.
6. Call IPAM plugin
   The network plugin invokes the IPAM plugin (e.g., host-local) to allocate an IP address from the configured range. IPAM writes the allocation to its state file.
7. Configure pod namespace
   The plugin enters the pod's namespace and configures: IP address on eth0, default route to the gateway, DNS in /etc/resolv.conf (typically pointing to kube-dns at 10.96.0.10).
8. Return result to CRI / kubelet
   The plugin chain returns a JSON result (IPs, routes, interfaces, DNS) to stdout. The CRI runtime passes this back to kubelet, which records the pod's IP in the API server.

CNI vs Docker Networking

Docker has its own networking model called CNM (Container Network Model), implemented by libnetwork. Kubernetes chose CNI instead. Understanding why illuminates fundamental design differences.

Popular CNI Plugins

Plugin Deep Dive

Comparison: Bridge vs Routing Data Planes