Skip to main content

Networking

vMetal uses two networks. The Kubernetes cluster network carries pod-to-pod traffic inside the control plane cluster. The bare metal provisioning network is a separate L2 segment where bare metal servers PXE boot. It is not the same as the control plane cluster's node or pod network.

The vMetal DHCP server bridges the two networks.

DHCP server and Multus CNI​

The DHCP server runs as a pod on the control plane cluster. By default, pods only have access to the cluster network. Bare metal servers PXE boot on the provisioning network, which the pod cannot reach without a second interface.

The DHCP server is a multihomed pod with two interfaces. One connects to the cluster network, where Ironic runs. A second interface, attached via Multus CNI, connects to the provisioning network where bare metal servers broadcast DHCP requests.

Use the DHCP server and Multus CNI when the bare metal servers and Ironic are on different networks. In lab setups where both share the same network, they may not be needed.

PXE boot flow​

When Ironic powers on a server, the server broadcasts a DHCP discover on the provisioning network. The vMetal DHCP server receives the request on its provisioning-network interface and responds with an IP address and the location of the iPXE bootloader.

The server downloads the bootloader via TFTP, then contacts Ironic over HTTP to fetch the Ironic Python Agent (IPA) ramdisk. The ramdisk boots in memory, registers with Ironic, and performs hardware inspection or OS installation. After installation, Ironic sets the boot device to disk and reboots the server.

IPAM​

vMetal includes built-in IP address management. Each Machine receives one IP address from the configured address pool. Set the pool on the NodeType properties, or configure a Network Environment and mark it as default.

Set metal3.vcluster.com/network-cidr to define the gateway and address range. The format is <gateway>/<prefix>. Example: 192.168.100.1/24 sets the gateway to 192.168.100.1 and allocates from 192.168.100.0/24. This property is required for IPAM.

Optionally, set metal3.vcluster.com/network-ip-range to restrict allocations to explicit ranges within the CIDR. Example: 10.0.0.20-10.0.0.30,10.0.0.40-10.0.0.50.

The platform tracks allocations across all Machines in the node type. When a Machine is deleted, its IP is released automatically.

The platform writes the allocated IP, gateway, and DNS servers into a network-data Secret. Ironic reads this Secret and applies the network configuration during provisioning. For the Metal3 provider, the DHCP server also uses the allocated IP when responding to PXE boot requests from that server.

Custom network configuration​

Set metal3.vcluster.com/network-data to supply a complete network-data JSON document directly. This overrides IPAM-based generation and ignores the network-cidr and network-ip-range properties.

Use custom network configuration when your environment requires VLAN tagging, bonding, or other configurations not covered by the IPAM properties.

For a reference of all networking properties, see Configuration.