Complete field reference for the NodeProvider resource and the property keys recognized by the Metal3 provider. For task-oriented guides with YAML examples, see Configuration.
NodeProvider
apiVersion: management.loft.sh/v1 · kind: NodeProvider
spec
NodeProviderSpec defines the desired state of NodeProvider.
| Field | Type | Required | Description |
|---|
properties | map[string]string | No | Properties are global properties that are applied to all node claims and environments managed by this provider. |
metal3 | NodeProviderMetal3 | No | Metal3 configures a node provider using metal3.io BareMetalHost resources. See spec.metal3. |
displayName | string | No | DisplayName is the name that should be displayed in the UI |
Only one provider type (bcm, kubeVirt, terraform, clusterAPI, metal3) may be set at a time. This reference covers metal3 only.
| Field | Type | Required | Description |
|---|
clusterRef | NodeProviderClusterRef | Yes | ClusterRef is a reference to connected control plane cluster in which KubeVirt operator is running See spec.metal3.clusterRef. |
deploy | Metal3ProviderDeployment | No | See spec.metal3.deploy. |
nodeTypes | Metal3NodeTypeSpec[] | Yes | NodeTypes define NodeTypes that should be automatically created for this provider. See spec.metal3.nodeTypes. |
| Field | Type | Required | Description |
|---|
cluster | string | Yes | Cluster is the connected cluster the VMs will be created in |
namespace | string | Yes | Namespace is the namespace inside the connected cluster holding VMs |
| Field | Type | Required | Description |
|---|
enabled | boolean | Yes | Enabled controls whether Multus CNI is deployed into the cluster. |
helmValues | string | No | HelmValues is raw YAML that will be passed as values to the Multus Helm chart. |
| Field | Type | Required | Description |
|---|
enabled | boolean | Yes | Enabled controls whether the DHCP server is deployed into the cluster. |
chartRepo | string | No | ChartRepo overrides the Helm chart repository used to install the DHCP server. |
chart | string | No | Chart overrides the Helm chart name used to install the DHCP server. |
version | string | No | Version overrides the Helm chart version used to install the DHCP server. |
helmValues | string | No | HelmValues is raw YAML that will be passed as values to the DHCP Helm chart. |
| Field | Type | Required | Description |
|---|
enabled | boolean | Yes | Enabled controls whether Metal3 and Ironic are deployed into the cluster. |
chartRepo | string | No | ChartRepo overrides the Helm chart repository used to install Metal3. |
chart | string | No | Chart overrides the Helm chart name used to install Metal3. |
version | string | No | Version overrides the Helm chart version used to install Metal3. |
helmValues | string | No | HelmValues is raw YAML that will be passed as values to the Metal3 Helm chart. |
| Field | Type | Required | Description |
|---|
providerRef | string | No | ProviderRef is the node provider to use for this node type. |
properties | map[string]string | Yes | Properties returns a flexible set of properties that may be selected for scheduling. |
resources | ResourceList | Yes | Resources lists the full resources for a single node. |
overhead | NodeTypeOverhead | No | Overhead defines the resource overhead for this node type. See spec.metal3.nodeTypes.overhead. |
cost | integer | No | Cost is the instance cost. The higher the cost, the less likely it is to be selected. If empty, cost is automatically calculated from the resources specified. |
displayName | string | No | DisplayName is the name that should be displayed in the UI |
name | string | Yes | Name is the name of this node type. |
metadata | ManagedNodeTypeObjectMeta | Yes | Metadata holds metadata to add to this managed NodeType. See spec.metal3.nodeTypes.metadata. |
bareMetalHosts | Metal3BareMetalHosts | No | BareMetalHosts is a list of BareMetalHosts to use for this NodeType. See spec.metal3.nodeTypes.bareMetalHosts. |
NodeTypeOverhead defines the resource overhead for a node type.
| Field | Type | Required | Description |
|---|
kubeReserved | ResourceList | No | KubeReserved is the resource overhead for kubelet and other Kubernetes system daemons. |
| Field | Type | Required | Description |
|---|
labels | map[string]string | Yes | Labels holds labels to add to this managed NodeType. |
annotations | map[string]string | Yes | Annotations holds annotations to add to this managed NodeType. |
| Field | Type | Required | Description |
|---|
selector | LabelSelector | No | Selector is a label selector to select the BareMetalHosts to use for this NodeType. |
Properties reference
Properties are key-value strings set on NodeProvider.spec.properties, nodeTypes[].properties, or per-Machine. The most specific level wins: Machine overrides NodeType, NodeType overrides NodeProvider.
Image
| Property | Description |
|---|
vcluster.com/os-image | Name of an OSImage resource to use as the OS for provisioned servers. Mutually exclusive with metal3.vcluster.com/image-url. |
metal3.vcluster.com/image-url | Direct HTTP URL of the OS image. Use when the image is not tracked as an OSImage resource. |
metal3.vcluster.com/image-checksum | Checksum of the OS image file. Required when using image-url. |
metal3.vcluster.com/image-checksum-type | Algorithm for image-checksum. Accepted values: md5, sha256, sha512. Defaults to md5. |
User data
| Property | Description |
|---|
vcluster.com/user-data | Inline cloud-init user data applied at first boot. The platform appends the vCluster join script automatically. |
vcluster.com/user-data-template | Go template string for user data. Receives Machine and NodeType fields as template variables. |
vcluster.com/user-data-template-secret | Reference to a Secret containing a Go template for user data. Format: <namespace>/<name>. |
vcluster.com/ssh-keys | Newline-separated SSH public keys injected into the provisioned OS. |
Networking
| Property | Description |
|---|
metal3.vcluster.com/network-cidr | CIDR pool for IPAM. Format: <gateway>/<prefix>, e.g. 192.168.100.1/24. The platform derives the allocatable range from the prefix and skips network, gateway, and broadcast addresses. Mutually exclusive with network-ip-range. |
metal3.vcluster.com/network-ip-range | Explicit IP ranges for IPAM. Format: <start>-<end>, comma-separated for multiple ranges, e.g. 10.0.0.20-10.0.0.30,10.0.0.40-10.0.0.50. Mutually exclusive with network-cidr. |
metal3.vcluster.com/dns-servers | Comma-separated DNS server IPs written into the network-data Secret, e.g. 8.8.8.8,8.8.4.4. |
metal3.vcluster.com/network-data | Raw network-data JSON document. Overrides IPAM-based generation entirely. Use for VLAN tagging, bonding, or other configurations not covered by CIDR/range allocation. |
vcluster.com/network-data-template | Go template string for the network-data JSON document. Receives the allocated IP and gateway as template variables. |
Server selection
| Property | Description |
|---|
metal3.vcluster.com/server-name | Name of a specific BareMetalHost to claim. The platform ignores the node type's label selector and claims only this server. Provisioning fails if the named server is unavailable. |