feat: implement CAPI failure domain contract for zones

Map existing CAPMOX zones to CAPI failure domains so that
KubeadmControlPlane automatically distributes control plane
nodes across Proxmox zones.

API changes:
- Add Nodes []string to ZoneConfigSpec for per-zone node lists
- Add ControlPlane *bool to ZoneConfigSpec (defaults to true)
- Add FailureDomains to ProxmoxClusterStatus (CAPI v1beta2 contract)
- Add spec.failureDomain to ProxmoxMachineSpec (InfraMachine contract)
- Add GetZoneNodes() helper on ProxmoxCluster
- Add FailureDomainNotReady condition reason

Controller changes:
- Add reconcileFailureDomains in cluster controller (sorted by name)
- Read Machine.Spec.FailureDomain in machine controller with
  retryable FailureDomainNotReady condition
- Use effectiveZone/effectiveAllowedNodes on MachineScope to avoid
  spec mutation from the controller
- Pass zone override to GetInClusterPools for IPAM pool selection
- Set Zone on NodeLocation in createVM
- Update scheduler to use GetEffectiveAllowedNodes()

Conversion:
- Restore Status.FailureDomains and Spec.FailureDomain in v1alpha1
  conversion webhook
- Add manual conversion stub for ProxmoxMachineSpec.FailureDomain

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: emanuelebosetti

api/v1alpha1/conversion.go

@@ -492,6 +492,14 @@ func Convert_v1alpha2_ProxmoxMachineTemplateResource_To_v1alpha1_ProxmoxMachineT
 	return Convert_v1alpha2_ProxmoxMachineSpec_To_v1alpha1_ProxmoxMachineSpec(&in.Spec, &out.Spec, s)
 }
 
+// Convert_v1alpha2_ProxmoxMachineSpec_To_v1alpha1_ProxmoxMachineSpec handles
+// the lossy conversion of ProxmoxMachineSpec from v1alpha2 to v1alpha1.
+// The FailureDomain field is intentionally dropped (it does not exist in v1alpha1
+// and is restored from annotation on ConvertTo).
+func Convert_v1alpha2_ProxmoxMachineSpec_To_v1alpha1_ProxmoxMachineSpec(in *v1alpha2.ProxmoxMachineSpec, out *ProxmoxMachineSpec, s conversion.Scope) error {
+	return autoConvert_v1alpha2_ProxmoxMachineSpec_To_v1alpha1_ProxmoxMachineSpec(in, out, s)
+}
+
 func Convert_v1beta1_ObjectMeta_To_v1beta2_ObjectMeta(in *clusterv1beta1.ObjectMeta, out *clusterv1beta2.ObjectMeta, s conversion.Scope) error {
 	if err := clusterv1beta1.Convert_v1beta1_ObjectMeta_To_v1beta2_ObjectMeta(in, out, s); err != nil {
 		return err

api/v1alpha1/proxmoxcluster_conversion.go

@@ -41,6 +41,7 @@ func (src *ProxmoxCluster) ConvertTo(dstRaw conversion.Hub) error {
 	// Restore lossy fields
 	dst.Spec.ZoneConfigs = restored.Spec.ZoneConfigs
 	dst.Status.InClusterZoneRef = restored.Status.InClusterZoneRef
+	dst.Status.FailureDomains = restored.Status.FailureDomains
 
 	clusterv1.Convert_bool_To_Pointer_bool(src.Spec.ExternalManagedControlPlane, ok, restored.Spec.ExternalManagedControlPlane, &dst.Spec.ExternalManagedControlPlane)
 

api/v1alpha1/proxmoxmachine_conversion.go

@@ -41,6 +41,9 @@ func (src *ProxmoxMachine) ConvertTo(dstRaw conversion.Hub) error {
 
 	restoreProxmoxMachineSpec(&src.Spec, &dst.Spec, &restored.Spec, ok)
 
+	// Restore FailureDomain (v1alpha2-only field, set by CAPI machine controller).
+	dst.Spec.FailureDomain = restored.Spec.FailureDomain
+
 	clusterv1.Convert_bool_To_Pointer_bool(src.Status.Ready, ok,
 		restored.Status.Initialization.Provisioned,
 		&dst.Status.Initialization.Provisioned)

api/v1alpha1/zz_generated.conversion.go

@@ -94,6 +94,12 @@ const (
 	// documents a ProxmoxMachine assigning host addresses for Cluster API.
 	ProxmoxMachineVirtualMachineProvisionedWaitingForClusterAPIMachineAddressesReason = "WaitingForClusterAPIMachineAddresses"
 
+	// ProxmoxMachineVirtualMachineProvisionedFailureDomainNotReadyReason documents
+	// a ProxmoxMachine waiting for its failure domain (zone) to be configured
+	// in the ProxmoxCluster. This is a transient condition that resolves when
+	// the zone is added to spec.zoneConfig.
+	ProxmoxMachineVirtualMachineProvisionedFailureDomainNotReadyReason = "FailureDomainNotReady"
+
 	// ProxmoxMachineVirtualMachineProvisionedVMProvisionFailedReason documents a failure
 	// during virtual machine provisioning.
 	ProxmoxMachineVirtualMachineProvisionedVMProvisionFailedReason = "VMProvisionFailed"

api/v1alpha2/conditions_consts.go

@@ -24,6 +24,7 @@ import (
 	corev1 "k8s.io/api/core/v1"
 	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
 	"k8s.io/utils/ptr"
+	clusterv1 "sigs.k8s.io/cluster-api/api/core/v1beta2"
 	"sigs.k8s.io/controller-runtime/pkg/client"
 )
 
@@ -148,6 +149,18 @@ type ZoneConfigSpec struct {
 	// +listType=set
 	// +kubebuilder:validation:MinItems=1
 	DNSServers []string `json:"dnsServers,omitempty"`
+
+	// nodes specifies the Proxmox nodes that belong to this zone.
+	// When set, machines assigned to this failure domain will only
+	// be placed on these nodes.
+	// +optional
+	// +listType=set
+	Nodes []string `json:"nodes,omitempty"`
+
+	// controlPlane indicates whether this zone is eligible for control plane machines.
+	// Defaults to true when not set.
+	// +optional
+	ControlPlane *bool `json:"controlPlane,omitempty"`
 }
 
 // IPConfigSpec contains information about available IP config.
@@ -232,6 +245,14 @@ type ProxmoxClusterStatus struct {
 	// for different machines.
 	// +optional
 	NodeLocations *NodeLocations `json:"nodeLocations,omitempty"`
+
+	// failureDomains is a slice of failure domains synced from zone configurations.
+	// This field is part of the Cluster API contract and is used by KubeadmControlPlane
+	// to distribute control plane machines across zones.
+	// +optional
+	// +listType=map
+	// +listMapKey=name
+	FailureDomains []clusterv1.FailureDomain `json:"failureDomains,omitempty"`
 }
 
 // ProxmoxClusterInitializationStatus provides observations of the ProxmoxCluster initialization process.
@@ -523,6 +544,18 @@ func (c *ProxmoxCluster) addNodeLocation(loc NodeLocation, isControlPlane bool)
 	c.Status.NodeLocations.Workers = append(c.Status.NodeLocations.Workers, loc)
 }
 
+// GetZoneNodes returns the Proxmox node names for a given zone name.
+// Returns nil if the zone is not found or has no explicit nodes configured.
+func (c *ProxmoxCluster) GetZoneNodes(zoneName string) []string {
+	for _, zc := range c.Spec.ZoneConfigs {
+		if ptr.Deref(zc.Zone, "") == zoneName {
+			return zc.Nodes
+		}
+	}
+
+	return nil
+}
+
 func init() {
 	objectTypes = append(objectTypes, &ProxmoxCluster{}, &ProxmoxClusterList{})
 }

api/v1alpha2/proxmoxcluster_types.go

@@ -216,6 +216,40 @@ func TestRemoveNodeLocation(t *testing.T) {
 	require.Len(t, cl.Status.NodeLocations.ControlPlane, 0)
 }
 
+func TestGetZoneNodes(t *testing.T) {
+	cl := &ProxmoxCluster{
+		Spec: ProxmoxClusterSpec{
+			ZoneConfigs: []ZoneConfigSpec{
+				{
+					Zone:  ptr.To("zone-a"),
+					Nodes: []string{"pve1", "pve2"},
+				},
+				{
+					Zone: ptr.To("zone-b"),
+					// No nodes explicitly set.
+				},
+			},
+		},
+	}
+
+	// Zone found with nodes.
+	nodes := cl.GetZoneNodes("zone-a")
+	require.Equal(t, []string{"pve1", "pve2"}, nodes)
+
+	// Zone found without nodes.
+	nodes = cl.GetZoneNodes("zone-b")
+	require.Nil(t, nodes)
+
+	// Zone not found.
+	nodes = cl.GetZoneNodes("zone-c")
+	require.Nil(t, nodes)
+
+	// Empty ZoneConfigs.
+	empty := &ProxmoxCluster{}
+	nodes = empty.GetZoneNodes("anything")
+	require.Nil(t, nodes)
+}
+
 func TestSetInClusterIPPoolRef(t *testing.T) {
 	cl := defaultCluster()
 

api/v1alpha2/proxmoxcluster_types_test.go

@@ -65,6 +65,12 @@ type ProxmoxMachineChecks struct {
 type ProxmoxMachineSpec struct {
 	VirtualMachineCloneSpec `json:",inline"`
 
+	// failureDomain is the failure domain the machine is placed in.
+	// This field is part of the Cluster API InfrastructureMachine contract
+	// and is set by the CAPI machine controller.
+	// +optional
+	FailureDomain string `json:"failureDomain,omitempty"`
+
 	// providerID is the virtual machine BIOS UUID formatted as
 	// proxmox://6c3fa683-bef9-4425-b413-eaa45a9d6191
 	// +optional

api/v1alpha2/proxmoxmachine_types.go

@@ -1244,6 +1244,11 @@ spec:
                   description: ZoneConfigSpec is the Network Configuration for further
                     deployment zones.
                   properties:
+                    controlPlane:
+                      description: |-
+                        controlPlane indicates whether this zone is eligible for control plane machines.
+                        Defaults to true when not set.
+                      type: boolean
                     dnsServers:
                       description: dnsServers contains information about nameservers
                         used by the machines in this zone.
@@ -1328,6 +1333,15 @@ spec:
                       x-kubernetes-validations:
                       - message: IPv6Config addresses must be provided
                         rule: self.addresses.size() > 0
+                    nodes:
+                      description: |-
+                        nodes specifies the Proxmox nodes that belong to this zone.
+                        When set, machines assigned to this failure domain will only
+                        be placed on these nodes.
+                      items:
+                        type: string
+                      type: array
+                      x-kubernetes-list-type: set
                     zone:
                       description: zone is the name of your deployment zone.
                       pattern: ^[a-z0-9A-Z](?:[a-z0-9A-Z-_.]{0,61}[a-z0-9A-Z])?$
@@ -1412,6 +1426,38 @@ spec:
                 x-kubernetes-list-map-keys:
                 - type
                 x-kubernetes-list-type: map
+              failureDomains:
+                description: |-
+                  failureDomains is a slice of failure domains synced from zone configurations.
+                  This field is part of the Cluster API contract and is used by KubeadmControlPlane
+                  to distribute control plane machines across zones.
+                items:
+                  description: |-
+                    FailureDomain is the Schema for Cluster API failure domains.
+                    It allows controllers to understand how many failure domains a cluster can optionally span across.
+                  properties:
+                    attributes:
+                      additionalProperties:
+                        type: string
+                      description: attributes is a free form map of attributes an
+                        infrastructure provider might use or require.
+                      type: object
+                    controlPlane:
+                      description: controlPlane determines if this failure domain
+                        is suitable for use by control plane machines.
+                      type: boolean
+                    name:
+                      description: name is the name of the failure domain.
+                      maxLength: 256
+                      minLength: 1
+                      type: string
+                  required:
+                  - name
+                  type: object
+                type: array
+                x-kubernetes-list-map-keys:
+                - name
+                x-kubernetes-list-type: map
               inClusterIPPoolRef:
                 description: inClusterIPPoolRef is the reference to the created in-cluster
                   IP pool.