Update contract and migration doc

sbueringer · sbueringer · commit 03e02f3ee157 · 2025-07-17T15:06:33.000+02:00
diff --git a/docs/book/src/developer/providers/contracts/control-plane.md b/docs/book/src/developer/providers/contracts/control-plane.md
@@ -428,25 +428,41 @@ the ControlPlane `spec`.
 type FooControlPlaneSpec struct {
     // machineTemplate contains information about how machines
     // should be shaped when creating or updating a control plane.
+    // +required
     MachineTemplate FooControlPlaneMachineTemplate `json:"machineTemplate"`
     
     // 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.
 }
 
 type FooControlPlaneMachineTemplate struct {
-    // Standard object's metadata.
+    // metadata is the standard object's metadata.
     // More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata
     // +optional
     ObjectMeta clusterv1.ObjectMeta `json:"metadata,omitempty,omitzero"`
-    
-    // infrastructureRef is a required reference to a custom infra machine template resource
-    // offered by an infrastructure provider.
-    // +required
-    InfrastructureRef clusterv1.ContractVersionedObjectReference `json:"infrastructureRef"`
-    
+
+    // spec defines the spec for Machines of the control plane.
+    // +optional
+    Spec FooControlPlaneMachineTemplateSpec `json:"spec,omitempty,omitzero"`
+}
+
+type FooControlPlaneMachineTemplateSpec struct {
+	// infrastructureRef is a required reference to a custom infra machine template resource
+	// offered by an infrastructure provider.
+	// +required
+	InfrastructureRef clusterv1.ContractVersionedObjectReference `json:"infrastructureRef"`
+
+	// deletion contains configuration options for Machine deletion.
+	// +optional
+	Deletion FooControlPlaneMachineTemplateDeletionSpec `json:"deletion,omitempty,omitzero"`
+}
+
+// FooControlPlaneMachineTemplateDeletionSpec contains configuration options for Machine deletion.
+// +kubebuilder:validation:MinProperties=1
+type FooControlPlaneMachineTemplateDeletionSpec struct {
     // nodeDrainTimeoutSeconds is the total amount of time that the controller will spend on draining a controlplane node
     // The default value is 0, meaning that the node can be drained without any time limitations.
+	// NOTE: nodeDrainTimeoutSeconds is different from `kubectl drain --timeout`
     // +optional
     // +kubebuilder:validation:Minimum=0
     NodeDrainTimeoutSeconds *int32 `json:"nodeDrainTimeoutSeconds,omitempty"`
@@ -482,14 +498,16 @@ preserves compatibility with the deprecated v1beta1 contract; compatibility will
 For reference. The v1beta1 contract had `nodeDrainTimeout`, `nodeVolumeDetachTimeout`, `nodeDeletionTimeout` fields
 of type `*metav1.Duration` instead of the new fields with `Seconds` suffix of type `*int32`.
 `infrastructureRef` was of type `corev1.ObjectReference`, the new field has the type  `clusterv1.ContractVersionedObjectReference`.
+In v1beta2 we also moved `infrastructureRef` into the newly introduced `spec.machineTemplate.spec` field and `nodeDrainTimeoutSeconds`,
+`nodeVolumeDetachTimeoutSeconds` and `nodeDeletionTimeoutSeconds` into the newly introduced `spec.machineTemplate.spec.deletion` field.
 
 </aside>
 
 In case you are developing a control plane provider that allows definition of machine readiness gates, you SHOULD also implement
-the following `machineTemplate` field.
+the following `spec.machineTemplate.spec` field.
 
 ```go
-type FooControlPlaneMachineTemplate struct {
+type FooControlPlaneMachineTemplateSpec struct {
     // readinessGates specifies additional conditions to include when evaluating Machine Ready condition.
     //
     // This field can be used e.g. by Cluster API control plane providers to extend the semantic of the
@@ -516,6 +534,8 @@ type FooControlPlaneMachineTemplate struct {
 }
 ```
 
+NOTE: In the v1beta1 contract the `readinessGates` field was located directly in the `spec.machineTemplate` field.
+
 In case you are developing a control plane provider where control plane instances uses a Cluster API Machine 
 object to represent each control plane instance, but those instances do not show up as a Kubernetes node (for example, 
 managed control plane providers for AKS, EKS, GKE etc), you SHOULD also implement the following `status` field.
diff --git a/docs/book/src/developer/providers/migrations/v1.10-to-v1.11.md b/docs/book/src/developer/providers/migrations/v1.10-to-v1.11.md
@@ -120,10 +120,10 @@ proposal because most of the changes described below are a consequence of the wo
   - `spec.topology.controlPlane.machineHealthCheck`
   - `spec.topology.workers.machineDeployments[].machineHealthCheck`
 - All fields of type Duration in `spec.topology.{controlPlane,workers.machineDeployments[],workers.machinePools[]` have 
-  been renamed by adding the `Seconds` suffix and their type was changed to int32, thus aligning to K8s guidelines.
-  - `nodeDrainTimeout` => `nodeDrainTimeoutSeconds`
-  - `nodeVolumeDetachTimeout` => `nodeVolumeDetachTimeoutSeconds`
-  - `nodeDeletionTimeout` => `nodeDeletionTimeoutSeconds`
+  been renamed by adding the `Seconds` suffix, moved into the `deletion` section and their type was changed to int32, thus aligning to K8s guidelines.
+  - `nodeDrainTimeout` => `deletion.nodeDrainTimeoutSeconds`
+  - `nodeVolumeDetachTimeout` => `deletion.nodeVolumeDetachTimeoutSeconds`
+  - `nodeDeletionTimeout` => `deletion.nodeDeletionTimeoutSeconds`
 - All fields of type Duration in `spec.topology.{controlPlane.machineHealthCheck,workers.machineDeployments[].machineHealthCheck` have
   been renamed by adding the `Seconds` suffix and their type was changed to int32, thus aligning to K8s guidelines.
   - `nodeStartupTimeout` => `nodeStartupTimeoutSeconds`
@@ -155,10 +155,10 @@ proposal because most of the changes described below are a consequence of the wo
   - `apiVersion` has been replaced with `apiGroup`. As before, the version will be read from the corresponding CRD.
 - The `spec.progressDeadlineSeconds` field (deprecated since CAPI v1.9) has been removed
 - All fields of type Duration in `spec.template.spec` have
-  been renamed by adding the `Seconds` suffix and their type was changed to int32, thus aligning to K8s guidelines.
-  - `nodeDrainTimeout` => `nodeDrainTimeoutSeconds`
-  - `nodeVolumeDetachTimeout` => `nodeVolumeDetachTimeoutSeconds`
-  - `nodeDeletionTimeout` => `nodeDeletionTimeoutSeconds`
+  been renamed by adding the `Seconds` suffix, moved into the `deletion` section and their type was changed to int32, thus aligning to K8s guidelines.
+  - `nodeDrainTimeout` => `deletion.nodeDrainTimeoutSeconds`
+  - `nodeVolumeDetachTimeout` => `deletion.nodeVolumeDetachTimeoutSeconds`
+  - `nodeDeletionTimeout` => `deletion.nodeDeletionTimeoutSeconds`
 - Replica counters are now consistent with replica counters from other resources
   - `status.replicas` was made a pointer and omitempty was added
   - `status.readyReplicas` has now a new semantic based on machine's `Ready` condition
@@ -180,10 +180,10 @@ proposal because most of the changes described below are a consequence of the wo
   - The following fields have been removed: `namespace`, `uid`, `resourceVersion`, `fieldPath`
   - `apiVersion` has been replaced with `apiGroup`. As before, the version will be read from the corresponding CRD.
 - All fields of type Duration in `spec.template.spec` have
-  been renamed by adding the `Seconds` suffix and their type was changed to int32, thus aligning to K8s guidelines.
-  - `nodeDrainTimeout` => `nodeDrainTimeoutSeconds`
-  - `nodeVolumeDetachTimeout` => `nodeVolumeDetachTimeoutSeconds`
-  - `nodeDeletionTimeout` => `nodeDeletionTimeoutSeconds`
+  been renamed by adding the `Seconds` suffix, moved into the `deletion` section and their type was changed to int32, thus aligning to K8s guidelines.
+  - `nodeDrainTimeout` => `deletion.nodeDrainTimeoutSeconds`
+  - `nodeVolumeDetachTimeout` => `deletion.nodeVolumeDetachTimeoutSeconds`
+  - `nodeDeletionTimeout` => `deletion.nodeDeletionTimeoutSeconds`
 - Replica counters fields are now consistent with replica counters from other resources
   - `status.replicas` was made a pointer and omitempty was added
   - `status.readyReplicas` has now a new semantic based on machine's `Ready` condition
@@ -201,10 +201,10 @@ proposal because most of the changes described below are a consequence of the wo
   - The following fields have been removed: `namespace`, `uid`, `resourceVersion`, `fieldPath`
   - `apiVersion` has been replaced with `apiGroup`. As before, the version will be read from the corresponding CRD.
 - All fields of type Duration in `spec.template.spec` have
-  been renamed by adding the `Seconds` suffix and their type was changed to int32, thus aligning to K8s guidelines.
-  - `nodeDrainTimeout` => `nodeDrainTimeoutSeconds`
-  - `nodeVolumeDetachTimeout` => `nodeVolumeDetachTimeoutSeconds`
-  - `nodeDeletionTimeout` => `nodeDeletionTimeoutSeconds`
+  been renamed by adding the `Seconds` suffix, moved into the `deletion` section and their type was changed to int32, thus aligning to K8s guidelines.
+  - `nodeDrainTimeout` => `deletion.nodeDrainTimeoutSeconds`
+  - `nodeVolumeDetachTimeout` => `deletion.nodeVolumeDetachTimeoutSeconds`
+  - `nodeDeletionTimeout` => `deletion.nodeDeletionTimeoutSeconds`
 - `status.replicas` was made a pointer and omitempty was added
 - Support for terminal errors has been dropped.
   - `status.failureReason` and `status.failureMessage` will continue to exist temporarily under `status.deprecated.v1beta1`.
@@ -218,10 +218,10 @@ proposal because most of the changes described below are a consequence of the wo
   - The following fields have been removed: `namespace`, `uid`, `resourceVersion`, `fieldPath`
   - `apiVersion` has been replaced with `apiGroup`. As before, the version will be read from the corresponding CRD.
 - All fields of type Duration in `spec` have
-  been renamed by adding the `Seconds` suffix and their type was changed to int32, thus aligning to K8s guidelines.
-  - `nodeDrainTimeout` => `nodeDrainTimeoutSeconds`
-  - `nodeVolumeDetachTimeout` => `nodeVolumeDetachTimeoutSeconds`
-  - `nodeDeletionTimeout` => `nodeDeletionTimeoutSeconds`
+  been renamed by adding the `Seconds` suffix, moved into the `deletion` section and their type was changed to int32, thus aligning to K8s guidelines.
+  - `nodeDrainTimeout` => `deletion.nodeDrainTimeoutSeconds`
+  - `nodeVolumeDetachTimeout` => `deletion.nodeVolumeDetachTimeoutSeconds`
+  - `nodeDeletionTimeout` => `deletion.nodeDeletionTimeoutSeconds`
 - Information about the initial provisioning process is now surfacing under the new `status.initialization` field.
   - `status.infrastructureReady` has been replaced by `status.initialization.infrastructureProvisioned`
   - `status.bootstrapReady` has been replaced by `status.initialization.bootstrapDataSecretCreated`
@@ -243,6 +243,7 @@ proposal because most of the changes described below are a consequence of the wo
 - The `spec.unhealthyConditions` field has been renamed to `spec.unhealthyNodeConditions`
 - The `spec.remediationTemplate` field has been migrated from type `corev1.ObjectReference` to `MachineHealthCheckRemediationTemplateReference`:
   - The following fields have been removed from `remediationTemplate`: `namespace`, `uid`, `resourceVersion`, `fieldPath`
+
 ### ClusterClass
 
 - See changes that apply to [all CRDs](#all-crds)
@@ -256,10 +257,10 @@ proposal because most of the changes described below are a consequence of the wo
   - These fields are deprecated and will be removed when support for v1beta1 will be dropped.
   - Please use `XMetadata` in `JSONSchemaProps` instead.
 - All fields of type Duration in `spec.{controlPlane,workers.machineDeployments[],workers.machinePools[]` have
-  been renamed by adding the `Seconds` suffix and their type was changed to int32, thus aligning to K8s guidelines.
-  - `nodeDrainTimeout` => `nodeDrainTimeoutSeconds`
-  - `nodeVolumeDetachTimeout` => `nodeVolumeDetachTimeoutSeconds`
-  - `nodeDeletionTimeout` => `nodeDeletionTimeoutSeconds`
+  been renamed by adding the `Seconds` suffix, moved into the `deletion` section and their type was changed to int32, thus aligning to K8s guidelines.
+  - `nodeDrainTimeout` => `deletion.nodeDrainTimeoutSeconds`
+  - `nodeVolumeDetachTimeout` => `deletion.nodeVolumeDetachTimeoutSeconds`
+  - `nodeDeletionTimeout` => `deletion.nodeDeletionTimeoutSeconds`
 - All fields of type Duration in `spec.controlPlane.machineHealthCheck` and `spec.workers.machineDeployments[].machineHealthCheck` have
   been renamed by adding the `Seconds` suffix and their type was changed to int32, thus aligning to K8s guidelines.
   - `nodeStartupTimeout` => `nodeStartupTimeoutSeconds`
@@ -336,10 +337,11 @@ KubeadmConfigTemplate `spec.template.spec` has been aligned to changes in the [K
 
 - KubeadmControlPlane (and the entire KCP provider) now implements the v1beta2 Cluster API contract.
 - See changes that apply to [all CRDs](#all-crds)
-- The `spec.machineTemplate.infrastructureRef` field is now using `ContractVersionedObjectReference` type instead
+- The `spec.machineTemplate.infrastructureRef` field was moved to `spec.machineTemplate.spec.infrastructureRef` and is now using `ContractVersionedObjectReference` type instead
   of `corev1.ObjectReference`.
   - The following fields have been removed: `namespace`, `uid`, `resourceVersion`, `fieldPath`
   - `apiVersion` has been replaced with `apiGroup`. As before, the version will be read from the corresponding CRD.
+- The `spec.machineTemplate.readinessGates` field was moved to `spec.machineTemplate.spec.readinessGates`.
 - ExtraArg field types have been changed from `map[string]sting` to `[]Arg`, thus aligning with kubeadm v1beta4 API;
   however, using multiple args with the same name will be enabled only when v1beta1 is removed, tentatively in August 2026
   - `spec.kubeadmConfigSpec.clusterConfiguration.apiServer.extraArgs` type has been changed to `[]Arg`
@@ -381,10 +383,10 @@ KubeadmConfigTemplate `spec.template.spec` has been aligned to changes in the [K
   been renamed by adding the `Seconds` suffix and their type was changed to int32, thus aligning to K8s guidelines.
   - `.ttl` => `.ttlSeconds`
 - All fields of type Duration in `spec.machineTemplate` have
-  been renamed by adding the `Seconds` suffix and their type was changed to int32, thus aligning to K8s guidelines.
-  - `nodeDrainTimeout` => `nodeDrainTimeoutSeconds`
-  - `nodeVolumeDetachTimeout` => `nodeVolumeDetachTimeoutSeconds`
-  - `nodeDeletionTimeout` => `nodeDeletionTimeoutSeconds`
+  been renamed by adding the `Seconds` suffix, moved into the `deletion` section and their type was changed to int32, thus aligning to K8s guidelines.
+  - `nodeDrainTimeout` => `deletion.nodeDrainTimeoutSeconds`
+  - `nodeVolumeDetachTimeout` => `deletion.nodeVolumeDetachTimeoutSeconds`
+  - `nodeDeletionTimeout` => `deletion.nodeDeletionTimeoutSeconds`
 - All fields of type Duration in `spec.remediationStrategy` have
   been renamed by adding the `Seconds` suffix and their type was changed to int32, thus aligning to K8s guidelines.
   - `retryPeriod` => `retryPeriodSeconds`
@@ -497,6 +499,7 @@ for providers still implementing the v1beta1 contract.
   - Type of the `status.version` field was changed from `*string` to `string`.
 - [ControlPlane: machines](../contracts/control-plane.md#controlplane-machines)
   - Type of the `status.externalManagedControlPlane` field was changed from `bool` to `*bool`.
+  - Fields in `spec.machineTemplate` were restructured.
 - [ControlPlane: conditions](../contracts/control-plane.md#controlplane-conditions)
   - The fact that Providers are not required to implement conditions remains valid
   - In case a provider implements conditions, Cluster API doesn't require anymore usage of a specific condition type,
