CNI in kubernetes

• Container runtimes create network namespaces for containers.
• CNI defines how a plugin should be invoked to attach that namespace to a network.
• Kubernetes delegates the work of creating the pod network namespace and invoking CNI plugins to the kubelet (which coordinates with runtimes such as containerd or CRI-O).

​

How Kubernetes wires up CNI plugins

• The kubelet creates the pod’s network namespace (via the container runtime).
• After the namespace is created, the kubelet calls the configured CNI plugin binary to attach the pod to the desired network.
• The plugin creates veth pairs, attaches interfaces to host bridges or overlays, assigns IP addresses, sets up routes, and configures NAT rules if requested.

​

Where to place plugin binaries and configs

$ ls /opt/cni/bin
bridge  dhcp  flannel  host-local  ipvlan  loopback  macvlan  portmap  ptp  sample  tuning  vlan  weave-ipam  weave-net  weave-plugin-2.2.1

$ ls /etc/cni/net.d
10-bridge.conf

​

Example network configuration (bridge plugin)

{
  "cniVersion": "0.2.0",
  "name": "mynet",
  "type": "bridge",
  "bridge": "cni0",
  "isGateway": true,
  "ipMasq": true,
  "ipam": {
    "type": "host-local",
    "subnet": "10.22.0.0/16",
    "routes": [
      {
        "dst": "0.0.0.0/0"
      }
    ]
  }
}

• cniVersion: Target CNI specification version.
• name: Logical network name for this configuration.
• type: Plugin type to invoke (e.g., bridge, flannel, calico).
• bridge: Host bridge interface to use (e.g., cni0).
• isGateway: When true, the bridge gets an IP and can act as gateway for pods.
• ipMasq: When true, applies SNAT (iptables masquerade) for pod egress to non-cluster destinations.
• ipam: IP Address Management configuration:
  • type: Allocation method; host-local stores allocation state on the node. dhcp can be used for external allocation.
  • subnet: CIDR used for pod IP assignments.
  • routes: Additional routes to add in the pod namespace (e.g., default route {"dst":"0.0.0.0/0"}).

​

What happens when a pod starts

1. Kubelet asks the container runtime to create the container and its network namespace.
2. Once the pod network namespace exists, the kubelet reads /etc/cni/net.d to pick a configuration file (first by lexical order).
3. Kubelet executes the chosen plugin binary from /opt/cni/bin and provides the configuration and environment variables as required by the CNI spec.
4. The plugin sets up the pod interface (veth), attaches it to the host network (bridge, vlan, overlay), assigns an IP, configures routes, and applies NAT rules if requested.
5. Kubelet reports the allocated IP and network state back to Kubernetes components.

​

Troubleshooting checklist

• Verify plugin binaries exist: ls /opt/cni/bin
• Check configuration files: ls /etc/cni/net.d and inspect the JSON or .conflist content
• Confirm filename ordering if multiple config files are present (the first file wins)
• Match cniVersion and plugin versions to avoid incompatibilities

​

Links and references

• CNI Specification: https://github.com/containernetworking/cni
• Kubernetes networking overview: https://kubernetes.io/docs/concepts/cluster-administration/networking/
• containerd: https://containerd.io/