Networks

kcore supports three network types for VMs: NAT, bridge, and VXLAN. Each type creates a Linux bridge (kbr-<name>) and optionally provides DHCP, masquerade, or overlay connectivity.

Supported network types

Type	Behaviour
NAT (default)	Linux bridge with dnsmasq DHCP (range .100–.199) and nftables masquerade + DNAT from `externalIP`. Single-node only.
Bridge	Physical NIC (or VLAN sub-interface) added as a bridge port. VMs use upstream DHCP. No local DHCP or NAT.
VXLAN	L2 overlay across nodes (VXLAN/UDP 4789). VM addresses are allocated cluster-wide for that network name (no duplicate IPs on the same overlay). Cloud-init applies static addressing; no local dnsmasq. When nodes join or leave, peer forwarding is updated on all participants. Optional outbound NAT. Same logical name on each node shares one VNI and subnet.

VXLAN in a cluster

Default network

A default network is auto-created on every node during installation. It is always NAT type and cannot be deleted or created via kctl.

Create a network

kctl create network private \
  --external-ip 192.168.40.105 \
  --gateway-ip 10.250.0.1 \
  --internal-netmask 255.255.255.0 \
  --type vxlan

kind: Network
metadata:
  name: private
spec:
  type: vxlan
  externalIp: 192.168.40.105
  gatewayIp: 10.250.0.1
  internalNetmask: "255.255.255.0"

Apply: kctl apply -f network.yaml

List, describe, delete

# One row per logical network name (example)
kctl get networks
# NAME   TYPE   GATEWAY      NETMASK         VLAN  OVERLAY  BRIDGE           NODES
# prod   vxlan  10.100.0.1   255.255.255.0   -     yes      kbr-prod         3

# Full detail: overlay flag, bridge name, every node (VTEP for VXLAN)
kctl describe network prod

# Remove (use --target-node when deleting one node’s copy of a shared name)
kctl delete network prod

VLAN tagging

NAT and bridge networks support VLAN tagging via --vlan-id. When specified, kcore creates a VLAN sub-interface (gatewayInterface.<id>) and uses it as the bridge uplink.

kctl create network vlan-net \
  --type nat \
  --vlan-id 100 \
  --external-ip 192.168.100.10 \
  --gateway-ip 10.100.0.1 \
  --internal-netmask 255.255.255.0

kind: Network
metadata:
  name: vlan-net
spec:
  type: nat
  vlanId: 100
  externalIp: 192.168.100.10
  gatewayIp: 10.100.0.1
  internalNetmask: "255.255.255.0"

Apply: kctl apply -f network.yaml

Disable VXLAN on a node

If a node should not participate in VXLAN overlays, pass --disable-vxlan during installation:

kctl node install ... --disable-vxlan

The controller will reject VXLAN network creation requests targeting that node with a FailedPrecondition error.

VM network attachment

Attach a VM to a network at creation time:

kctl create vm web-01 --network private --image ubuntu-24.04 --cpus 2 --memory 4096

kind: VM
metadata:
  name: web-01
spec:
  cpu: 2
  memoryBytes: "4G"
  storageBackend: filesystem
  storageSizeBytes: "40G"
  nics:
    - network: private
  disks:
    - image: https://...
      sha256: "<sha256>"
      format: qcow2

Apply: kctl apply -f vm.yaml

VMs on VXLAN networks receive controller-assigned static IPs (unique across the cluster for that overlay name) via cloud-init. VMs on NAT networks receive IPs from dnsmasq DHCP.