API and Resource Definitions

August 19, 2026 · View on GitHub

BareMetalHost

Metal³ introduces the concept of BareMetalHost resource, which defines a physical host and its properties. See BareMetalHost CR or check the source code at apis/metal3.io/v1alpha1/baremetalhost_types.go for a detailed API description. See the user guide for information on how to manage hosts.

Triggering Provisioning

Several conditions must be met in order to initiate provisioning.

  1. Either spec.image.url contains a URL for a valid image file that is visible from within the cluster and from the host receiving the image, or spec.customDeploy is set.
  2. The host must have online set to true so that the operator will keep the host powered on.
  3. The host must have all of the BMC details.

To initiate deprovisioning, clear the image URL and customDeploy from the host spec.

Unmanaged Hosts

Hosts created without BMC details will be left in the unmanaged state until the details are provided. Unmanaged hosts cannot be provisioned and their power state is undefined.

Pausing reconciliation

It is possible to pause the reconciliation of a BareMetalHost object by adding an annotation baremetalhost.metal3.io/paused. Metal³ provider sets the value of this annotation as metal3.io/capm3 when the cluster to which the BareMetalHost belongs, is paused and removes it when the cluster is not paused. If you want to pause the reconciliation of BareMetalHost you can put any value on this annotation other than metal3.io/capm3. Please make sure that you remove the annotation only if the value of the annotation is not metal3.io/capm3, but another value that you have provided. Removing the annotation will enable the reconciliation again.

HostFirmwareSettings

A HostFirmwareSettings resource is used to manage BIOS settings for a host, there is a one-to-one mapping with BareMetalHosts. The resource is created during host registration. BIOS values are filled in later when they are read from Ironic. These settings are the complete actual BIOS configuration names returned from the BMC, typically 100-200 settings per host, as compared to the three vendor-independent fields stored in the BareMetalHosts firmware field.

See HostFirmwareSettings CR or check the source code at apis/metal3.io/v1alpha1/hostfirmwaresettings_types.go for a detailed API description. See the firmware settings guide for information on how to change firmware settings.

FirmwareSchema

A FirmwareSchema resource contains the limits each setting, specific to each host. This data comes directly from the BMC via Ironic. It can be used to prevent misconfiguration of the HostFirmwareSettings spec field so that invalid values are not sent to the host. The FirmwareSchema has a unique identifier derived from its settings and limits. Multiple hosts may therefore have the same FirmwareSchema identifier so its likely that more than one HostFirmwareSettings reference the same FirmwareSchema when hardware of the same vendor and model are used.

See FirmwareSchema CR or check the source code at apis/metal3.io/v1alpha1/firmwareschema_types.go for a detailed API description.

HardwareData

A HardwareData resource contains hardware specifications data of a specific host and it is tightly coupled to its owner resource BareMetalHost. The data in the HardwareData comes from Ironic after a successful inspection phase. The operator creates HardwareData when inspection completes, before the host moves from inspecting to preparing. HardwareData gets deleted automatically by the operator whenever its BareMetalHost is deleted. Deprovisioning of the BareMetalHost should not trigger the deletion of HardwareData, but a later re-inspection can recreate it (with the same name and namespace) with the latest inspection data retrieved from Ironic. HardwareData holds the same name and namespace as its corresponding BareMetalHost resource. Currently, HardwareData doesn't have Status subresource but only the Spec.

See HardwareData CR or check the source code at apis/metal3.io/v1alpha1/hardwaredata_types.go for a detailed API description.

PreprovisioningImage

A PreprovisioningImage resource is automatically created by baremetal-operator for each BareMetalHost to ensure creation of a preprovisioning image for it. In this context, a preprovisioning image is an ISO or initramfs file that contains the Ironic agent. The relevant parts of BareMetalHost are copied to the PreprovisioningImage Spec, the resulting image is expected to appear in the Status.

The baremetal-operator project contains a simple controller for PreprovisioningImages that uses images provided in the environment variables DEPLOY_ISO_URL and DEPLOY_RAMDISK_URL. More sophisticated controllers may be written downstream (for example, the OpenShift image-customization-controller).

See PreprovisioningImage CR or check the source code at apis/metal3.io/v1alpha1/preprovisioningimage_types.go for a detailed API description.

BareMetalSwitch

A BareMetalSwitch resource represents a Top-of-Rack network switch that can be accessed to manage the switch ports connecting BareMetalHosts to the network. When the BareMetalSwitch controller is enabled, the operator watches BareMetalSwitch resources and generates an INI-format configuration file that is written to a Kubernetes secret. This secret is expected to be mounted into the Ironic networking service, which in turn reads it to know how to connect to each switch and configure port VLANs during bare metal provisioning. Each BareMetalSwitch references a credentials secret containing the authentication details needed to access the switch. If a switch's credential secret is missing or misconfigured, the controller skips that switch and continues generating config for the remaining healthy switches.

See BareMetalSwitch CR for a detailed API description.

The BareMetalSwitch controller is enabled when IRONIC_NETWORKING_ENABLED is true. See Configuration.

HostFirmwareComponents

A HostFirmwareComponents resource tracks BIOS and BMC firmware versions for a host, with a one-to-one mapping to BareMetalHost. The operator creates it during registration when the provisioner reports firmware components. Desired updates are listed in spec.updates as component name and image URL pairs. Those updates are applied in preparing, or on a provisioned host during servicing when a matching HostUpdatePolicy allows it.

See HostFirmwareComponents CR for a detailed API description. See the firmware updates guide for how to apply firmware updates.

HostUpdatePolicy

A HostUpdatePolicy resource opts a host into live firmware changes while it is provisioned. The name must match the BareMetalHost. spec.firmwareSettings and spec.firmwareUpdates can each be set to onPreparing (default preparing-time behavior) or onReboot (apply on the next reboot of a provisioned host, which sets operationalStatus to servicing).

See HostUpdatePolicy CR for a detailed API description. See the live updates guide.

BMCEventSubscription

A BMCEventSubscription resource registers a webhook destination on a host BMC so that hardware events can be forwarded. It references a BareMetalHost by name and an optional secret of HTTP headers to send with each notification.

See BMCEventSubscription CR for a detailed API description.

DataImage

A DataImage resource attaches a virtual-media image (for example an ISO) to a BareMetalHost. The name must match the BareMetalHost. The controller attaches spec.url via the BMC and reports the currently attached image in status.

See DataImage CR for a detailed API description.

HostClaim

⚠️ Under development. This API is not ready for use. The controller is not functional yet; the CRD exists for early review only.

A HostClaim selects and binds a BareMetalHost, then copies provisioning fields (image, user/network/meta data, custom deploy, power) onto that host. It is an alternative to writing those fields directly on the BareMetalHost, typically used when a consumer such as Cluster API claims hardware. The HostClaim controller is disabled by default and is enabled with the -hostclaims flag.

See HostClaim CR for a detailed API description.

HostDeployPolicy

⚠️ Under development. This API is not ready for use. It is part of the HostClaim work; the controller is not functional yet.

A HostDeployPolicy restricts which namespaces may bind BareMetalHosts in the policy's namespace via HostClaim (spec.hostClaimNamespaces).

See HostDeployPolicy CR for a detailed API description.

HostNetworkAttachment

⚠️ Under development. This API is not ready for use. The controller is not functional yet; the CRD exists for early review only.

A HostNetworkAttachment describes switchport configuration (access, trunk, or hybrid VLAN mode) that a BareMetalHost can reference from spec.networkInterfaces. The BareMetalSwitch controller uses this together with BareMetalSwitch resources to generate Ironic networking configuration.

See HostNetworkAttachment CR for a detailed API description.