Show examples as

VXLAN overlay networking

VXLAN overlays provide L2 connectivity across multiple nodes, allowing VMs on different hosts to communicate on the same logical network.

Data plane

Each VXLAN network creates a Linux VXLAN device (vxlan<VNI>) using UDP port 4789. The VXLAN device is attached to a bridge (kbr-<name>), and the gateway IP is assigned to the bridge interface to serve as the subnet gateway.

VNI derivation

The VXLAN Network Identifier is derived deterministically from the network name using a djb2-style hash:

VNI = 10000 + (hash(name) % 6000)   // range 10000–15999

The same network name on different nodes produces the same VNI, which means the nodes automatically join the same overlay segment.

Peer discovery

Peer discovery uses static FDB entries. When the controller pushes a network configuration to a node, it includes the list of peer IPs (vxlanPeers). For each peer, the node adds a forwarding database entry:

bridge fdb append 00:00:00:00:00:00 dev vxlan<VNI> dst <peer_ip>

This implements head-end replication (flood-to-peers): BUM traffic is replicated to every known peer.

When a node joins or leaves a VXLAN network, the controller pushes updated configuration to the other nodes so VTEP forwarding entries stay consistent.

VM addressing

The controller allocates the next address in the subnet; addresses are not reclaimed when a VM is deleted. On VXLAN overlays, allocation is cluster-wide for a given network name, so VMs on different hosts never receive the same IP on the same overlay. Addresses are assigned via cloud-init static network configuration, not DHCP.

Outbound NAT

Outbound internet access for VMs on VXLAN networks is optional. Enable it with --enable-outbound-nat (or omit --no-outbound-nat) when creating the network. When enabled, kcore adds an nftables masquerade rule on the gateway interface so that VMs can reach external destinations.

Firewall

All kbr-* bridges are treated as trusted interfaces in the node firewall. UDP port 4789 is automatically allowed when any VXLAN network exists on the node.

Systemd ordering

VXLAN network services are started in a strict dependency order:

  1. kcore-bridge-<net> — creates the bridge and VXLAN device
  2. kcore-tap-<vm> — creates the TAP device on the bridge
  3. kcore-vm-<vm> — starts the Cloud Hypervisor VM

NAT networks insert an additional unit between steps 1 and 2: kcore-dhcp-<net> (dnsmasq).

Opt-out

Pass --disable-vxlan during node installation to prevent VXLAN network creation on that node. NAT and bridge networks continue to work normally. If a VXLAN network creation is attempted on a node with VXLAN disabled, the controller returns a FailedPrecondition error.