Networking¶

kMetal's networking model is built on Kube-OVN and gives every tenant a private virtual network on shared bare metal. The two top-level abstractions are VPCs and Subnets; both are first-class Kube-OVN custom resources, and both are what a tenant claims when they want to run a cluster.

VPC — the tenant network boundary¶

A VPC is the tenant's isolated routing domain. Under the hood it is an OVN Logical Router with its own routing table, its own ACL set, and no static path to any other tenant's VPC. The under cluster's OVN deployment maintains one VPC per tenant.

What a VPC enforces:

Cross-tenant traffic is dropped by default. Two tenants on the same physical hosts cannot reach each other's pods, services, or worker IPs — the routing tables don't list each other.
Hard multi-tenancy against the platform. A default OVN Logical Router Policy on every tenant VPC also blocks traffic destined for the kMetal external CIDR (the under cluster's API server, platform services, other tenants' load-balancer VIPs). A tenant cannot pivot from a compromised workload into the platform.
Independent IP space. Each tenant chooses their own pod and service CIDRs. Overlapping CIDRs between tenants are fine — they are isolated by the routing domain, not by global allocation.

Subnet — IP space inside a VPC¶

A Subnet is a Kube-OVN Subnet resource bound to a VPC. It defines the IP CIDR, the gateway IP, and (in VLAN mode) the physical VLAN ID or (in overlay mode) the Geneve tunnel parameters. A subnet is what a CAPI Cluster attaches to — one tenant cluster lives in one subnet inside one VPC.

A tenant can have multiple subnets per VPC. The kMetal ClusterClass exposes a network.subnet variable so multiple Cluster objects in the same VPC can each pick a different subnet for their worker VMs. This lets a single tenant build out separate dev/stage/prod clusters with separate IP planes inside one isolated network boundary.

Two modes: overlay and VLAN¶

kMetal supports two networking modes, picked at platform install time:

Overlay mode (default)¶

Tenant traffic is encapsulated in Geneve tunnels between under-cluster nodes.
The data-center switch sees only generic Geneve traffic — no per-tenant VLANs, no per-tenant switch port config.
Adding a tenant is purely a software operation; no network team involvement.
Requires MTU 9100 (jumbo frames) on the overlay transport VLAN for good performance.

Overlay is the supported mode for new deployments.

VLAN mode¶

Each tenant gets a dedicated physical VLAN on the data-center switch.
Tenant traffic crosses the wire untagged-into-the-tenant-VLAN; the switch enforces isolation in hardware.
Requires the network team to provision a VLAN per tenant on the switching fabric before kMetal can use it.
Matches existing per-tenant VLAN governance in regulated environments.

VLAN mode is available but adding tenants requires coordination with the network team.

Provider network — egress and external IPs¶

Separate from tenant VPCs, the under cluster has a provider network: a dedicated VLAN that carries tenant SNAT/egress traffic and hosts the IPs that external clients connect to.

A distributed gateway runs an external OVN Logical Router Port on every node, so any node can do SNAT for any tenant. There is no single egress chokepoint.
Tenant LoadBalancer services get External IPs allocated from this provider network. The under cluster announces those IPs into the data-center routing fabric (via static route at the edge router or 1:1 NAT).
The edge router is decoupled from kMetal — it doesn't run any Kube-OVN logic. kMetal just publishes the right IPs and the edge router handles the public-facing piece.

Where to go next¶

Networking Configuration — operator-side setup: address pools, BGP, overlay transport VLAN, MTU.
Load Balancer Configuration — tenant-facing service exposure: OVN Gateway, CCM Proxy, Tenant MetalLB, edge integration.
Hard Multi-Tenancy — how VPC isolation fits with KVM compute isolation and dedicated etcd to form kMetal's tenant boundary.