Networking is where most Harvester deployments succeed or struggle. Let's build it up carefully.

13.1 The layers¶

13.2 The built-in mgmt cluster network¶

Created at install time from the management interface(s): bond mgmt-bo, bridge mgmt-br. It carries:

• Kubernetes/Harvester control traffic.
• The cluster VIP.
• Optionally VM VLAN networks (you can create VM networks on mgmt if you only have one NIC pair).

With limited NICs, putting VM VLANs on mgmt is fine; trunk the switch ports and keep the management VLAN as native/untagged or specify vlan_id at install.

13.3 Custom cluster networks¶

With more NICs, separate VM data plane from management:

apiVersion: network.harvesterhci.io/v1beta1
kind: ClusterNetwork
metadata:
  name: data
---
apiVersion: network.harvesterhci.io/v1beta1
kind: VlanConfig
metadata:
  name: data-rack-a
spec:
  clusterNetwork: data
  nodeSelector:
    topology.kubernetes.io/zone: rack-a        # optional: only some nodes
  uplink:
    nics:
      - enp65s0f0
      - enp65s0f1
    linkAttributes:
      mtu: 9000
    bondOptions:
      mode: 802.3ad
      miimon: 100

Rules worth memorizing:

• A NIC can belong to only one cluster network.
• Multiple VlanConfigs can serve one cluster network across different node groups (heterogeneous NIC names). Each node can be covered by at most one VlanConfig per cluster network.
• MTU must be consistent across all VlanConfigs of a cluster network.
• A VM scheduled on a node not covered by the cluster network won't start — Harvester labels nodes (network.harvesterhci.io/<clusternetwork>=true) and the VM gets matching affinity automatically.
• Bond modes: active-backup (no switch config), 802.3ad (LACP, needs switch config), balance-tlb, balance-alb, etc.

13.4 VM networks (VLAN)¶

UI: Networks → VM Networks → Create → type L2VlanNetwork → VLAN ID → cluster network.

Underlying object:

apiVersion: k8s.cni.cncf.io/v1
kind: NetworkAttachmentDefinition
metadata:
  name: vlan100-servers
  namespace: default
  labels:
    network.harvesterhci.io/clusternetwork: data
    network.harvesterhci.io/type: L2VlanNetwork
    network.harvesterhci.io/vlan-id: "100"
  annotations:
    network.harvesterhci.io/route: '{"mode":"auto","serverIPAddr":"","cidr":"","gateway":""}'
spec:
  config: >-
    {"cniVersion":"0.3.1","name":"vlan100-servers","type":"bridge",
     "bridge":"data-br","promiscMode":true,"vlan":100,"ipam":{}}

Notes:

• ipam: {} — Harvester doesn't do DHCP for VLAN networks; your physical network (router/DHCP server) does. VMs get IPs from your existing infrastructure — exactly like port groups in vSphere.
• The route annotation lets Harvester discover the subnet/gateway (via DHCP probe in auto mode, or manual) — needed for the load balancer and guest clusters to know the CIDR.
• Untagged networks (L2VlanTrunkNetwork/untagged types depending on version) attach VMs to the native VLAN.
• VLAN trunk networks pass a range of VLANs into the guest (useful for virtual routers/firewalls like OPNsense or VyOS).
• Namespace matters: networks in default are usable by VMs in default; networks can be created in other namespaces for tenant scoping.

13.5 Management network for VMs¶

A VM can use the pod network (masquerade NAT through the host). It's convenient (no VLAN needed) but:

• The VM's IP changes across restarts/migrations.
• Inbound access requires Services/LoadBalancers.
• Not suitable for most server workloads; fine for quick tests.

13.6 Overlay networks and VPCs (Kube-OVN)¶

Recent releases integrate Kube-OVN to give OpenStack/cloud-style software-defined networking:

• VPCs — isolated L3 domains with overlapping CIDRs between tenants.
• Subnets — Harvester-managed IPAM and DHCP inside overlays.
• NAT gateways — SNAT/DNAT/EIP between VPCs and the underlay (v1.9).
• Isolated guest load balancers inside VPCs (v1.9).

This is the closest Harvester gets to Neutron tenant networks + floating IPs. It's newer than VLAN networking; read the version-specific docs on prerequisites (often enabled as an add-on), supported topologies, and limitations (e.g. live migration and LB behaviour on overlays) before committing production tenants to it.

13.7 Storage network¶

By default Longhorn replication traffic rides the management network. Configure a dedicated one:

// Setting: storage-network
{
  "vlan": 200,
  "clusterNetwork": "storage",
  "range": "172.16.200.0/24",
  "exclude": ["172.16.200.1/32"]
}

• Create the storage cluster network and its VlanConfig first.
• The range must provide one IP per Longhorn instance-manager pod (roughly nodes × a few) — be generous.
• Changing the storage network requires all VMs to be stopped (Longhorn instance managers restart). Do it early.
• Jumbo frames (MTU 9000) help noticeably for replication — ensure switch ports and every hop agree.

13.8 Load balancing¶

The built-in harvester-load-balancer provides L4 LBs:

• VM load balancers: select backend VMs by label; listeners on TCP/UDP ports; health checks.
• Guest cluster load balancers: Services of type: LoadBalancer in guest RKE2/K3s clusters, fulfilled by the Harvester cloud provider.
• IPAM modes: dhcp (LB requests an address from your DHCP server on the VLAN) or pool (from an IPPool you define).

apiVersion: loadbalancer.harvesterhci.io/v1beta1
kind: IPPool
metadata:
  name: vlan100-lb
spec:
  ranges:
    - subnet: 10.100.0.0/24
      gateway: 10.100.0.1
      rangeStart: 10.100.0.200
      rangeEnd: 10.100.0.239
  selector:
    network: default/vlan100-servers
    scope:
      - project: "*"
        namespace: "*"
        guestCluster: "*"

Under the hood the LB VIPs are announced by kube-vip (ARP in L2 mode) on Harvester nodes.

13.9 Network design patterns¶

Pattern A — two NICs (small/homelab):

eno1+eno2 → mgmt-bo (active-backup or LACP) → mgmt-br
  ├─ native VLAN 10: management + VIP
  ├─ VLAN 100, 101…: VM networks (on mgmt cluster network)
  └─ VLAN 200: storage network (on mgmt cluster network)

Pattern B — four NICs (production minimum):

eno1+eno2 (1/10G)   → mgmt     : management, VIP
ens1f0+ens1f1 (25G) → data     : VM VLANs (trunk) + storage network VLAN

Pattern C — six NICs (performance):

mgmt    : 2× 10G  management
data    : 2× 25G  VM traffic
storage : 2× 25G  Longhorn replication (MTU 9000)

← Installing Harvester · Index · Harvester storage in depth →