containernetworking/plugins: the reference CNI plugin set for Kubernetes and container runtimes

What the CNI plugin set actually solves

A container runtime needs to move a network interface into a network namespace, give it an address, and set up the routing and firewall rules that make it reachable. The CNI specification defines the contract for that work, but a specification does not ship binaries. This repository ships them. It is the reference implementation maintained by the CNI team, and it is the set most runtimes reach for when they need a working default.

The audience is narrower than the name suggests. If you run Kubernetes with a distribution that already bundles a network provider, you are unlikely to touch these binaries directly. The people who do care are runtime authors, platform engineers debugging why a pod has no address, and anyone writing a custom CNI plugin who wants a working example to copy from. The README lists a sample plugin for exactly that last case.

Main, IPAM and meta: how the three plugin classes divide the work

The README splits the plugins into three groups, and the split reflects how CNI chains work. Main plugins create or move interfaces: bridge creates a bridge and attaches the host and container to it, ptp creates a veth pair, macvlan assigns a new MAC address and forwards traffic to the container, ipvlan adds an ipvlan interface, vlan allocates a vlan device, host-device moves an already-existing device into the container, dummy creates a dummy device, and loopback sets the loopback interface up. Windows has its own two: win-bridge and win-overlay.

IPAM plugins answer a different question: which address does the interface get. host-local keeps a local database of allocated IPs, dhcp runs a host daemon that makes DHCP requests on behalf of the container, and static hands a single IPv4 or IPv6 address to the container, which the README describes as useful for debugging.

Meta plugins run after the interface exists and adjust it. tuning changes sysctl parameters on an existing interface, portmap uses iptables to map host ports into the container, bandwidth limits traffic with traffic control tbf on ingress and egress, sbr configures source-based routing for the interface it is chained from, and firewall adds iptables or firewalld rules to allow traffic to and from the container.

The practical consequence of this split is that a single CNI configuration file usually names several plugins in sequence. A typical chain is bridge for the interface, host-local for the address, and portmap plus tuning for the post-configuration. Nothing in the repository enforces a particular combination; the runtime reads your config and calls each plugin in order.

Building the plugin binaries from source

The README points at CONTRIBUTING.md for build and test instructions rather than repeating them, and the repository root carries the scripts: build_linux.sh, build_windows.sh, test_linux.sh and test_windows.sh. The module declares go 1.26.0 in go.mod, so the toolchain version is not left to guesswork.

A Linux build from a checkout is a single script invocation:

./build_linux.sh

The README does not spell out the output directory or the CNI binary path, so the only installation detail that can be stated from the repository is which script produces which platform's binaries: build_linux.sh for the Linux plugins and build_windows.sh for the Windows ones, including win-bridge and win-overlay. The two scripts are separate, so a Linux build does not give you the Windows plugins.

Configuration lives separately from the binaries, as a JSON file naming the plugins in the order they should run. The README does not print a full example configuration, so treat the plugin list above as the source for which names are valid rather than copying a config from an external tutorial.

Where the set is the wrong tool

The most important limitation is that this repository is a plugin collection, not a network fabric. host-local maintains a local database of allocated IPs, which means address allocation is scoped to the node. Nothing here distributes routes between nodes or coordinates address ranges across a cluster. If you need pods on different hosts to reach each other without an external routing layer, this set alone does not provide it.

The second limitation is platform scope. The Linux and Windows plugins are built by separate scripts and cover different feature sets. win-bridge and win-overlay are the only two Windows main plugins listed, so a Linux configuration that leans on macvlan, ipvlan or sbr has no Windows equivalent in this repository.

The third is that several plugins depend on host facilities rather than implementing them. portmap and firewall are iptables or firewalld based, so the host must have those tools and the rules must be compatible with whatever else manages the host firewall. dhcp requires a daemon running on the host. bandwidth relies on traffic control tbf. If your environment has replaced iptables with something else, or you cannot run a host daemon, those plugins are not a fit.

Finally, static is documented as useful for debugging, not as an allocation strategy. Reading it as a production IPAM option would be a mistake.

How this differs from Calico, Cilium and Flannel

The honest comparison is that these are different layers. Calico, Cilium and Flannel are network providers: they decide how addresses are allocated across a cluster, how traffic moves between nodes, and often how policy is enforced. They typically ship or depend on CNI plugins to do the per-container interface work, and those plugins are frequently this repository's binaries or forks of them.

The difference in approach shows up in what each side owns. host-local owns a node-local database and nothing else. A provider owns the cluster-wide address plan and the cross-node path, which is why providers usually replace host-local with their own IPAM plugin rather than using this one. Similarly, portmap maps ports with iptables on a single host, while a provider may implement service routing and policy at a different point in the stack entirely.

So the choice is not this set versus a provider. It is whether you need the provider layer at all. A single-node test environment, a CI job that needs a pod network, or a runtime integration test can run on these plugins alone. A multi-node cluster cannot.

Maintenance, releases and licence

The repository is not archived, and the last push was on 2026-09-21. Recent releases are v1.9.1 on 2026-03-16, v1.9.0 on 2025-12-09 and v1.8.0 on 2025-09-01. The dependency set in go.mod is current enough to be informative: containernetworking/cni v1.3.0 for the spec types, vishvananda/netlink v1.3.1 for interface manipulation, coreos/go-iptables v0.8.0 and networkplumbing/go-nft v0.4.0 for the rule-based plugins, and Microsoft/hcsshim v0.14.1 for the Windows path.

Upgrade cost is mostly about the CNI spec version. The plugins depend on cni v1.3.0, and a runtime that speaks an older spec may not accept configurations the newer plugins expect. Because the binaries sit in a shared directory and are picked up by scanning, an upgrade is a file replacement, but the configuration files naming the plugin chain are yours and are not touched by the build scripts. That means an upgrade can change plugin behaviour without changing your config, which is worth testing on one node before rolling out.

The licence is Apache-2.0, which is permissive and permits redistribution and modification with the usual notice and attribution conditions. Whether that fits a specific product or distribution is a question for your own review; the repository ships the LICENSE file and nothing here changes its terms.

Editorial conclusion

Adopt containernetworking/plugins if you are building or debugging a CNI-based container runtime and need the reference binaries for bridge, host-local, portmap or loopback. Do not adopt it if you expect a full cluster networking product: there is no overlay control plane, no route distribution and no cross-node IPAM here, so Calico, Cilium or Flannel remain the right layer above it. Before rollout, verify which plugins your runtime actually invokes, confirm the CNI spec version your runtime expects against the cni v1.3.0 dependency in go.mod, and check whether you need the Windows binaries from build_windows.sh separately.

Frequently asked questions

Official sources

1. containernetworking/plugins on GitHub
2. Issues
3. License: Apache-2.0
4. README
5. Releases