⚠️ Update ControlPlaneEndpoint InfraCluster contract, align CAPD to infra contracts

docs/book/src/developer/providers/contracts/control-plane.md

@@ -237,19 +237,26 @@ in the ControlPlane resource.
 type FooControlPlaneSpec struct {
     // controlPlaneEndpoint represents the endpoint used to communicate with the control plane.
     // +optional
-    ControlPlaneEndpoint APIEndpoint `json:"controlPlaneEndpoint"`
+    ControlPlaneEndpoint APIEndpoint `json:"controlPlaneEndpoint,omitempty,omitzero"`
 
     // See other rules for more details about mandatory/optional fields in ControlPlane spec.
     // Other fields SHOULD be added based on the needs of your provider.
 }
 
 // APIEndpoint represents a reachable Kubernetes API endpoint.
+// +kubebuilder:validation:MinProperties=1
 type APIEndpoint struct {
     // host is the hostname on which the API server is serving.
-    Host string `json:"host"`
-
+    // +optional
+    // +kubebuilder:validation:MinLength=1
+    // +kubebuilder:validation:MaxLength=512
+    Host string `json:"host,omitempty"`
+
     // port is the port on which the API server is serving.
-    Port int32 `json:"port"`
+    // +optional
+    // +kubebuilder:validation:Minimum=1
+    // +kubebuilder:validation:Maximum=65535
+    Port int32 `json:"port,omitempty"`
 }
 ```
 
@@ -259,6 +266,35 @@ the Cluster controller will surface this info in Cluster's `spec.controlPlaneEnd
 If instead you are developing a control plane provider which is NOT responsible to provide a control plane endpoint,
 the implementer should exit reconciliation until it sees Cluster's `spec.controlPlaneEndpoint` populated.
 
+<aside class="note warning">
+
+<h1>Compatibility with the deprecated v1beta1 contract</h1>
+
+In order to ease the transition for providers, the v1beta2 version of the Cluster API contract _temporarily_
+preserves compatibility with the deprecated v1beta1 contract; compatibility will be removed tentatively in August 2026.
+
+```go
+type FooControlPlaneSpec struct {
+    // controlPlaneEndpoint represents the endpoint used to communicate with the control plane.
+    // +optional
+    ControlPlaneEndpoint APIEndpoint `json:"controlPlaneEndpoint"`
+
+    // See other rules for more details about mandatory/optional fields in ControlPlane spec.
+    // Other fields SHOULD be added based on the needs of your provider.
+}
+
+// APIEndpoint represents a reachable Kubernetes API endpoint.
+type APIEndpoint struct {
+    // host is the hostname on which the API server is serving.
+    Host string `json:"host"`
+
+    // port is the port on which the API server is serving.
+    Port int32 `json:"port"`
+}
+```
+
+</aside>
+
 ### ControlPlane: replicas
 
 In case you are developing a control plane provider which allows control of the number of replicas of the

docs/book/src/developer/providers/contracts/infra-cluster.md

@@ -221,19 +221,26 @@ in the InfraCluster resource.
 type FooClusterSpec struct {
     // controlPlaneEndpoint represents the endpoint used to communicate with the control plane.
     // +optional
-    ControlPlaneEndpoint APIEndpoint `json:"controlPlaneEndpoint"`
+    ControlPlaneEndpoint APIEndpoint `json:"controlPlaneEndpoint,omitempty,omitzero"`
 
     // See other rules for more details about mandatory/optional fields in InfraCluster spec.
     // Other fields SHOULD be added based on the needs of your provider.
 }
 
 // APIEndpoint represents a reachable Kubernetes API endpoint.
+// +kubebuilder:validation:MinProperties=1
 type APIEndpoint struct {
     // host is the hostname on which the API server is serving.
-    Host string `json:"host"`
-
+    // +optional
+    // +kubebuilder:validation:MinLength=1
+    // +kubebuilder:validation:MaxLength=512
+    Host string `json:"host,omitempty"`
+
     // port is the port on which the API server is serving.
-    Port int32 `json:"port"`
+    // +optional
+    // +kubebuilder:validation:Minimum=1
+    // +kubebuilder:validation:Maximum=65535
+    Port int32 `json:"port,omitempty"`
 }
 ```
 
@@ -243,6 +250,35 @@ the Cluster controller will surface this info in Cluster's `spec.controlPlaneEnd
 If instead you are developing an infrastructure provider which is NOT responsible to provide a control plane endpoint,
 the implementer should exit reconciliation until it sees Cluster's `spec.controlPlaneEndpoint` populated.
 
+<aside class="note warning">
+
+<h1>Compatibility with the deprecated v1beta1 contract</h1>
+
+In order to ease the transition for providers, the v1beta2 version of the Cluster API contract _temporarily_
+preserves compatibility with the deprecated v1beta1 contract; compatibility will be removed tentatively in August 2026.
+
+```go
+type FooClusterSpec struct {
+    // controlPlaneEndpoint represents the endpoint used to communicate with the control plane.
+    // +optional
+    ControlPlaneEndpoint APIEndpoint `json:"controlPlaneEndpoint"`
+
+    // See other rules for more details about mandatory/optional fields in InfraCluster spec.
+    // Other fields SHOULD be added based on the needs of your provider.
+}
+
+// APIEndpoint represents a reachable Kubernetes API endpoint.
+type APIEndpoint struct {
+    // host is the hostname on which the API server is serving.
+    Host string `json:"host"`
+
+    // port is the port on which the API server is serving.
+    Port int32 `json:"port"`
+}
+```
+
+</aside>
+
 ### InfraCluster: failure domains
 
 In case you are developing an infrastructure provider which has a notion of failure domains where machines should be

docs/book/src/developer/providers/migrations/v1.10-to-v1.11.md

@@ -437,6 +437,7 @@ KubeadmControlPlaneTemplate `spec.template.spec` has been aligned to changes in
 Following rules have been changed or are not supported anymore; please read corresponding notes about compatibility
 for providers still implementing the v1beta1 contract.
 
+- [InfraCluster: control plane endpoint](../contracts/infra-cluster.md#infracluster-control-plane-endpoint)
 - [InfraCluster: failure domains](../contracts/infra-cluster.md#infracluster-failure-domains)
 - [InfraCluster: initialization completed](../contracts/infra-cluster.md#infracluster-initialization-completed)
 - [InfraCluster: conditions](../contracts/infra-cluster.md#infracluster-conditions)
@@ -488,6 +489,7 @@ for providers still implementing the v1beta1 contract.
 Following rules have been changed or are not supported anymore; please read corresponding notes about compatibility
 for providers still implementing the v1beta1 contract.
 
+- [ControlPlane: control plane endpoint](../contracts/control-plane.md#controlplane-endpoint)
 - [ControlPlane: machines](../contracts/control-plane.md#controlplane-machines)
 - [ControlPlane: initialization completed](../contracts/control-plane.md#controlplane-initialization-completed)
 - [ControlPlane: replicas](../contracts/control-plane.md#controlplane-replicas)

test/infrastructure/docker/api/v1alpha3/conversion.go

@@ -108,6 +108,10 @@ func (dst *DockerMachine) ConvertFrom(srcRaw conversion.Hub) error {
 		return err
 	}
 
+	if dst.Spec.ProviderID != nil && *dst.Spec.ProviderID == "" {
+		dst.Spec.ProviderID = nil
+	}
+
 	if err := utilconversion.MarshalData(src, dst); err != nil {
 		return err
 	}
@@ -141,6 +145,10 @@ func (dst *DockerMachineTemplate) ConvertFrom(srcRaw conversion.Hub) error {
 		return err
 	}
 
+	if dst.Spec.Template.Spec.ProviderID != nil && *dst.Spec.Template.Spec.ProviderID == "" {
+		dst.Spec.Template.Spec.ProviderID = nil
+	}
+
 	// Preserve Hub data on down-conversion except for metadata
 	if err := utilconversion.MarshalData(src, dst); err != nil {
 		return err

test/infrastructure/docker/api/v1alpha3/conversion_test.go

@@ -48,8 +48,9 @@ func TestFuzzyConversion(t *testing.T) {
 	}))
 
 	t.Run("for DockerMachineTemplate", utilconversion.FuzzTestFunc(utilconversion.FuzzTestFuncInput{
-		Hub:   &infrav1.DockerMachineTemplate{},
-		Spoke: &DockerMachineTemplate{},
+		Hub:         &infrav1.DockerMachineTemplate{},
+		Spoke:       &DockerMachineTemplate{},
+		FuzzerFuncs: []fuzzer.FuzzerFuncs{DockerMachineTemplateFuzzFunc},
 	}))
 }
 
@@ -87,6 +88,7 @@ func hubFailureDomain(in *clusterv1.FailureDomain, c randfill.Continue) {
 func DockerMachineFuzzFunc(_ runtimeserializer.CodecFactory) []any {
 	return []any{
 		hubDockerMachineStatus,
+		spokeDockerMachineSpec,
 	}
 }
 
@@ -105,3 +107,17 @@ func hubDockerMachineStatus(in *infrav1.DockerMachineStatus, c randfill.Continue
 		}
 	}
 }
+
+func spokeDockerMachineSpec(in *DockerMachineSpec, c randfill.Continue) {
+	c.FillNoCustom(in)
+
+	if in.ProviderID != nil && *in.ProviderID == "" {
+		in.ProviderID = nil
+	}
+}
+
+func DockerMachineTemplateFuzzFunc(_ runtimeserializer.CodecFactory) []any {
+	return []any{
+		spokeDockerMachineSpec,
+	}
+}

test/infrastructure/docker/api/v1alpha4/conversion.go

@@ -136,6 +136,10 @@ func (dst *DockerMachine) ConvertFrom(srcRaw conversion.Hub) error {
 		return err
 	}
 
+	if dst.Spec.ProviderID != nil && *dst.Spec.ProviderID == "" {
+		dst.Spec.ProviderID = nil
+	}
+
 	if err := utilconversion.MarshalData(src, dst); err != nil {
 		return err
 	}
@@ -169,6 +173,10 @@ func (dst *DockerMachineTemplate) ConvertFrom(srcRaw conversion.Hub) error {
 		return err
 	}
 
+	if dst.Spec.Template.Spec.ProviderID != nil && *dst.Spec.Template.Spec.ProviderID == "" {
+		dst.Spec.Template.Spec.ProviderID = nil
+	}
+
 	// Preserve Hub data on down-conversion except for metadata
 	if err := utilconversion.MarshalData(src, dst); err != nil {
 		return err

test/infrastructure/docker/api/v1alpha4/conversion_test.go

@@ -54,8 +54,9 @@ func TestFuzzyConversion(t *testing.T) {
 	}))
 
 	t.Run("for DockerMachineTemplate", utilconversion.FuzzTestFunc(utilconversion.FuzzTestFuncInput{
-		Hub:   &infrav1.DockerMachineTemplate{},
-		Spoke: &DockerMachineTemplate{},
+		Hub:         &infrav1.DockerMachineTemplate{},
+		Spoke:       &DockerMachineTemplate{},
+		FuzzerFuncs: []fuzzer.FuzzerFuncs{DockerMachineTemplateFuzzFunc},
 	}))
 }
 
@@ -99,6 +100,7 @@ func DockerClusterTemplateFuzzFunc(_ runtimeserializer.CodecFactory) []any {
 func DockerMachineFuzzFunc(_ runtimeserializer.CodecFactory) []any {
 	return []any{
 		hubDockerMachineStatus,
+		spokeDockerMachineSpec,
 	}
 }
 
@@ -117,3 +119,17 @@ func hubDockerMachineStatus(in *infrav1.DockerMachineStatus, c randfill.Continue
 		}
 	}
 }
+
+func spokeDockerMachineSpec(in *DockerMachineSpec, c randfill.Continue) {
+	c.FillNoCustom(in)
+
+	if in.ProviderID != nil && *in.ProviderID == "" {
+		in.ProviderID = nil
+	}
+}
+
+func DockerMachineTemplateFuzzFunc(_ runtimeserializer.CodecFactory) []any {
+	return []any{
+		spokeDockerMachineSpec,
+	}
+}