- Introduction
- What Does Binding Exactly Mean
- 1. Masquerade Binding
- 2. Bridge Binding
- 3. Passt Binding
- 4. SR-IOV Binding
- Why Plugin Bindings Are Needed
- How IP Models Differ by Binding
- Relationship with Migration
- Common Misconceptions
- Practical Selection Criteria
- Conclusion
Introduction
When understanding KubeVirt networking, the most important choice is the binding. Even for the same VMI, the way the guest sees the network, service exposure method, performance, and live migration suitability change depending on which binding is used.
Looking at staging/src/kubevirt.io/api/core/v1/schema.go, the main interface binding types are revealed:
BridgeMasqueradeSRIOVPasstBindingBindingplugin
KubeVirt does not force a single correct network model. Instead, it provides multiple wiring approaches.
What Does Binding Exactly Mean
As the official developer guide docs/network/network-binding-plugin.md summarizes well, a binding is the layer that defines "how to connect a domain VM NIC to the guest inside the Pod."
This includes:
- Domain vNIC configuration
- Network configuration inside the Pod
- Guest delivery services like DHCP when needed
A binding is not just an API option but a guest NIC wiring strategy.
1. Masquerade Binding
The most straightforward and Kubernetes-friendly default choice.
How It Works
- The Pod receives a primary IP via CNI
- The guest receives a separate IP from an internal CIDR
- KubeVirt configures DHCP and NAT
- External communication goes through the Pod IP
Advantages
- Minimal conflict with the Pod network
- Familiar service exposure and port forwarding model
- Easy to handle in migration and general operations
Disadvantages
- The guest is not directly exposed to the network
- NAT overhead and port design considerations needed
This is the first choice to consider due to operational convenience and versatility.
2. Bridge Binding
Bridge binding is a model for connecting the guest more directly to the network.
How It Works
- Pod interface, bridge, and TAP are linked to directly connect the guest
- The guest acts as a more direct endpoint on the Pod network
- DHCP and bridge wiring are important
Advantages
- The guest can have more direct network connectivity
- Scenarios where NAT can be avoided
Disadvantages
- The Pod-side network structure is more sensitively rewired
- Operators must pay more attention to Pod IP and guest reachability
Bridge leans more toward "exposing the guest more directly" rather than "safe defaults like containers."
3. Passt Binding
schema.go places PasstBinding as a separate core binding. passt is best understood as a user-mode networking approach.
Advantages
- Provides a relatively simple connection model
- May have less configuration burden than bridge in some environments
Disadvantages
- Has trade-offs with models using direct kernel datapaths in terms of performance and features
- Feature gates, support scope, and operational compatibility must be verified
Reading pkg/network/passt and the binding plugin documentation together, you can see that passt is closer to user-mode friendly networking than "high-performance L2 direct connection."
4. SR-IOV Binding
SR-IOV is the most performance-oriented choice. However, Kubernetes, host, NIC, IOMMU, and VFIO configuration must all align.
Looking at docs/network/sriov.md, there are quite a few related components:
- SR-IOV device plugin
- SR-IOV CNI plugin
- Multus
- SR-IOV operator if needed
- KubeVirt's libvirt domain configuration logic
How It Works
- The device plugin advertises VF resources as Kubernetes resources
- Multus and CNI perform Pod namespace-side preparation
- KubeVirt configures the domain in VFIO passthrough form based on assigned PCI information
Advantages
- High performance
- Network path close to direct device passthrough
Disadvantages
- High hardware and kernel requirements
- Greater migration and hotplug constraints
- High operational complexity
SR-IOV is not a general-purpose default but a choice that trades some simplicity and flexibility for performance.
Why Plugin Bindings Are Needed
KubeVirt does not try to cover all networks with built-in bindings alone. network-binding-plugin.md explains two directions:
- Zero-code plugins
- Plugins that include sidecars or CNIs
The key is that plugins make new bindings extensible by combining domain attachment types, sidecars, and custom CNIs.
This design shows KubeVirt's intention not to put all network experimentation and extensions into core code.
How IP Models Differ by Binding
This is a point operators frequently get confused about.
Masquerade
- Pod IP and guest IP can differ
- Guest IP is based on KubeVirt DHCP and internal CIDR
Bridge
- Guest connects more directly to the network
- Has a significant effect of rewiring the Pod network
Passt
- Closer to a user-mode forwarding model
SR-IOV
- Has strong VF passthrough characteristics
- Guest has more direct device access
The answer to "who gives the IP" also changes by binding.
Relationship with Migration
Binding is not just a connectivity choice but also significantly impacts migration strategy.
- Masquerade is the most migration-friendly
- Bridge requires more caution depending on implementation and environment
- SR-IOV has significant constraints due to device passthrough characteristics
- Plugin bindings must verify documented migration method support
network-binding-plugin.md also explains that binding plugins need separate migration method declarations to support migration.
Common Misconceptions
Misconception 1: Bridge Is Always Better Than Masquerade
No. More direct connectivity can be an advantage, but operational simplicity and migration friendliness may be better with masquerade.
Misconception 2: SR-IOV Is Just a Faster NIC Option
No. It's a complex choice involving device advertising, CNI, VFIO, IOMMU, and libvirt domain configuration all together.
Misconception 3: Plugin Bindings Are Just Decorations for Core Bindings
No. It's an important design for KubeVirt to handle network extensions modularly.
Practical Selection Criteria
- For the safest default:
masquerade - When direct guest connectivity is important:
bridge - When specific user-mode networking characteristics are needed:
passt - When maximum performance and direct device access are needed:
SR-IOV
Ultimately, binding is simultaneously a performance issue and an operability/migration possibility issue.
Conclusion
KubeVirt's network bindings are the core axis determining how to wire guest NICs inside Pods. masquerade has versatility and operational convenience, bridge has more direct connectivity, passt has user-mode characteristics, and SR-IOV has high-performance device passthrough. Therefore, binding selection is not a simple API option but an architectural choice that determines the entire network model and operational strategy.
In the next article, we will look beyond primary networks at how Multus and secondary networks connect to KubeVirt.