Spiderpool gives Kubernetes underlay networking and dual stack IPAM

The layer 2 access problem behind the project

Spiderpool is described as the underlay and RDMA network solution for Kubernetes, for bare metal, virtual machines and any public cloud, and it is a Cloud Native Computing Foundation sandbox project. The problem it addresses is not pod addressing, which Kubernetes already solves, but how a pod gets onto the physical network. The project enhances the capabilities of the Macvlan CNI, the ipvlan CNI and the SR-IOV CNI, and the enhancement is access to the node's layer 2 network. The advantage list for underlay CNI in the documentation is specific about why that matters. Macvlan, ipvlan and SR-IOV are the basis for supporting RDMA network acceleration, and RDMA significantly enhances performance for AI applications, latency sensitive and network I/O intensive applications, surpassing overlay network solutions in network performance. Unlike CNI solutions based on veth virtual interfaces, underlay networks eliminate layer 3 forwarding on the host, which avoids tunnel encapsulation overhead and translates into high throughput, low latency and reduced CPU utilisation for network forwarding. The audience is therefore platform teams running storage, database, middleware and AI inference clusters where the network path is the constraint.

The reasons the project lists for going underlay

The rest of the advantage list covers the properties a fabric team actually argues about. Connecting with underlay layer 2 VLAN networks enables both layer 2 and layer 3 communication for applications, and it supports multicast and broadcast communication while allowing packets to be controlled by firewalls. Data packets carry the actual IP addresses of pods, which enables direct north-south communication based on pod IPs, and this connectivity across multi cloud networks enhances flexibility. Underlay CNI can create virtual interfaces using different parent network interfaces on the host, providing isolated subnets for applications with high network overhead such as storage and observability. Each of those is a design decision with a cost on the other side. Pod IP addresses are now real addresses on your VLAN, so address management stops being a Kubernetes abstraction and becomes a fabric concern. Multicast and broadcast work, but they also mean the pod network is not isolated by default. And the requirement that the fabric can route those addresses is exactly the constraint that makes this approach unavailable in some managed cloud environments. The project says it supports bare metal, virtual machine and public cloud, and the public cloud part depends on what the provider's network will allow.

CRD based IPAM with exclusive and shared pools

The IPAM side is the part most operators will touch first, and it is built on Custom Resource Definitions. Spiderpool provides exclusive and shared IP address pools with various affinity settings, supports assigning static IP addresses for stateful applications such as mysql, redis and kubevirt, and allows fixed IP address ranges for stateless ones. It also supports binding and releasing cloud side IP resources through a generic IaaS Network Provider interface, which matters when your addresses come from a cloud allocation rather than a spreadsheet. Two behaviours stand out for production use. Spiderpool automates the management of exclusive IP pools to ensure excellent IP reclamation and avoid IP leakage, which is the failure mode that kills most hand rolled IPAM when a pod is deleted without releasing its address. And the project claims very good IPAM performance, with a separate document referenced for the numbers. The scope statement is broader than the underlay plugins, which is worth noting: the IPAM of Spiderpool could be available for any main CNI supporting a third party IPAM plugin, not only macvlan, ipvlan and SR-IOV, but also calico and weave as static IP usage. So the IPAM component and the underlay component can be adopted independently.

Installation that removes the Multus and RDMA prerequisites

The installation story is presented as a feature rather than a chore, and the claim is specific. By eliminating the need to manually install multiple components such as the Multus CNI, RDMA and SR-IOV, Spiderpool simplifies the installation process and decreases the number of running pods. It provides straightforward installation procedures, encapsulates the relevant CRDs, and ships detailed documentation. The repository layout shows a Helm chart in charts/ alongside the Go source in api/, cmd/, pkg/ and the tools/ directory, with a vendor/ directory, a Makefile, a VERSION file and a test/ tree, plus docs/ containing the upgrade guide. The build system in the Makefile is worth a glance if you want to build from source. It defines separate controller and agent binary groups, with the controller side covering spiderpool-controller, spiderpoolctl and spiderpool-init, and the agent side covering spiderpool-agent, spiderpool and the coordinator, and there are distinct build-bin, install-bin, agent-bin and controller-bin targets, with a build_image target that uses the commit version in the image tag. The Go module requires Go 1.25 and vendors its dependencies, with CNI plugins, the CNI specification library, cilium, the network attachment definition client, openkruise, prometheus client and OpenTelemetry among the direct requirements.

Two maintained release branches, older minors end of life

The release policy is spelled out and is stricter than many CNCF projects. The community regularly maintains specific versions and older Spiderpool minor releases are considered EOL. The maintained branches listed are release-v1.2 with its latest patch v1.2.3, and release-v1.1 with its latest patch v1.1.2, and for upgrades to new minor releases the project points at a Spiderpool Upgrade Guide in the upgrade.md document under the install directory. The recent release history shows how that policy maps onto the timeline, with v1.2.3 released on 2026-08-31, a v1.2.3-rc1 candidate on 2026-07-31, and a v1.3.0-rc0 release candidate on 2026-09-23, so a new minor is currently in candidate form while the 1.2 line carries the stable fixes. The last push to the repository was on 2026-10-20 and the repository is not archived, so development is current. Practically, this means two things for an operator. First, plan an upgrade to a new minor as a project rather than a patch, because the guide exists and the EOL policy gives you a deadline. Second, a release candidate is a test target, not a production target, and the release branch you run should be one of the two the project commits to maintaining.

Where underlay CNI is the wrong choice

The honest boundary is that underlay networking only makes sense when the underlying fabric can support it, and that is not always true. In a managed public cloud with a provider-controlled layer 2, the premise of a pod having a real address on your VLAN does not hold, and the project's support for public cloud depends on the provider's network offering what is needed. In an environment where security policy is enforced by network segmentation, giving pods real addresses on a shared VLAN can weaken isolation that the platform team relied on. There is also a class of workload that does not benefit. A cluster running stateless web services on a general purpose cloud has no latency problem that a tunnelled veth pair creates, and adopting an underlay CNI there adds operational work for no measurable gain. The alternatives differ in kind. A managed CNI with its own IPAM and overlay, such as calico, gives a simpler operational model and is the right default for most clusters. An SR-IOV based device plugin path with a vendor RDMA driver gives hardware offload without changing the pod addressing model. The reasoning that leads to Spiderpool is specific: you have measured that the network path is the bottleneck, you control the fabric, and you want pods to own real addresses. Without those three conditions it is a lot of machinery for a problem you do not have.

Editorial conclusion

Adopt Spiderpool if your cluster runs latency sensitive or high throughput workloads and you have decided that overlay tunnelling is the bottleneck, and you have the hardware or cloud network to expose layer 2 to pods. Do not adopt it if you only need stable pod addressing, since a simpler IPAM plugin covers that, or if your network cannot carry layer 2 traffic per pod. Before you install, read the upgrade guide in docs/usage/install/upgrade.md, confirm which release branch your cluster is on, since older minor releases are considered EOL, and check the charts/ directory for the configuration surface rather than assuming the defaults fit your fabric.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. Project website
3. README
4. Releases
5. spidernet-io/spiderpool on GitHub