📖 Refactor the BootstrapConfig contract

docs/book/src/SUMMARY.md

@@ -77,8 +77,7 @@
           - [MachineSet](./developer/core/controllers/machine-set.md)  
           - [Machine](./developer/core/controllers/machine.md)
           - [MachinePool](./developer/core/controllers/machine-pool.md)
-          - [MachineHealthCheck](./developer/core/controllers/machine-health-check.md)     
-          - [Bootstrap](./developer/core/controllers/bootstrap.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)

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

@@ -22,6 +22,14 @@ a BootstrapConfig object, e.g. KubeadmBoostrapConfig etc.
 The [BootstrapConfig resource contract](../../providers/contracts/bootstrap-config.md) defines a set of rules a provider is expected to comply with in order to allow
 the expected interactions with the Machine controller.
 
+Among those rules:
+- BootstrapConfig MUST create a [bootstrap data secret](../../providers/contracts/bootstrap-config.md#bootstrapconfig-data-secret) where machines should be placed in
+- BootstrapConfig MUST report when Machine's bootstrap data secret is [fully provisioned](../../providers/contracts/bootstrap-config.md#bootstrapconfig-initialization-completed)
+- BootstrapConfig SHOULD report [conditions](../../providers/contracts/bootstrap-config.md#bootstrapconfig-conditions)
+- BootstrapConfig SHOULD report [terminal failures](../../providers/contracts/bootstrap-config.md#bootstrapconfig-terminal-failures)
+- BootstrapConfig SHOULD report [taint Nodes at creation](../../providers/contracts/bootstrap-config.md#taint-nodes-at-creation)
+- BootstrapConfig SHOULD create a [sentinel file](../../providers/contracts/bootstrap-config.md#sentinel-file) on machines
+
 Considering all the info above, the Machine controller's main responsibilities are:
 
 * Setting an OwnerReference on the infrastructure object referenced in `Machine.spec.infrastructureRef`.
@@ -44,3 +52,8 @@ The machine controller uses the kubeconfig for the new workload cluster to watch
 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`.
+
+The following schema goes trough machine phases and interactions with InfraMachine and BootstrapConfig
+happening at each step.
+
+![](../../../images/machine-phases.png)

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

@@ -12,7 +12,7 @@ and the interaction between the Cluster's controller and the InfraCluster resour
 rules defined in this page.
 
 Once contract rules are satisfied by an InfraCluster implementation, other implementation details 
-could be addressed according to the specific needs (Cluster API in not prescriptive).
+could be addressed according to the specific needs (Cluster API is not prescriptive).
 
 Nevertheless, it is always recommended to take a look at Cluster API controllers,
 in-tree providers, other providers and use them as a reference implementation (unless custom solutions are required 
@@ -236,7 +236,7 @@ type APIEndpoint struct {
 ```
 
 Once `spec.controlPlaneEndpoint` is set on the InfraCluster resource and the [InfraCluster initialization completed],
-the Cluster controller will bubble up this info in Cluster's `spec.controlPlaneEndpoint`.
+the Cluster controller will surface this info in Cluster's `spec.controlPlaneEndpoint`.
 
 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.
@@ -262,7 +262,7 @@ type FooClusterStatus struct {
 - `attributes map[string]string`: arbitrary attributes for users to apply to a failure domain.
 
 Once `status.failureDomains` is set on the InfraCluster resource and the [InfraCluster initialization completed],
-the Cluster controller will bubble up this info in Cluster's `status.failureDomains`.
+the Cluster controller will surface this info in Cluster's `status.failureDomains`.
 
 ### InfraCluster: initialization completed
 
@@ -364,7 +364,7 @@ type FooClusterStatus struct {
 ```
 
 Once `status.failureReason` and `status.failureMessage` are set on the InfraCluster resource, the Cluster "core" controller
-will bubble up those info in the corresponding fields in Cluster's `status`.
+will surface those info in the corresponding fields in Cluster's `status`.
 
 Please note that once failureReason/failureMessage is set in Cluster's `status`, the only way to recover is to delete and
 recreate the Cluster (it is a terminal failure).

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

@@ -12,7 +12,7 @@ and the interaction between the Machine's controller and the InfraMachine resour
 rules defined in this page.
 
 Once contract rules are satisfied by an InfraMachine implementation, other implementation details
-could be addressed according to the specific needs (Cluster API in not prescriptive).
+could be addressed according to the specific needs (Cluster API is not prescriptive).
 
 Nevertheless, it is always recommended to take a look at Cluster API controllers,
 in-tree providers, other providers and use them as a reference implementation (unless custom solutions are required
@@ -215,7 +215,7 @@ type FooMachineSpec struct {
 ```
 
 Once `spec.providerID` is set on the InfraMachine resource and the [InfraMachine initialization completed],
-the Cluster controller will bubble up this info in Machine's `spec.providerID`.
+the Cluster controller will surface this info in Machine's `spec.providerID`.
 
 ### InfraMachine: failure domain
 
@@ -275,7 +275,7 @@ type FooMachineStatus struct {
 Each MachineAddress must have a type; accepted types are `Hostname`, `ExternalIP`, `InternalIP`, `ExternalDNS` or `InternalDNS`.
 
 Once `status.addresses` is set on the InfraMachine resource and the [InfraMachine initialization completed],
-the Machine controller will bubble up this info in Machine's `status.addresses`.
+the Machine controller will surface this info in Machine's `status.addresses`.
 
 ### InfraMachine: initialization completed
 
@@ -377,7 +377,7 @@ type FooMachineStatus struct {
 ```
 
 Once `status.failureReason` and `status.failureMessage` are set on the InfraMachine resource, the Machine "core" controller
-will bubble up those info in the corresponding fields in Machine's `status`.
+will surface those info in the corresponding fields in Machine's `status`.
 
 Please note that once failureReason/failureMessage is set in Machine's `status`, the only way to recover is to delete and
 recreate the Machine (it is a terminal failure).

docs/book/src/developer/providers/security-guidelines.md

@@ -6,6 +6,7 @@ There are several critical areas that any infrastructure provider implementer mu
 - **Ensuring secure access to VMs** for troubleshooting, with proper authentication methods.
 - **Controlling manual operations** performed on cloud infrastructure targeted by the provider.
 - **Housekeeping** of the cloud infrastructure, ensuring timely cleanup and garbage collection of unused resources.
+- **Securing Machine's bootstrap data** ensuring protection oversensitive data that might be included in it.
 
 The following list outlines high-level security recommendations. It is a community-maintained resource, and everyone’s contributions are essential to continuously improve and adapt these best practices. Each provider implementer is responsible for translating these recommendations to fit the context of their specific cloud provider:
 
@@ -23,3 +24,6 @@ The following list outlines high-level security recommendations. It is a communi
 
 5. **Resource Housekeeping**:
    Any cloud resource not linked to a cluster after a fixed configurable period, created by cloud credentials, should be automatically deleted or marked for garbage collection to avoid resource sprawl.
+
+6. **Securing Machine's bootstrap data**:
+   Bootstrap data are usually stored in machine's metadata, and they might contain sensitive data, like e.g. Cluster secrets, user credentials, ssh certificates etc. It is important to ensure protections of those metadata, or if not possible, to clean up them immediately after machine bootstrap.