📖 Refactor ControlPlane contract

controlplane/kubeadm/api/v1beta1/kubeadm_control_plane_types.go

@@ -271,8 +271,11 @@ type KubeadmControlPlaneStatus struct {
 	// +optional
 	UnavailableReplicas int32 `json:"unavailableReplicas"`
 
-	// Initialized denotes whether or not the control plane has the
-	// uploaded kubeadm-config configmap.
+	// Initialized denotes that the KubeadmControlPlane API Server is initialized and thus
+	// it can accept requests.
+	// NOTE: this field is part of the Cluster API contract and it is used to orchestrate provisioning.
+	// The value of this field is never updated after provisioning is completed. Please use conditions
+	// to check the operational state of the control plane.
 	// +optional
 	Initialized bool `json:"initialized"`
 

docs/book/src/SUMMARY.md

@@ -78,7 +78,6 @@
           - [Machine](./developer/core/controllers/machine.md)
           - [MachinePool](./developer/core/controllers/machine-pool.md)
           - [MachineHealthCheck](./developer/core/controllers/machine-health-check.md)
-          - [Control Plane](./developer/core/controllers/control-plane.md)
         - [Logging](developer/core/logging.md)
         - [Testing](developer/core/testing.md)
         - [Developing E2E tests](developer/core/e2e.md)

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

@@ -18,8 +18,12 @@ Among those rules:
 Similarly, in order to support different solutions for control plane management, The Cluster resource references
 an ControlPlane object, e.g. KubeadmControlPlane, EKSControlPlane etc.
 
-The [ControlPlane resource contract](../../providers/contracts/control-plane.md) defines a set of rules a provider is expected to comply with in order to allow
-the expected interactions with the Cluster controller.
+Among those rules:
+- ControlPlane SHOULD report a [controlplane endpoint](../../providers/contracts/control-plane.md#controlplane-endpoint) for the Cluster
+- ControlPlane MUST report when Cluster's control plane is [fully provisioned](../../providers/contracts/control-plane.md#controlplane-initialization-completed)
+- ControlPlane MUST manage a [KubeConfig secret](../../providers/contracts/control-plane.md#cluster-kubeconfig-management)
+- ControlPlane SHOULD report [conditions](../../providers/contracts/control-plane.md#controlplane-conditions)
+- ControlPlane SHOULD report [terminal failures](../../providers/contracts/control-plane.md#controlplane-terminal-failures)
 
 Considering all the info above, the Cluster controller's main responsibilities are:
 

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

@@ -221,7 +221,10 @@ Each BootstrapConfig MUST report when the bootstrap data secret is fully provisi
 
 ```go
 type FooConfigStatus struct {
-    // Ready denotes that the foo bootstrap data secret is fully provisioned.
+    // ready denotes that the foo bootstrap data secret is fully provisioned.
+	// NOTE: this field is part of the Cluster API contract and it is used to orchestrate provisioning.
+	// The value of this field is never updated after provisioning is completed. Please use conditions
+	// to check the operational state of the bootstrap config.
     // +optional
     Ready bool `json:"ready"`
 
@@ -284,28 +287,22 @@ the implication of this choice which are described both in the document above an
 
 </aside>
 
-### BootstrapConfig: pausing
-
-Providers SHOULD implement the pause behaviour for every object with a reconciliation loop. This is done by checking if `spec.paused` is set on the Cluster object and by checking for the `cluster.x-k8s.io/paused` annotation on the BootstrapConfig object.
-
-If implementing the pause behavior, providers SHOULD surface the paused status of an object using the Paused condition: `Status.Conditions[Paused]`.
-
 ### BootstrapConfig: terminal failures
 
 Each BootstrapConfig SHOULD report when BootstrapConfig's enter in a state that cannot be recovered (terminal failure) by
 setting `status.failureReason` and `status.failureMessage` in the BootstrapConfig resource.
 
 ```go
 type FooConfigStatus struct {
-    // FailureReason will be set in the event that there is a terminal problem reconciling the FooConfig 
+    // failureReason will be set in the event that there is a terminal problem reconciling the FooConfig 
     // and will contain a succinct value suitable for machine interpretation.
     //
     // This field should not be set for transitive errors that can be fixed automatically or with manual intervention,
     // but instead indicate that something is fundamentally wrong with the FooConfig and that it cannot be recovered.
     // +optional
     FailureReason *capierrors.ClusterStatusError `json:"failureReason,omitempty"`
 
-    // FailureMessage will be set in the event that there is a terminal problem reconciling the FooConfig
+    // failureMessage will be set in the event that there is a terminal problem reconciling the FooConfig
     // and will contain a more verbose string suitable for logging and human consumption.
     //
     // This field should not be set for transitive errors that can be fixed automatically or with manual intervention,
@@ -432,6 +429,12 @@ Please, read carefully the page linked above to fully understand implications an
 
 The clusterctl command is designed to work with all the providers compliant with the rules defined in the [clusterctl provider contract].
 
+### BootstrapConfig: pausing
+
+Providers SHOULD implement the pause behaviour for every object with a reconciliation loop. This is done by checking if `spec.paused` is set on the Cluster object and by checking for the `cluster.x-k8s.io/paused` annotation on the BootstrapConfig object.
+
+If implementing the pause behavior, providers SHOULD surface the paused status of an object using the Paused condition: `Status.Conditions[Paused]`.
+
 ## Typical BootstrapConfig reconciliation workflow
 
 A bootstrap provider must respond to changes to its BootstrapConfig resources. This process is