OverlayNetwork Resource Kind

Kind: OverlayNetworkapiVersion: pivirt.hu/v1Aliases: overlay, overlays

The OverlayNetwork resource configures Open vSwitch (OVS) tunnel networks for multi-host cluster connectivity. It encapsulates Layer 2 virtual machine frames inside UDP packets (such as VXLAN or Geneve), allowing VMs on different hypervisor nodes to communicate over a shared L2 broadcast domain across L3 underlay networks.

---

Accepted Kind Aliases

In pivirtctl commands, any of the following aliases are recognized: OverlayNetwork, overlaynetwork, overlaynetworks, overlay-network, overlay-networks, overlay, overlays.

---

Example Manifests

VXLAN Multi-Host Mesh

apiVersion: pivirt.hu/v1
kind: OverlayNetwork
metadata:
  name: app-cluster-overlay
  labels:
    cluster: production
spec:
  vni: 10042
  bridge: br-int
  tunnelType: vxlan
  localIP: "192.168.1.101"
  peers:
    - "192.168.1.102"
    - "192.168.1.103"
  dstPort: 4789
  mtu: 1450 # Adjusted for VXLAN encapsulation overhead

Geneve Encapsulation

apiVersion: pivirt.hu/v1
kind: OverlayNetwork
metadata:
  name: geneve-mesh
spec:
  vni: 20001
  tunnelType: geneve
  localIP: "10.0.0.11"
  peers:
    - "10.0.0.12"
  mtu: 1442

---

Specification Reference (spec)

Field	Type	Required	Default	Description
vni	uint32	Yes		VXLAN/Geneve Network Identifier (1–16777215)
bridge	string	No	br-int	Target OVS integration bridge name
tunnelType	string	No	vxlan	Tunnel protocol: vxlan or geneve
localIP	string	Yes		Local host underlay IP address used for tunnel termination
peers	list[string]	No	[]	Remote underlay host IP addresses acting as tunnel endpoints
dstPort	int	No	4789	UDP destination port for VXLAN frames (Standard: 4789)
mtu	int	No	1450	MTU size accounting for tunnel header overhead

MTU Configuration

VXLAN encapsulation adds a 50-byte header on IPv4 underlays. When running over standard 1500-byte underlays, ensure the guest interfaces or overlay MTU is set to 1450 (or enable jumbo frames on the physical network) to prevent packet fragmentation.

---

Behaviour

• One tunnel port per peer, keyed to the VNI and tagged external_ids:pivirt-overlay=<name>, so reconcile finds exactly the ports this object created. Adding a peer adds one port; removing one removes exactly that port; a port whose type, remote, key or destination port drifted is recreated; an in-sync mesh issues no command.
• No per-VM flows. Fixed tunnel keys let the bridge’s ordinary NORMAL forwarding carry the overlay, and PortSecurity flows compose on the same bridge.
• The bridge must exist first — apply its OVSBridge before the overlay. The MTU is applied to the bridge’s internal port so guests inherit it.
• Segments ride overlays. A NetworkSegment with spec.overlay: <name> uses the overlay’s bridge and puts this host’s address on that bridge’s internal port; deleting an overlay a segment still references is refused.
• Peer membership is what the agent’s Network computes per node (N7); on a standalone node it is the operator’s list.

---

CLI Management Examples

# Apply overlay network manifest
pivirtctl apply -f overlay-app.yaml

# List all overlay networks
pivirtctl get overlays

# Inspect tunnel ports and active peer endpoints
pivirtctl describe overlay app-cluster-overlay

# Delete overlay network (cleans up OVS tunnel ports and flow rules)
pivirtctl delete overlay app-cluster-overlay