⚠️ Stop using FailureReason and FailureMessage in controllers

api/v1beta2/cluster_phase_types.go

@@ -49,6 +49,11 @@ const (
 
 	// ClusterPhaseFailed is the Cluster state when the system
 	// might require user intervention.
+	//
+	// Deprecated: This enum value is deprecated; the Failed phase won't be set anymore by controllers, and it is preserved only
+	// for conversion from v1beta1 objects; the Failed phase is going to be removed when support for v1beta1 will be dropped.
+	// Please see https://github.com/kubernetes-sigs/cluster-api/blob/main/docs/proposals/20240916-improve-status-in-CAPI-resources.md for more details.
+	//
 	ClusterPhaseFailed = ClusterPhase("Failed")
 
 	// ClusterPhaseUnknown is returned if the Cluster state cannot be determined.

api/v1beta2/machine_phase_types.go

@@ -57,6 +57,11 @@ const (
 
 	// MachinePhaseFailed is the Machine state when the system
 	// might require user intervention.
+	//
+	// Deprecated: This enum value is deprecated; the Failed phase won't be set anymore by controllers, and it is preserved only
+	// for conversion from v1beta1 objects; the Failed phase is going to be removed when support for v1beta1 will be dropped.
+	// Please see https://github.com/kubernetes-sigs/cluster-api/blob/main/docs/proposals/20240916-improve-status-in-CAPI-resources.md for more details.
+	//
 	MachinePhaseFailed = MachinePhase("Failed")
 
 	// MachinePhaseUnknown is returned if the Machine state cannot be determined.

api/v1beta2/machinedeployment_types.go

@@ -567,6 +567,11 @@ const (
 	MachineDeploymentPhaseRunning = MachineDeploymentPhase("Running")
 
 	// MachineDeploymentPhaseFailed indicates there was a problem scaling and user intervention might be required.
+	//
+	// Deprecated: This enum value is deprecated; the Failed phase won't be set anymore by controllers, and it is preserved only
+	// for conversion from v1beta1 objects; the Failed phase is going to be removed when support for v1beta1 will be dropped.
+	// Please see https://github.com/kubernetes-sigs/cluster-api/blob/main/docs/proposals/20240916-improve-status-in-CAPI-resources.md for more details.
+	//
 	MachineDeploymentPhaseFailed = MachineDeploymentPhase("Failed")
 
 	// MachineDeploymentPhaseUnknown indicates the state of the MachineDeployment cannot be determined.

docs/book/src/developer/core/controllers/machine.md

@@ -44,14 +44,13 @@ Considering all the info above, the Machine controller's main responsibilities a
 ![](../../../images/cluster-admission-machine-controller.png)
 
 After the machine controller sets the OwnerReferences on the associated objects, it waits for the bootstrap
-and infrastructure objects referenced by the machine to have the `Status.Ready` field set to `true`. When
-the infrastructure object is ready, the machine controller will attempt to read its `Spec.ProviderID` and
+and infrastructure objects referenced by the machine to have the `Status.initialization.dataSecretCreated` field set to `true`. When
+the infrastructure object reports `Status.initialization.provisioned`, the machine controller will attempt to read its `Spec.ProviderID` and
 copy it into `Machine.Spec.ProviderID`.
 
 The machine controller uses the kubeconfig for the new workload cluster to watch new nodes coming up.
 When a node appears with `Node.Spec.ProviderID` matching `Machine.Spec.ProviderID`, the machine controller
-transitions the associated machine into the `Provisioned` state. When the infrastructure ref is also
-`Ready`, the machine controller marks the machine as `Running`.
+transitions the associated machine into the `Running` state.
 
 The following schema goes through machine phases and interactions with InfraMachine and BootstrapConfig
 happening at each step.

docs/book/src/developer/providers/contracts/bootstrap-config.md

@@ -322,7 +322,10 @@ In case a Bootstrap provider reports that a BootstrapConfig resource is in a sta
 setting `status.failureReason` and `status.failureMessage` as defined by the deprecated v1beta1 contract, 
 the "core" Machine controller will surface those info in the corresponding fields within in Machine's `status.deprecated.v1beta1` struct.
 
-However, those info won't have any impact on the Machine lifecycle as before. 
+However, those info won't have any impact on the Machine lifecycle as before (the Machine controller won't consider the
+presence of `status.failureReason` and `status.failureMessage` info as "terminal failures"; similarly, the
+MachineHealthCheck controller won't consider the presence of `status.failureReason` and `status.failureMessage` to
+determine when a Machine needs remediation).
 
 After compatibility with the deprecated v1beta1 contract will be removed, `status.failureReason` and `status.failureMessage`
 fields in the BootstrapConfig resource will be ignored and Machine's `status.deprecated.v1beta1` struct will be dropped.

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

@@ -654,7 +654,8 @@ In case a Control Plane provider reports that a ControlPlane resource is in a st
 setting `status.failureReason` and `status.failureMessage` as defined by the deprecated v1beta1 contract,
 the "core" Cluster controller will surface those info in the corresponding fields in the Cluster's `status.deprecated.v1beta1` struct.
 
-However, those info won't have any impact on the Cluster lifecycle as before.
+However, those info won't have any impact on the Cluster lifecycle as before (the Cluster controller won't consider the
+presence of `status.failureReason` and `status.failureMessage` info as "terminal failures").
 
 After compatibility with the deprecated v1beta1 contract will be removed, `status.failureReason` and `status.failureMessage`
 fields in the ControlPlane resource will be ignored and Cluster's `status.deprecated.v1beta1` struct will be dropped.

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

@@ -373,7 +373,8 @@ In case an infrastructure provider reports that a InfraCluster resource is in a
 setting `status.failureReason` and `status.failureMessage` as defined by the deprecated v1beta1 contract,
 the "core" Cluster controller will surface those info in the corresponding fields in the Cluster's `status.deprecated.v1beta1` struct.
 
-However, those info won't have any impact on the Cluster lifecycle as before.
+However, those info won't have any impact on the Cluster lifecycle as before (the Cluster controller won't consider the
+presence of `status.failureReason` and `status.failureMessage` info as "terminal failures").
 
 After compatibility with the deprecated v1beta1 contract will be removed, `status.failureReason` and `status.failureMessage`
 fields in the InfraCluster resource will be ignored and Cluster's `status.deprecated.v1beta1` struct will be dropped.

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

@@ -386,7 +386,10 @@ In case an infrastructure provider reports that a InfraMachine resource is in a
 setting `status.failureReason` and `status.failureMessage` as defined by the deprecated v1beta1 contract,
 the "core" Machine controller will surface those info in the corresponding fields in the Machine's `status.deprecated.v1beta1` struct.
 
-However, those info won't have any impact on the Machine lifecycle as before.
+However, those info won't have any impact on the Machine lifecycle as before (the Machine controller won't consider the
+presence of `status.failureReason` and `status.failureMessage` info as "terminal failures"; similarly, the
+MachineHealthCheck controller won't consider the presence of `status.failureReason` and `status.failureMessage` to
+determine when a Machine needs remediation).
 
 After compatibility with the deprecated v1beta1 contract will be removed, `status.failureReason` and `status.failureMessage`
 fields in the InfraMachine resource will be ignored and Machine's `status.deprecated.v1beta1` struct will be dropped.
@@ -504,7 +507,6 @@ is implemented in InfraMachine controllers:
 1. If the resource does not have a `Machine` owner, exit the reconciliation
     1. The Cluster API `Machine` reconciler populates this based on the value in the `Machines`'s
        `spec.infrastructureRef` field
-1. If the resource has `status.failureReason` or `status.failureMessage` set, exit the reconciliation
 1. If the `Cluster` to which this resource belongs cannot be found, exit the reconciliation
 1. Add the provider-specific finalizer, if needed
 1. If the associated `Cluster`'s `status.infrastructureReady` is `false`, exit the reconciliation

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

@@ -23,6 +23,11 @@ proposal because most of the changes described below are a consequence of the wo
   - Support for terminal errors has been dropped from all Kinds
     - `status.failureReason` and `status.failureMessage` will continue to exist temporarily under `status.deprecated.v1beta1`
       for the sake of down conversions and to provide a temporary option for users willing to continue using old conditions.
+    - The const values for `Failed` phase has been deprecated in the following enum types (controllers are not setting this value anymore):
+      - `cluster.status.phase`
+      - `machineDeployment.status.phase`
+      - `machinePool.status.phase`
+      - `machine.status.phase`
   - Informations about the initial provisioning process are now surfacing under `status.initialization` for
     both `Cluster`, `Machine` and `KubeadmControlPlane` Kinds.
   - All the resources handling machine replicas have now a consistent set of replica counters based on corresponding
@@ -45,6 +50,11 @@ proposal because most of the changes described below are a consequence of the wo
 - v1beta1 version of the Cluster API contract is now deprecated
   - In order to ease the transition to the new v1beta2 version of the Cluster API contract, v1beta2 version 
     will implement temporarily compatibility with the deprecated v1beta1 version of the Cluster API contract   
+    - Compatibility, is only intended to ease the transition for providers, and it has following limitations:
+      - The Machine controller won't consider the presence of `status.failureReason` and `status.failureMessage` info
+        as "terminal failures"
+      - MachineHealthCheck controller won't consider the presence of `status.failureReason` and `status.failureMessage` to
+        determine when a Machine needs remediation.
   - Compatibility support for the v1beta1 version of the Cluster API contract will be removed tentatively in August 2026 
   - After compatibility support for the v1beta1 version of the Cluster API contract is removed, providers 
     which are implementing the v1beta1 contract will stop to work (they will work only with older versions of Cluster API).
@@ -54,8 +64,11 @@ proposal because most of the changes described below are a consequence of the wo
     - 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,
       even if transition to `metav1.Conditions` is highly recommended.
-  - Support for terminal errors has been dropped.
-
+  - Support for terminal errors has been dropped; as a consequence if a provider resources reports `status.failureReason` 
+    and `status.failureMessage`, those info won't have any impact on the lifecycle of the corresponding resources as before.
+    - `status.failureReason` and `status.failureMessage` will temporarily keep surfacing into `status.deprecated.v1beta1` 
+      struct of the corresponding resources.
+
 See [provider contracts](../contracts/overview.md) for more details.
 
 ### Deprecation
@@ -72,11 +85,18 @@ See [provider contracts](../contracts/overview.md) for more details.
 - v1beta1 conditions utils are now deprecated, and will removed as soon as v1beta1 API will be removed
 - v1beta1 support in the patch helper is now deprecated, and will removed as soon as v1beta1 API will be removed
 
+- As a consequence of dropping support for terminal errors from all Kinds, the const values for
+  `Failed` phase has been deprecated in the following enum types (controllers are not setting this value anymore):
+  - `ClusterPhase`, used in `cluster.status.phase`
+  - `MachineDeploymentPhase`, used in `machineDeployment.status.phase`
+  - `MachinePoolPhase`, used in `machinePool.status.phase`
+  - `MachinePhase`, used in `machine.status.phase`
+
 ### Removals
 
 There are no removals in the CAPI v1.11 version.
 
-Please, also keep in mind future removals:
+As documented in [Suggested changes for providers](#suggested-changes-for-providers), please also start planning for future removals:
 
 - v1beta1 API version will be removed tentatively in August 2026
 - Starting from the CAPI release when v1beta1 removal will happen (tentative Aug 2026), the Cluster API project
@@ -110,7 +130,11 @@ Please refer to following how to guides for additional details.
 CAPI v1.11 implements the v1beta2 version of the Cluster API contract.
 
 However, in order to ease the transition for providers, the v1beta2 version of the Cluster API contract _temporarily_
-preserves compatibility with the deprecated v1beta1 contract.
+preserves compatibility with the deprecated v1beta1 contract; a few limitations apply:
+- The Machine controller won't consider the presence of `status.failureReason` and `status.failureMessage` info
+as "terminal failures"
+- MachineHealthCheck controller won't consider the presence of `status.failureReason` and `status.failureMessage` to
+determine when a Machine needs remediation.
 
 Provider's implementing the deprecated v1beta1 contract can leverage compatibility support without any change,
 but it is crucial for them to start planning for the implementation of the new v1beta2 version of

docs/book/src/images/bootstrap-provider.plantuml

@@ -8,20 +8,16 @@ if (Deleted?) then (yes)
     stop
 else (no)
     if (Has machine owner?) then (yes)
-        if (Has status.failureReason/failureMessage?) then (yes)
+        if (Cluster exists?) then (no)
             stop
-        else (no)
-            if (Cluster exists?) then (no)
-                stop
+        else (yes)
+            if (Bootstrap data secret exists?) then (no)
+                :Generate bootstrap data & create secret;
             else (yes)
-                if (Bootstrap data secret exists?) then (no)
-                    :Generate bootstrap data & create secret;
-                else (yes)
-                endif
-
-                :Set status.dataSecretName;
-                :set status.ready to true;
             endif
+
+            :Set status.dataSecretName;
+            :set status.initialization.dataSecretCreated to true;
         endif
     else (no)
     endif

docs/book/src/images/cluster-infra-provider.plantuml

@@ -28,7 +28,7 @@ else (no)
             :Set spec.controlPlaneEndpoint;
         else (no)
         endif
-        :Set status.ready to true;
+        :Set status.initialization.provisioned to true;
     else (no)
     endif
 endif

docs/book/src/images/machine-infra-provider.plantuml

@@ -20,10 +20,6 @@ if (Deleted?) then (yes)
     :Delete provider-specific finalizer;
 else (no)
     if (Has machine owner?) then (yes)
-        if (Has status.failureReason/failureMessage?) then (yes)
-            stop
-        else (no)
-        endif
 
         if (Cluster exists?) then (no)
             stop
@@ -32,7 +28,7 @@ else (no)
 
         :Add provider-specific finalizer if needed;
 
-        if (Cluster's status.infrastructureReady = true?) then (no)
+        if (Cluster's status.initialization.provisioned = true?) then (no)
             stop
         else (yes)
         endif
@@ -42,21 +38,14 @@ else (no)
         else (no)
         endif
 
-        :Reconcile provider machine infrastructure;
-        if (Error?) then (yes)
-            :Set status.failureReason/failureMessage;
-            :Patch resource to persist changes;
-            stop
+        if (Control plane machine?) then (yes)
+            :Register instance with control plane load balancer;
         else (no)
-            if (Control plane machine?) then (yes)
-                :Register instance with control plane load balancer;
-            else (no)
-            endif
         endif
 
         :Set spec.providerID;
-        :Set status.ready to true;
         :Set status.addresses;
+        :Set status.initialization.provisioned to true;
     else (no)
     endif
 endif

docs/book/src/images/machine-phases.plantuml

@@ -5,10 +5,10 @@ title Figure 1: State diagram with a generic provider
 
 note right
 - Bootstrap provider watches Machines in "pending" state,
-  generates //BootstrapConfig.Status.DataSecretName// and sets
-  //BootstrapConfig.Status.Ready// = true.
-- Machine controller sets //Machine.Spec.Bootstrap.DataSecretName//
-  from //BootstrapConfig.Status.DataSecretName//.
+  generates //BootstrapConfig.status.dataSecretName// and sets
+  //BootstrapConfig.status.initialization.dataSecretCreated// = true.
+- Machine controller sets //Machine.spec.bootstrap.dataSecretName//
+  from //BootstrapConfig.status.dataSecretName//.
 - Machine controller can now transition to the next state.
 end note
 
@@ -17,17 +17,17 @@ end note
 note right
 - Infrastructure provider watches Machines in "provisioning"
   state and starts creating infrastructure for those Machines.
-- When MachineInfrastructure is ready sets
-  //MachineInfrastructure.Status.Ready// = true.
-- Machine controller sets //Machine.Status.Addresses//
-  from //MachineInfrastructure.Status.Addresses// and other fields.
+- When MachineInfrastructure is provisioned sets
+  //MachineInfrastructure.status.initialization.provisioned// = true.
+- Machine controller sets //Machine.status.addresses//
+  from //MachineInfrastructure.status.addresses// and other fields.
 end note
 
 "Provisioning" --> "Provisioned"
 
 note right
 - Machine controller watches Machines in "provisioning" state and
-  //MachineInfrastructure.Status.Ready// = true.
+  //MachineInfrastructure.status.initialization.provisioned// = true.
 - Machine controller sets //Machine.Status.Phase// = "provisioned".
 end note
 
@@ -47,15 +47,5 @@ end note
 
 "Deleting" --> "Deleted"
 
-"Pending" --> "Failed"
-"Provisioning" --> "Failed"
-"Provisioned" --> "Failed"
-"Running" --> "Failed"
-"Deleting" --> "Failed"
-"Deleted" --> "Failed"
-
-"Failed" --> (*)
-"Deleted" --> (*)
-
 hide footbox
 @enduml

docs/book/src/reference/versions.md

@@ -175,9 +175,14 @@ and it will be considered in a very limited set of operations e.g.
   the v1beta1 contract (v1beta1 is deprecated).
 - A version of clusterctl implementing the v1beta2 contract cannot perform upgrades when the target version core provider 
   will be implementing the v1beta1 contract (v1beta1 is deprecated).
+- A core provider implementing the v1beta2 contract can work with an infrastructure provider still implementing the
+  v1beta1 contract and reporting `status.ready` on InfraCluster or InfraMachines (v1beta1 is temporarily compatible with v1beta2).
 
 Also, might be that in future compatibility will be subject to limitations (e.g. compatibility only for infrastructure 
-providers of an older contract version)
+providers of an older contract version) e.g.
+- A core provider implementing the v1beta2 contract will still read `status.failureReason` and `status.failureMessae` 
+  from an infrastructure provider still implementing the v1beta1 contract, but those info won't be considered
+  anymore by controllers as terminal failures nor trigger machine remediation (v1beta1 compatibility has some limitations).
 
 </aside>