Kube-OVN: OVN-Based Virtual Networking for Kubernetes, From Overlay to Underlay

What Kube-OVN Actually Solves

Kube-OVN is a CNCF sandbox project that plugs OVN (Open Virtual Network) into Kubernetes as a CNI. The core problem it addresses is the gap between Kubernetes' default flat networking and the needs of operators running multi-tenant workloads, VMs, or bare-metal integration. Standard CNIs like Calico or Flannel give you basic pod-to-pod connectivity, but they do not give each tenant an isolated address space with its own gateways, security groups, and load balancers. Kube-OVN does. It targets clusters where you need VPC-like isolation, static IPs for stateful workloads, or direct L2/L3 connectivity to physical networks. The README lists VPC support, namespaced subnets, and VLAN/underlay mode as headline features, which tells you the intended audience: platform teams managing shared infrastructure, not developers just wanting to spin up a cluster.

The OVN Architecture Under the Hood

Kube-OVN's mechanism is to translate Kubernetes network objects into OVN logical constructs. Each subnet is backed by a logical switch, and each VPC has its own independent address space with eips, NAT gateways, security groups, and load balancers. The control plane, written in Go, watches Kubernetes resources and programs OVN northbound and southbound databases. Data plane traffic flows through Open vSwitch (OVS) on each node, which handles forwarding, ACLs, and load balancing. The README mentions a cluster-wide IPAM for multi-NIC scenarios, where Kube-OVN can allocate IPs for other CNIs like macvlan or host-device. That suggests a modular design: Kube-OVN is not just a single CNI but a network controller that can coordinate with other plugins. The distributed gateway feature means every node can act as an egress point, which spreads the load but also complicates troubleshooting. This is not a simple overlay; it is a full virtual network stack with OVN's complexity.

Getting It Running: Installation and Quick Start

The README does not include a one-line install command; it points to an installation guide on the project's documentation site. The quick start section says 'Kube-OVN is easy to install' and links to the one-step-install page, but the actual commands are not in the README. Based on typical Kube-OVN deployments, you would apply a YAML manifest that deploys the controller, OVS daemonsets, and CNI binaries. The documentation also covers setup options like choosing overlay, underlay, or VLAN mode, and there is a separate guide for multi-NIC setups. The README references a kubectl-ko tool for operations, which suggests a command-line utility for diagnostics and management. If you want static IPs for KubeVirt VMs, there is a dedicated usage page. The key takeaway: installation is not a single helm install; it requires reading the docs to pick your mode and configure subnets. The lack of a direct command in the README is a minor friction point for evaluation.

Key Features and Where They Matter

The feature list is long, and each item has a specific use case. Namespaced subnets let you give each namespace its own IP range, which is useful for isolating dev and prod environments. Static IP allocation is a must for databases or VMs where IP changes break connections. The non-primary CNI mode is interesting: Kube-OVN can run alongside Cilium or Calico as a secondary CNI, providing extra interfaces via Network Attachment Definitions. That means you can keep your existing primary CNI and still get Kube-OVN's advanced features for specific pods. Hardware offload is another differentiator, moving OVS flow tables to hardware to boost performance and save CPU. BGP support lets you expose pod IPs to external networks via BGP, which is essential for bare-metal environments. However, each feature adds configuration surface. The README does not specify which features are stable or beta, so you need to check the docs for maturity. The breadth is impressive, but it also means you will likely use only a fraction of these features in practice.

Limitations and When It Is the Wrong Tool

The biggest limitation is operational complexity. Kube-OVN is built on OVN and OVS, which are powerful but notoriously hard to debug. The README lists troubleshooting tools, but that implies you will need them. If your cluster is small or your networking needs are basic, a simpler CNI like Flannel or even Cilium in overlay mode is easier to run. Kube-OVN's multi-tenancy and VPC features are overkill for a single-team cluster. Another limitation is performance: even with hardware offload, the OVS data plane adds overhead compared to eBPF-based solutions like Cilium. The README claims underlay and VLAN modes offer 'better performance', but that is relative to overlay, not to other CNIs. Also, the project is under CNCF sandbox status, which means it is still maturing; the release cadence (v1.15.22, .23, .24 in quick succession) shows active development, but that also means frequent upgrades and potential API changes. If you need a stable, low-maintenance network, this may not be it.

Alternatives: Cilium and Calico with Different Approaches

The most direct alternative is Cilium, which uses eBPF instead of OVS. Cilium offers similar features like network policies, load balancing, and even multi-cluster, but it does so without a separate OVN control plane. The approach is fundamentally different: Cilium programs the kernel directly via eBPF, while Kube-OVN relies on userspace OVS daemons and OVN databases. That difference affects performance and debugging. Cilium is generally faster for pure overlay scenarios, but it does not natively provide VPC-level multi-tenancy or underlay/VLAN modes in the same way. Calico is another alternative, focusing on simple IP routing with BGP for on-prem deployments. Calico can do underlay networking natively, but it lacks the logical switch abstraction and VPC features. If your primary need is underlay connectivity, Calico might be simpler. If you need multi-tenancy with isolated address spaces, Kube-OVN's VPC support is more comprehensive. The choice comes down to whether you want a kernel-native approach or a virtual switch approach.

Maintenance, Upgrades, and License

Kube-OVN is licensed under Apache-2.0, which is permissive and allows commercial use without copyleft obligations. The project is under CNCF, which suggests governance and community oversight, but that does not guarantee stability. The release history shows frequent patch releases: v1.15.22, .23, and .24 were released within weeks of each other in August 2026. That indicates an active maintenance effort, but it also means you will need to track upgrades regularly. The README mentions a development guide and architecture guide, which are useful for understanding how to contribute or debug. There is no explicit upgrade path in the README, so you will need to consult the documentation for migration steps. The operational tooling, like kubectl-ko, likely helps with upgrades and diagnostics, but the complexity of OVN means upgrades can be risky. You should budget time for testing upgrades in a staging environment. The license is not a concern, but the maintenance burden is real.

Editorial conclusion

Adopt Kube-OVN if you operate Kubernetes clusters that demand multi-tenant VPCs, static IPs for workloads like KubeVirt VMs, or direct underlay connectivity to physical networks, and you have the OVS/OVN expertise to run a complex control plane. Avoid it if your networking needs are simple overlay-only, if you lack staff comfortable debugging OVN ACLs and gateways, or if you want minimal moving parts. Before committing, verify the latest release's upgrade path from your current version, test the non-primary CNI mode with your existing CNI (Cilium or Calico), and confirm hardware offload support for your specific NICs. The project's breadth is its strength, but that breadth translates into a steep learning curve and ongoing maintenance that only pays off when you need the advanced features.

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes