# kube-router: BGP pod networking, IPVS service proxy and network policy in one DaemonSet

> kube-router replaces the CNI plugin, kube-proxy and a network policy engine with a single Go binary per node. It fits bare-metal and on-premise clusters that already speak BGP, and it is a poor fit if you want an overlay or a managed cloud load balancer.

**cloudnativelabs/kube-router** — Kube-router, a turnkey solution for Kubernetes networking.

- Repository: https://github.com/cloudnativelabs/kube-router
- Website: https://kube-router.io
- Stars: 2,507 · Forks: 496
- Language: Go
- License: Apache-2.0
- Published: 2026-09-28 · Updated: 2026-09-28 · Language: en
- Canonical page: https://hysenlabs.com/projects/cloudnativelabs-kube-router

## The stack kube-router collapses into one DaemonSet

A typical Kubernetes cluster runs three separate things to move packets: a CNI plugin for pod addresses, kube-proxy for Service VIPs, and some policy engine for NetworkPolicy. kube-router's claim is that one DaemonSet covers all three, plus a LoadBalancer IP allocator for clusters with no cloud controller. The README states the project aims at "operational simplicity and high performance", and the feature list maps directly onto flags: --run-router for pod networking, --run-service-proxy for the IPVS service proxy, --run-firewall for NetworkPolicy, --run-loadbalancer for the address allocator.

The audience is narrow and specific. It is the operator of a bare-metal or on-premise cluster who already runs BGP on the underlay and does not want an overlay. If your cluster lives in a cloud that provides a VPC-native CNI and a load balancer controller, kube-router is solving problems you do not have. The README is explicit that the LoadBalancer allocator exists "for environments where an external cloud load balancer is not available".

## How pod routing works without an overlay

Pod networking in kube-router is direct routing driven by BGP. The README says the project uses "the BGP protocol and the GoBGP Go library" and maintains distributed pod networking state through "the native Kubernetes API", so there is no separate datastore to run alongside the cluster. go.mod confirms the dependency on github.com/osrg/gobgp/v4.

Two consequences follow. First, kube-router does not ship its own CNI plugin. The README states that "the official bridge plugin provided by the CNI project is all you need", and that kube-router will install the plugins it needs into /opt/cni/bin if they are missing. Second, because routes are advertised rather than encapsulated, your switches or routers have to accept them. The README describes a range from "a simple full node-to-node mesh to per-node peering configurations", with configuration expressed as Kubernetes annotations, and mentions MD5 password authentication and strict export policies.

The data path stays in the kernel. The README's design tenet is to "use standard Linux networking stack and toolset", with no overlays, so you troubleshoot with iptables, ipvsadm, ipset, iproute, traceroute and tcpdump. The official image ships those tools and the docs describe a pod toolbox for them.

## Service proxying with IPVS, and the externalIP validation that comes with it

The service proxy is built on the Linux kernel's LVS/IPVS rather than iptables DNAT chains. The README lists scheduling options and DSR (Direct Server Return) among the features, and describes L3 load balancing with ECMP for deployments that need high throughput and low latency. go.mod shows the userspace side of this: github.com/moby/ipvs for programming the virtual server table, alongside github.com/coreos/go-iptables and sigs.k8s.io/knftables for the rule plumbing.

One detail is worth flagging because it is not a headline feature. The README states kube-router validates externalIPs and loadBalancerIPs "against configured CIDR ranges, preventing unauthorized VIP bindings in multi-tenant clusters". That is a real operational control: in a shared cluster, a tenant who can create a Service of type LoadBalancer can otherwise claim an address that belongs to someone else. If you run multi-tenant bare metal, this is the feature to check first, and the README does not spell out the default CIDR range, so read the configuration docs before assuming it is restrictive.

## Installing kube-router and turning on the first controller

The README does not give a step-by-step install. It points at the repository, where the daemonset/ directory holds the manifests, and the project publishes an image at cloudnativelabs/kube-router. The Makefile defines IMG_NAMESPACE as cloudnativelabs and NAME as kube-router, which matches the image reference in the README badge.

The controllers are selected by flags, which the README lists as --run-router, --run-service-proxy, --run-firewall and --run-loadbalancer. The README's own feature headings use these flags in the form below:

```bash
--run-service-proxy
--run-router
--run-firewall
--run-loadbalancer
```

Each flag corresponds to one controller described in the README. Enabling --run-router gives you BGP pod networking; adding --run-service-proxy is the point at which kube-router takes over Service VIP handling and you would stop running kube-proxy.

If you build the image yourself rather than pulling it, the Dockerfile cross-compiles Go for each TARGETPLATFORM, running the builder stage on BUILDPLATFORM to avoid QEMU-emulated go build. The Dockerfile also clones kubernetes-sigs/iptables-wrappers at a pinned commit and builds it, which is how the image copes with hosts that have moved from iptables-legacy to nftables. After applying the DaemonSet, check that the CNI configuration on each node points at the bridge plugin in /opt/cni/bin; the README states kube-router installs missing plugins there itself.

## What breaks, and when kube-router is the wrong tool

The failure modes are mostly consequences of the direct-routing design. If your ToR switches will not peer BGP with the nodes, or your network team will not accept pod CIDR routes into the underlay, pod networking does not come up regardless of how the DaemonSet is configured. The README's own framing, that kube-router "will fit in perfectly" where other devices talk BGP, is the inverse of the limitation: where nothing talks BGP, the model has nothing to lean on.

There is no overlay to fall back on. Clusters that span L3 boundaries they do not control, or that need encryption between nodes at the network layer, are outside what the README describes. The same applies to cloud environments where the provider's CNI and load balancer controller are the supported path; the README positions the LoadBalancer allocator as a substitute for a cloud load balancer, not an addition to one.

The README also does not document rollback. Removing the DaemonSet leaves IPVS virtual servers, ipsets and iptables rules that kube-router programmed, and the documentation gives no procedure for unwinding them. Treat migration to and from kube-router as a planned change with a node-level test first, not something you reverse by deleting a manifest.

## kube-router against Calico, Cilium and flannel

The comparison people actually search for is kube-router versus Calico. Both do BGP-based pod routing and both enforce NetworkPolicy, but the packaging differs: kube-router is a single DaemonSet with flags selecting controllers, while Calico is a broader project with its own datastore options and a larger surface area. If you want one binary and Kubernetes-native annotation configuration, kube-router is the smaller commitment; if you want an ecosystem of policy extensions and observability integrations, Calico is the larger one. The README does not benchmark against either.

Against flannel the difference is more fundamental. Flannel is an overlay: it encapsulates pod traffic in VXLAN or a similar tunnel so the underlay never sees pod routes. kube-router advertises routes instead, which is why it needs BGP peering and why the README can say there is "no dependency on another CNI plugin" beyond the bridge plugin. Flannel works on networks that will not accept routes; kube-router performs better on networks that will.

Cilium differs in mechanism rather than packaging. It is eBPF-based, so policy and load balancing are enforced in the kernel's eBPF hooks rather than through iptables, ipsets and IPVS. kube-router's README leans the other way on purpose, describing standard Linux tools as the way you observe the data path. If your team already debugs with ipvsadm and iptables, kube-router matches that muscle memory; if you are standardizing on eBPF tooling, Cilium is the aligned choice.

## Maintenance, licence and the cost of upgrading

The repository is not archived and the last push was on 2026-09-26. Releases v2.11.0 and v2.11.1 both landed on 2026-08-17, with v2.10.0 before that on 2026-05-27, which suggests a release cadence measured in months rather than weeks. Plan upgrades around that rhythm.

The upgrade cost is concentrated in the data path. Because kube-router programs IPVS virtual servers, ipsets and iptables rules, a version bump is a change to kernel-level state on every node, not just a new container image. The repository carries an end-to-end network policy workflow (ci-e2e-netpol.yml) and a grype configuration, so there is some automated coverage, but the README does not describe a supported rollback path between versions.

The code is Apache-2.0, which permits commercial use and modification with the usual notice and patent terms. That is a permissive licence and creates no copyleft obligation on your own code. This is a description of the licence text, not legal advice; if you redistribute a modified kube-router, read the LICENSE file in the repository. One governance note: the repository contains AI_POLICY.md and AGENTS.md at the top level, so contributor expectations around AI-assisted changes are written down and should be read before sending a patch.

## Conclusion

Adopt kube-router on bare-metal or on-premise clusters where the underlay already runs BGP and you want one DaemonSet instead of a CNI plugin, kube-proxy and a separate policy engine. Do not adopt it if you need an overlay network, depend on a cloud provider's load balancer controller, or cannot peer BGP with your ToR switches. Before rollout, verify that your CNI configuration points at the bridge plugin in /opt/cni/bin, that your BGP peer configuration is expressed as annotations, and that the --run-router, --run-service-proxy and --run-firewall flags match the components you intend to replace.

## FAQ

### What is kube-router?

It is a turnkey Kubernetes networking solution distributed as a single DaemonSet or binary. With all controllers enabled it handles pod networking over BGP, an IPVS-based Service proxy, NetworkPolicy enforcement with ipsets and iptables, and a LoadBalancer IP allocator for clusters without a cloud load balancer.

### How does kube-router compare with MetalLB?

kube-router includes its own LoadBalancer IP allocator that watches Services of type LoadBalancer and assigns addresses from a configurable pool, and when combined with --advertise-loadbalancer-ip and BGP peering those addresses become reachable from outside the cluster. The README presents this as one controller among several rather than a standalone component, so the allocator is only available if you are also running kube-router for other purposes.

### How do I install kube-router?

The README does not give install steps; it points at the repository, where the daemonset/ directory holds the manifests, and the project publishes an image at cloudnativelabs/kube-router. The controllers are then selected with flags such as --run-router, --run-service-proxy, --run-firewall and --run-loadbalancer.

### Does kube-router need its own CNI plugin?

No. The README states there is no dependency on another CNI plugin and that the official bridge plugin from the CNI project is all you need. It also says kube-router will install the plugins it needs into /opt/cni/bin if it finds them missing.

### Can kube-router replace kube-proxy?

The --run-service-proxy flag enables a Service proxy implemented with the Linux kernel's LVS/IPVS features, which is the component that handles Service VIPs. The README lists it as one of the controllers that can be enabled alongside pod routing and firewall enforcement in the same binary.

## Sources

- [cloudnativelabs/kube-router on GitHub](https://github.com/cloudnativelabs/kube-router)
- [License: Apache-2.0](https://github.com/cloudnativelabs/kube-router/blob/master/LICENSE)
- [Project website](https://kube-router.io)
- [README](https://github.com/cloudnativelabs/kube-router/blob/master/README.md)
- [Releases](https://github.com/cloudnativelabs/kube-router/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/cloudnativelabs-kube-router