Network configuration
The Metal3 driver uses two distinct L2 segments. The Kubernetes cluster network carries pod-to-pod traffic inside the control plane cluster. The bare metal provisioning network is a separate segment where bare metal servers PXE boot. These aren't the same network, and bare metal servers have no direct access to cluster-internal services.
Why the DHCP server needs Multus​
The DHCP server runs as a pod on the control plane cluster. By default, pods can only reach the cluster network, but bare metal servers PXE boot on the provisioning network, which is unreachable from a single-interface pod.
The DHCP server is a multihomed pod with two interfaces: the first (eth0) connects to the cluster network, where Ironic runs, and the second (eth1), attached through 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 L2 segments. In lab setups where both share the same network, hostNetwork: true removes the Multus requirement. For the Helm values that configure bridge, macvlan, and host-network modes, see Infrastructure deployment.
When Ironic powers on a server, it broadcasts a DHCP discover on the provisioning network. The DHCP server responds with an IP address and the location of the iPXE bootloader. The server downloads the bootloader, then contacts Ironic over HTTP to fetch the Ironic Python Agent ramdisk, which registers with Ironic and performs hardware inspection or OS installation.
Set a host address​
A host address reserves an IPv4 address for the boot NIC through the platform DHCP server. Configure it before registration so the server can boot the inspection ramdisk. These settings control DHCP replies. They don't generate static network data for the installed OS. See Host addresses and installed-OS networking before choosing an address source.
This procedure covers the default mode without Neutron. For Neutron-managed port addresses, use Network integration.
The UI requires a platform admin outside tenant scope, with the machine management and Metal3 features enabled. You also need a Metal3 provider whose cluster reference you can read. Adding a server creates a BareMetalHost on that cluster. When you supply the BMC address, username, and password, it also creates the host's BMC credential Secret. Your access must permit those creates. With kubectl, you need permission to read and patch BareMetalHosts on the control plane cluster.
Choose an address outside platform IPAM pools and other DHCP allocation ranges. The platform doesn't reserve a manually configured host address in its IPAM database.
Configure the address in the UI​
Open Bare Metal > Machines and click the Metal3 tab, if shown. Click .
Enter the server name, provider, BMC credentials, and boot MAC as described in Add servers.
In Hardware & Network, enter IP with a prefix length, such as
192.168.100.20/24. Set Gateway and DNS Servers for that network. Separate multiple DNS addresses with commas.Click . Check that the host's IP address appears in the Metal3 list and that registration proceeds to inspection.
Configure an existing host with kubectl​
Set the equivalent annotations on an unclaimed BareMetalHost. Commands use <control-plane-context>, the cluster referenced by NodeProvider.spec.metal3.clusterRef.cluster.
kubectl --context <control-plane-context> annotate baremetalhost server-01 -n metal3-system \
metal3.vcluster.com/ip-address=192.168.100.20/24 \
metal3.vcluster.com/gateway=192.168.100.1 \
metal3.vcluster.com/dns-servers=192.168.100.53,192.168.100.54 --overwrite
The address must be IPv4 with a prefix length. Gateway and DNS values, when supplied, must also be IPv4 addresses. Check DHCP annotations for optional settings.
To verify the configuration, inspect the host's annotations and provisioning state:
kubectl --context <control-plane-context> get baremetalhost server-01 -n metal3-system -o yaml
A displayed address confirms the saved configuration. Successful inspection confirms that the server booted and contacted Ironic. See Host has no usable DHCP address if provisioning fails.
To remove a manual reservation, first ensure another address source is configured before the host's next network boot. Then remove these annotations from the unclaimed host:
kubectl --context <control-plane-context> annotate baremetalhost server-01 -n metal3-system metal3.vcluster.com/ip-address- metal3.vcluster.com/gateway- metal3.vcluster.com/dns-servers-
Don't change a claimed host's managed annotations to change a running OS's address.
Host addresses and installed-OS networking​
The DHCP reservation and the installed OS's network configuration are separate. When a claim allocates an address, the platform generates network data for the boot NIC. Without an allocated address, the default generator doesn't create network data from host annotations alone.
For installed-OS networking, configure an IPAM pool or provide explicit network data through metal3.vcluster.com/network-data or a MachineConfigTemplate. The OS image must consume the supplied configuration.
When a claim allocates a different address, the platform temporarily replaces the host's DHCP annotations. A node type's metal3.vcluster.com/dns-servers property replaces the host's DNS annotation the same way, even without an allocated address. The platform restores the operator's original values after release. See Reuse and reprovisioning.
IPAM​
For claim-allocated addresses, configure a pool on the node type:
metal3.vcluster.com/network-cidris required, and supplies the gateway and prefix. On its own, the platform derives the network address from the prefix length and skips the network address, gateway, and broadcast address, then allocates IPs sequentially from the remaining pool.metal3.vcluster.com/network-ip-rangeis optional, and restricts allocation to one or more explicit<start>-<end>ranges within that subnet. Range mode allocates every IP in the range exactly. The platform doesn't skip network or broadcast addresses within it.
The platform stores each allocation in an ipam-default ConfigMap in the platform management namespace on the management cluster. It writes the allocated IP, gateway, and DNS servers into a network-data Secret on the control plane cluster for Ironic to read during provisioning. After instance teardown completes, the platform releases the IP so a later allocation can reuse it.
The platform uses optimistic locking to serialize concurrent allocations, so two simultaneous provisioning requests don't receive the same IP. It doesn't validate the configured range against addresses already in use on the network, so make sure the range doesn't overlap with static addresses, the DHCP proxy VIP, or other DHCP servers on the provisioning network. Provisioning fails with an allocation error when all IPs in the range are in use. Size your range for the maximum number of servers you expect to run simultaneously.
For advanced configurations such as VLAN tagging or bonding, metal3.vcluster.com/network-data can supply a raw network-data document directly, overriding IPAM-based generation.
For diagnosing IP allocation failures, including how to inspect and clean up the allocation ConfigMap, see Troubleshooting.