From de9897bd37c9b64b584fc2233a69f0e7572384a6 Mon Sep 17 00:00:00 2001
From: fabriziopandini <fpandini@vmware.com>
Date: Wed, 25 Sep 2024 12:48:36 +0200
Subject: [PATCH] Refactor InfraMachine contract

---
 .../src/developer/core/controllers/cluster.md |   4 +-
 .../src/developer/core/controllers/machine.md | 152 +----
 .../providers/contracts/infra-cluster.md      |   6 +-
 .../providers/contracts/infra-machine.md      | 633 ++++++++++++++----
 .../providers/getting-started/webhooks.md     |  24 +-
 5 files changed, 525 insertions(+), 294 deletions(-)

diff --git a/docs/book/src/developer/core/controllers/cluster.md b/docs/book/src/developer/core/controllers/cluster.md
index 33e5ad388ce9..ac648fd2f10e 100644
--- a/docs/book/src/developer/core/controllers/cluster.md
+++ b/docs/book/src/developer/core/controllers/cluster.md
@@ -5,7 +5,7 @@ The Cluster controller is responsible for reconciling the Cluster resource.
 In order to allow Cluster provisioning on different type of infrastructure, The Cluster resource references
 an InfraCluster object, e.g. AWSCluster, GCPCluster etc.
 
-The [InfraCluster resource contract](../../providers/contracts/infra-cluster.md) defines a set of rules a provider is expected to comply in order to allow
+The [InfraCluster resource contract](../../providers/contracts/infra-cluster.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:
@@ -18,7 +18,7 @@ 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 in order to allow
+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.
 
 Considering all the info above, the Cluster controller's main responsibilities are:
diff --git a/docs/book/src/developer/core/controllers/machine.md b/docs/book/src/developer/core/controllers/machine.md
index bd318a381593..861abdfca2a5 100644
--- a/docs/book/src/developer/core/controllers/machine.md
+++ b/docs/book/src/developer/core/controllers/machine.md
@@ -1,20 +1,39 @@
-# Machine  Controller
+# Machine Controller
 
-![](../../../images/cluster-admission-machine-controller.png)
+The Machine controller is responsible for reconciling the Machine resource.
+
+In order to allow Machine provisioning on different type of infrastructure, The Machine resource references
+an InfraMachine object, e.g. AWSMachine, GCMachine etc.
+
+The [InfraMachine resource contract](../../providers/contracts/infra-machine.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:
+- InfraMachine MUST report a [provider ID](../../providers/contracts/infra-machine.md#inframachine-provider-id) for the Machine
+- InfraMachine SHOULD take into account the [failure domain](../../providers/contracts/infra-machine.md#inframachine-failure-domain) where machines should be placed in
+- InfraMachine SHOULD surface machine's [addresses](../../providers/contracts/infra-machine.md#inframachine-addresses) to help operators when troubleshooting issues
+- InfraMachine MUST report when Machine's infrastructure is [fully provisioned](../../providers/contracts/infra-machine.md#inframachine-initialization-completed)
+- InfraMachine SHOULD report [conditions](../../providers/contracts/infra-machine.md#inframachine-conditions)
+- InfraMachine SHOULD report [terminal failures](../../providers/contracts/infra-machine.md#inframachine-terminal-failures)
+
+Similarly, in order to support different machine bootstrappers, The Machine resource references
+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.
 
-The Machine controller's main responsibilities are:
+Considering all the info above, the Machine controller's main responsibilities are:
 
-* Setting an OwnerReference on:
-    * Each Machine object to the Cluster object.
-    * The associated BootstrapConfig object.
-    * The associated InfrastructureMachine object.
-* Copy data from `BootstrapConfig.Status.DataSecretName` to `Machine.Spec.Bootstrap.DataSecretName` if
-`Machine.Spec.Bootstrap.DataSecretName` is empty.
-* Setting NodeRefs to be able to associate machines and Kubernetes nodes.
-* Deleting Nodes in the target cluster when the associated machine is deleted.
-* Cleanup of related objects.
-* Keeping the Machine's Status object up to date with the InfrastructureMachine's Status object.
-* Finding Kubernetes nodes matching the expected providerID in the workload cluster.
+* Setting an OwnerReference on the infrastructure object referenced in `Machine.spec.infrastructureRef`.
+* Setting an OwnerReference on the bootstrap object referenced in `Machine.spec.bootstrap.configRef`.
+* Keeping the Machine's status in sync with the InfraMachine and BootstrapConfig's status.
+  * Finding Kubernetes nodes matching the expected providerID in the workload cluster.
+  * Setting NodeRefs to be able to associate machines and Kubernetes nodes.
+  * Monitor Kubernetes nodes and propagate labels to them.
+* Cleanup of all owned objects so that nothing is dangling after deletion.
+  * Drain nodes and wait for volumes being detached by CSI plugins.
+
+![](../../../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
@@ -25,108 +44,3 @@ 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`.
-
-## Contracts
-
-### Cluster API
-
-Cluster associations are made via labels.
-
-#### Expected labels
-
-| what | label | value | meaning |
-| --- | --- | --- | --- |
-| Machine | `cluster.x-k8s.io/cluster-name` | `<cluster-name>` | Identify a machine as belonging to a cluster with the name `<cluster-name>`|
-| Machine | `cluster.x-k8s.io/control-plane` | `true` | Identifies a machine as a control-plane node |
-
-### Bootstrap provider
-
-The BootstrapConfig object **must** have a `status` object.
-
-To override the bootstrap provider, a user (or external system) can directly set the `Machine.Spec.Bootstrap.Data`
-field. This will mark the machine as ready for bootstrapping and no bootstrap data will be copied from the
-BootstrapConfig object.
-
-#### Required `status` fields
-
-The `status` object **must** have several fields defined:
-
-* `ready` - a boolean field indicating the bootstrap config data is generated and ready for use.
-* `dataSecretName` - a string field referencing the name of the secret that stores the generated bootstrap data.
-
-#### Optional `status` fields
-
-The `status` object **may** define several fields that do not affect functionality if missing:
-
-* `failureReason` - a string field explaining why a fatal error has occurred, if possible.
-* `failureMessage` - a string field that holds the message contained by the error.
-
-Note: once any of `failureReason` or `failureMessage` surface on the machine who is referencing the bootstrap config object, 
-they cannot be restored anymore (it is considered a terminal error; the only way to recover is to delete and recreate the machine). 
-Also, if the machine is under control of a MachineHealthCheck instance, the machine will be automatically remediated.
-
-Example:
-
-```yaml
-kind: MyBootstrapProviderConfig
-apiVersion: bootstrap.cluster.x-k8s.io/v1alpha3
-status:
-    ready: true
-    dataSecretName: "MyBootstrapSecret"
-```
-
-### Infrastructure provider
-
-The InfrastructureMachine object **must** have both `spec` and `status` objects.
-
-#### Required `spec` fields
-
-The `spec` object **must** at least one field defined:
-
-* `providerID` - a cloud provider ID identifying the machine.
-
-#### Optional `spec` fields
-
-The `spec` object **may** define several fields that do not affect functionality if missing:
-
-* `failureDomain` - is a string identifying the failure domain the instance is running in.
-
-#### Required `status` fields
-
-The `status` object **must** at least one field defined:
-
-* `ready` - a boolean field indicating if the infrastructure is ready to be used or not.
-
-#### Optional `status` fields
-
-The `status` object **may** define several fields that do not affect functionality if missing:
-
-* `failureReason` - is a string that explains why a fatal error has occurred, if possible.
-* `failureMessage` - is a string that holds the message contained by the error.
-* `addresses` - is a `MachineAddresses` (a list of `MachineAddress`) which represents host names, external IP addresses, internal IP addresses,
-external DNS names, and/or internal DNS names for the provider's machine instance. `MachineAddress` is
-defined as:
-    - `type` (string): one of `Hostname`, `ExternalIP`, `InternalIP`, `ExternalDNS`, `InternalDNS`
-    - `address` (string)
-
-Note: once any of `failureReason` or `failureMessage` surface on the machine who is referencing the infrastructureMachine object, 
-they cannot be restored anymore (it is considered a terminal error; the only way to recover is to delete and recreate the machine). 
-Also, if the machine is under control of a MachineHealthCheck instance, the machine will be automatically remediated.
-
-Example:
-```yaml
-kind: MyMachine
-apiVersion: infrastructure.cluster.x-k8s.io/v1alpha3
-spec:
-    providerID: cloud:////my-cloud-provider-id
-status:
-    ready: true
-```
-
-### Secrets
-
-The Machine controller will create a secret or use an existing secret in the following format:
-
-| secret name | field name | content |
-|:---:|:---:|---|
-|`<cluster-name>-kubeconfig`|`value`|base64 encoded kubeconfig that is authenticated with the child cluster|
diff --git a/docs/book/src/developer/providers/contracts/infra-cluster.md b/docs/book/src/developer/providers/contracts/infra-cluster.md
index 0908e1e33e87..51242cd5d88f 100644
--- a/docs/book/src/developer/providers/contracts/infra-cluster.md
+++ b/docs/book/src/developer/providers/contracts/infra-cluster.md
@@ -119,7 +119,7 @@ rules:
     - watch
 ```
 
-Note: The write permissions allow the Cluster controller to set owner references and labels on the InfraCluster” resources;
+Note: The write permissions allow the Cluster controller to set owner references and labels on the InfraCluster resources;
 write permissions are not used for general mutations of InfraCluster resources, unless specifically required (e.g. when
 using ClusterClass and managed topologies).
 
@@ -271,7 +271,7 @@ Each InfraCluster MUST report when Cluster's infrastructure is fully provisioned
 
 ```go
 type FooClusterStatus struct {
-    // Ready denotes that the foo cluster infrastructure fully provisioned.
+    // Ready denotes that the foo cluster infrastructure is fully provisioned.
     // +optional
     Ready bool `json:"ready"`
     
@@ -282,7 +282,7 @@ type FooClusterStatus struct {
 
 Once `status.ready` the Cluster "core" controller will bubbles up this info in Cluster's `status.infrastructureReady`;
 If defined, also InfraCluster's `spec.controlPlaneEndpoint` and `status.failureDomains` will be surfaced on Cluster's
-corresponding field at the same time.
+corresponding fields at the same time.
 
 <aside class="note warning">
 
diff --git a/docs/book/src/developer/providers/contracts/infra-machine.md b/docs/book/src/developer/providers/contracts/infra-machine.md
index 3ec498714872..a33a597b6d09 100644
--- a/docs/book/src/developer/providers/contracts/infra-machine.md
+++ b/docs/book/src/developer/providers/contracts/infra-machine.md
@@ -1,118 +1,495 @@
-# Machine Infrastructure Provider Specification
+# Contract rules for InfraMachine
 
-## Overview
+Infrastructure providers SHOULD implement an InfraMachine resource.
 
-A machine infrastructure provider is responsible for managing the lifecycle of provider-specific machine instances.
+The goal of an InfraMachine resource is to manage the lifecycle of a provider-specific machine instances.
 These may be physical or virtual instances, and they represent the infrastructure for Kubernetes nodes.
 
-## Data Types
-
-A machine infrastructure provider must define an API type for "infrastructure machine" resources. The type:
-
-1. Must belong to an API group served by the Kubernetes apiserver
-2. Must be implemented as a CustomResourceDefinition.
-    1. The CRD name must have the format produced by `sigs.k8s.io/cluster-api/util/contract.CalculateCRDName(Group, Kind)`.
-3. Must be namespace-scoped
-4. Must have the standard Kubernetes "type metadata" and "object metadata"
-5. Must have a `spec` field with the following:
-    1. Required fields:
-        1. `providerID` (string): the identifier for the provider's machine instance. This field is expected to match the value set by the KCM cloud provider in the Nodes.
-           The Machine controller bubbles it up to the Machine CR, and it's used to find the matching Node.
-           Any other consumers can use the providerID as the source of truth to match both Machines and Nodes.
-            
-    2. Optional fields:
-        1. `failureDomain` (string): the string identifier of the failure domain the instance is running in for the
-           purposes of backwards compatibility and migrating to the v1alpha3 FailureDomain support (where FailureDomain
-           is specified in Machine.Spec.FailureDomain). This field is meant to be temporary to aid in migration of data
-           that was previously defined on the provider type and providers will be expected to remove the field in the
-           next version that provides breaking API changes, favoring the value defined on Machine.Spec.FailureDomain
-           instead. If supporting conversions from previous types, the provider will need to support a conversion from
-           the provider-specific field that was previously used to the `failureDomain` field to support the automated
-           migration path.
-6. Must have a `status` field with the following:
-    1. Required fields:
-        1. `ready` (boolean): indicates the provider-specific infrastructure has been provisioned and is ready
-    2. Optional fields:
-        1. `failureReason` (string): indicates there is a fatal problem reconciling the provider's infrastructure;
-            meant to be suitable for programmatic interpretation
-        2. `failureMessage` (string): indicates there is a fatal problem reconciling the provider's infrastructure;
-            meant to be a more descriptive value than `failureReason`
-        3. `addresses` (`MachineAddresses`): a list of the host names, external IP addresses, internal IP addresses,
-            external DNS names, and/or internal DNS names for the provider's machine instance. `MachineAddress` is
-            defined as:
-            - `type` (string): one of `Hostname`, `ExternalIP`, `InternalIP`, `ExternalDNS`, `InternalDNS`
-            - `address` (string)
-7. Should have a conditions field with the following:
-   1. A Ready condition to represent the overall operational state of the component. It can be based on the summary of more detailed conditions existing on the same object, e.g. instanceReady, SecurityGroupsReady conditions.
-
-Note: once any of `failureReason` or `failureMessage` surface on the machine who is referencing the infrastructureMachine object,
-they cannot be restored anymore (it is considered a terminal error; the only way to recover is to delete and recreate the machine).
-Also, if the machine is under control of a MachineHealthCheck instance, the machine will be automatically remediated.
-
-### InfraMachineTemplate Resources
-
-For a given InfraMachine resource, you should also add a corresponding InfraMachineTemplate resource:
-
-``` go
-// InfraMachineTemplateSpec defines the desired state of InfraMachineTemplate.
-type InfraMachineTemplateSpec struct {
-	Template InfraMachineTemplateResource `json:"template"`
-}
+The InfraMachine resource will be referenced by one of the Cluster API core resources, Machine.
+
+The [Machine's controller](../../core/controllers/machine.md) will be responsible to coordinate operations of the InfraMachine,
+and the interaction between the Machine's controller and the InfraMachine resource is based on the contract
+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).
+
+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
+in order to address very specific needs).
+
+In order to facilitate the initial design for each InfraMachine resource, a few [implementation best practices] and [infrastructure Provider Security Guidance]
+are explicitly called out in dedicated pages.
+
+<aside class="note warning">
+
+<h1>Never rely on Cluster API behaviours not defined as a contract rule!</h1>
+
+When developing a provider, you MUST consider any Cluster API behaviour that is not defined by a contract rule
+as a Cluster API internal implementation detail, and internal implementation details can change at any time.
+
+Accordingly, in order to not expose users to the risk that your provider breaks when the Cluster API internal behavior
+changes, you MUST NOT rely on any Cluster API internal behaviour when implementing an InfraMachine resource.
+
+Instead, whenever you need something more from the Cluster API contract, you MUST engage the community.
+
+The Cluster API maintainers welcome feedback and contributions to the contract in order to improve how it's defined,
+its clarity and visibility to provider implementers and its suitability across the different kinds of Cluster API providers.
+
+To provide feedback or open a discussion about the provider contract please [open an issue on the Cluster API](https://github.com/kubernetes-sigs/cluster-api/issues/new?assignees=&labels=&template=feature_request.md)
+repo or add an item to the agenda in the [Cluster API community meeting](https://git.k8s.io/community/sig-cluster-lifecycle/README.md#cluster-api).
+
+</aside>
+
+## Rules (contract version v1beta1)
+
+| Rule                                                                 | Mandatory | Note                                 |
+|----------------------------------------------------------------------|-----------|--------------------------------------|
+| [All resources: scope]                                               | Yes       |                                      |
+| [All resources: `TypeMeta` and `ObjectMeta`field]                    | Yes       |                                      |
+| [All resources: `APIVersion` field value]                            | Yes       |                                      |
+| [InfraMachine, InfraMachineList resource definition]                 | Yes       |                                      |
+| [InfraMachine: provider ID]                                          | Yes       |                                      |
+| [InfraMachine: failure domain]                                       | No        |                                      |
+| [InfraMachine: addresses]                                            | No        |                                      |
+| [InfraMachine: initialization completed]                             | Yes       |                                      |
+| [InfraMachine: conditions]                                           | No        |                                      |
+| [InfraMachine: terminal failures]                                    | No        |                                      |
+| [InfraMachineTemplate, InfraMachineTemplateList resource definition] | Yes       |                                      |
+| [InfraMachineTemplate: support for SSA dry run]                      | No        | Mandatory for ClusterClasses support |
+| [Multi tenancy]                                                      | No        | Mandatory for clusterctl CLI support |
+| [Clusterctl support]                                                 | No        | Mandatory for clusterctl CLI support |
+
+Note:
+- `All resources` refers to all the provider's resources "core" Cluster API interacts with;
+  In the context of this page: `InfraMachine`, `InfraMachineTemplate` and corresponding list types
+
+### All resources: scope
+
+All resources MUST be namespace-scoped.
+
+### All resources: `TypeMeta` and `ObjectMeta` field
+
+All resources MUST have the standard Kubernetes `TypeMeta` and `ObjectMeta` fields.
+
+### All resources: `APIVersion` field value
+
+In Kubernetes `APIVersion` is a combination of API group and version.
+Special consideration MUST applies to both API group and version for all the resources Cluster API interacts with.
+
+#### All resources: API group
+
+The domain for Cluster API resources is `cluster.x-k8s.io`, and infrastructure providers under the Kubernetes SIGS org
+generally use `infrastructure.cluster.x-k8s.io` as API group.
+
+If your provider uses a different API group, you MUST grant full read/write RBAC permissions for resources in your API group
+to the Cluster API core controllers. The canonical way to do so is via a `ClusterRole` resource with the [aggregation label]
+`cluster.x-k8s.io/aggregate-to-manager: "true"`.
+
+The following is an example ClusterRole for a `FooMachine` resource in the `infrastructure.foo.com` API group:
+
+```yaml
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRole
+metadata:
+    name: capi-foo-clusters
+    labels:
+      cluster.x-k8s.io/aggregate-to-manager: "true"
+rules:
+- apiGroups:
+    - infrastructure.foo.com
+  resources:
+    - foomachines
+    - foomachinetemplates
+  verbs:
+    - create
+    - delete
+    - get
+    - list
+    - patch
+    - update
+    - watch
+```
+
+Note: The write permissions are required because Cluster API manages InfraMachines generated from InfraMachineTemplates;
+when using ClusterClass and managed topologies, also InfraMachineTemplates are managed directly by Cluster API.
+
+#### All resources: version
+
+The resource Version defines the stability of the API and its backward compatibility guarantees.
+Examples include `v1alpha1`, `v1beta1`, `v1`, etc. and are governed by the [Kubernetes API Deprecation Policy].
+
+Your provider SHOULD abide by the same policies.
+
+Note: The version of your provider does not need to be in sync with the version of core Cluster API resources.
+Instead, prefer choosing a version that matches the stability of the provider API and its backward compatibility guarantees.
+
+Additionally:
+
+Providers MUST set `cluster.x-k8s.io/<version>` label on the InfraMachine Custom Resource Definitions.
+
+The label is a map from a Cluster API contract version to your Custom Resource Definition versions.
+The value is an underscore-delimited (_) list of versions. Each value MUST point to an available version in your CRD Spec.
+
+The label allows Cluster API controllers to perform automatic conversions for object references, the controllers will pick
+the last available version in the list if multiple versions are found.
+
+To apply the label to CRDs it’s possible to use commonLabels in your `kustomize.yaml` file, usually in `config/crd`:
+
+```yaml
+commonLabels:
+  cluster.x-k8s.io/v1alpha2: v1alpha1
+  cluster.x-k8s.io/v1alpha3: v1alpha2
+  cluster.x-k8s.io/v1beta1: v1beta1
+```
+
+An example of this is in the [Kubeadm Bootstrap provider](https://github.com/kubernetes-sigs/cluster-api/blob/release-1.1/controlplane/kubeadm/config/crd/kustomization.yaml).
+
+### InfraMachine, InfraMachineList resource definition
+
+You MUST define a InfraMachine resource.
+The InfraMachine resource name must have the format produced by `sigs.k8s.io/cluster-api/util/contract.CalculateCRDName(Group, Kind)`.
+
+Note: Cluster API is using such a naming convention to avoid an expensive CRD lookup operation when looking for labels from
+the CRD definition of the InfraMachine resource.
 
+It is a generally applied convention to use names in the format `${env}Machine`, where ${env} is a, possibly short, name
+for the environment in question. For example `GCPMachine` is an implementation for the Google Cloud Platform, and `AWSMachine`
+is one for Amazon Web Services.
+
+```go
 // +kubebuilder:object:root=true
-// +kubebuilder:resource:path=inframachinetemplates,scope=Namespaced,categories=cluster-api,shortName=imt
+// +kubebuilder:resource:path=foomachines,shortName=foom,scope=Namespaced,categories=cluster-api
 // +kubebuilder:storageversion
+// +kubebuilder:subresource:status
 
-// InfraMachineTemplate is the Schema for the inframachinetemplates API.
-type InfraMachineTemplate struct {
-	metav1.TypeMeta   `json:",inline"`
+// FooMachine is the Schema for foomachines.
+type FooMachine struct {
+    metav1.TypeMeta `json:",inline"`
 	metav1.ObjectMeta `json:"metadata,omitempty"`
+    Spec FooMachineSpec `json:"spec,omitempty"`
+    Status FooMachineStatus `json:"status,omitempty"`
+}
 
-	Spec InfraMachineTemplateSpec `json:"spec,omitempty"`
+type FooMachineSpec struct {
+    // See other rules for more details about mandatory/optional fields in InfraMachine spec.
+    // Other fields SHOULD be added based on the needs of your provider.
 }
 
-type InfraMachineTemplateResource struct {
-	// 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"`
-	Spec InfraMachineSpec `json:"spec"`
+type FooMachineStatus struct {
+    // See other rules for more details about mandatory/optional fields in InfraMachine status.
+    // Other fields SHOULD be added based on the needs of your provider.
 }
 ```
 
-The CRD name of the template must also have the format produced by `sigs.k8s.io/cluster-api/util/contract.CalculateCRDName(Group, Kind)`.
+For each InfraMachine resource, you MUST also add the corresponding list resource.
+The list resource MUST be named as `<InfraMachine>List`.
+
+```go
+// +kubebuilder:object:root=true
+
+// FooMachineList contains a list of foomachines.
+type FooMachineList struct {
+    metav1.TypeMeta `json:",inline"`
+    metav1.ListMeta `json:"metadata,omitempty"`
+    Items           []FooMachine `json:"items"`
+}
+```
 
-### List Resources
+### InfraMachine: provider ID
 
-For any resource, also add list resources, e.g.
+Each Machine needs a provider ID to identify the Kubernetes Node that runs on the machine. 
+Node's Provider id  MUST surface on `spec.providerID` in the InfraMachine resource.
 
 ```go
-//+kubebuilder:object:root=true
+type FooMachineSpec struct {
+    // ProviderID must match the provider ID as seen on the node object corresponding to this machine.
+	// For Kubernetes Nodes running on the Foo provider, this value is set by the corresponding CPI component 
+	// and it has the format docker:////<vm-name>. 
+    // +optional
+    ProviderID *string `json:"providerID,omitempty"`
+    
+    // See other rules for more details about mandatory/optional fields in InfraMachine spec.
+    // Other fields SHOULD be added based on the needs of your provider.
+}
+```
+
+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`.
+
+### InfraMachine: failure domain
+
+In case you are developing an infrastructure provider which has a notion of failure domains where machines should be
+placed in, the InfraMachine resource MUST comply to the value that exists in the `spec.failureDomain` field of the Machine
+(in other words, the InfraMachine MUST be placed in the failure domain specified at Machine level).
+
+Please note, that for allowing a transparent transition from when there was no failure domain support in Cluster API
+and InfraMachine was authoritative WRT to failure domain placement (before CAPI v0.3.0),
+Cluster API still supports a _deprecated_ reverse process for failure domain management.
+
+In the _deprecated_ reverse process, the failure domain where the machine should be placed is defined in the InfraMachine's 
+`spec.failureDomain` field; the value of this field is then surfaced on the corresponding field at Machine level.
+
+<aside class="note warning">
+
+<h1>Heads up! this will change with the v1beta2 contract</h1>
 
-// InfraMachineList contains a list of InfraMachines.
-type InfraMachineList struct {
-	metav1.TypeMeta `json:",inline"`
-	metav1.ListMeta `json:"metadata,omitempty"`
-	Items           []InfraCluster `json:"items"`
+Machine's controller will stop supporting the _deprecated_ reverse process; the InfraMachine's `spec.failureDomain`,
+if still present, will be ignored.
+
+However, InfraMachine will be allowed to surface the failure domain where the machine is actually placed in by 
+implementing a new, optional `status.failureDomain`; this info, if present, will then surface at Machine level in a 
+new corresponding field (also in status).
+
+```go
+type FooMachineStatus struct {
+    // FailureDomain is the unique identifier of the failure domain where this Machine has been placed in.
+    // For this Foo infrastructure provider, the name is equivalent to the name of one of the available regions.
+    FailureDomain *string `json:"failureDomain,omitempty"`
+
+    // See other rules for more details about mandatory/optional fields in InfraMachineStatus.
+    // Other fields SHOULD be added based on the needs of your provider.
 }
+```
+
+</aside>
 
-//+kubebuilder:object:root=true
+### InfraMachine: addresses
 
-// InfraMachineTemplateList contains a list of InfraMachineTemplates.
-type InfraMachineTemplateList struct {
-	metav1.TypeMeta `json:",inline"`
-	metav1.ListMeta `json:"metadata,omitempty"`
-	Items           []InfraClusterTemplate `json:"items"`
+Infrastructure provider have the opportunity to surface machines addresses on the InfraMachine resource; this information
+won't be used by core Cluster API controller, but it is really useful for operator troubleshooting issues on machines.
+
+In case you want to surface machine's addresses, you MUST surface them in `status.addresses` in the InfraMachine resource.
+
+```go
+type FooMachineStatus struct {
+    // Addresses contains the associated addresses for the machine.
+    // +optional
+    Addresses []clusterv1.MachineAddress `json:"addresses,omitempty"`
+
+    // See other rules for more details about mandatory/optional fields in InfraMachine status.
+    // Other fields SHOULD be added based on the needs of your provider.
 }
 ```
 
-## Behavior
+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`.
+
+### InfraMachine: initialization completed
+
+Each InfraMachine MUST report when Machine's infrastructure is fully provisioned (initialization) by setting
+`status.ready` in the InfraMachine resource.
+
+```go
+type FooMachineStatus struct {
+    // Ready denotes that the foo machine infrastructure is fully provisioned.
+    // +optional
+    Ready bool `json:"ready"`
+    
+    // See other rules for more details about mandatory/optional fields in InfraMachine status.
+    // Other fields SHOULD be added based on the needs of your provider.
+}
+```
+
+Once `status.ready` the Machine "core" controller will bubbles up this info in Machine's `status.infrastructureReady`;
+Also InfraMachine's `spec.providerID` and `status.addresses` will be surfaced on Machine's
+corresponding fields at the same time.
+
+<aside class="note warning">
+
+<h1>Heads up! this will change with the v1beta2 contract</h1>
+
+When the v1beta2 contract will be released (tentative Apr 2025), `status.initialization.provisioned` will be used
+instead of `status.ready`. However, `status.ready` will be supported until v1beta1 removal (~one year later).
+
+See [Improving status in CAPI resources].
+
+</aside>
 
-A machine infrastructure provider must respond to changes to its "infrastructure machine" resources. This process is
+### InfraMachine: conditions
+
+According to [Kubernetes API Conventions], Conditions provide a standard mechanism for higher-level
+status reporting from a controller.
+
+Providers implementers SHOULD implement `status.conditions` for their InfraMachine resource.
+In case conditions are implemented, Cluster API condition type MUST be used.
+
+If a condition with type `Ready` exist, such condition will be mirrored in Machine's `InfrastructureReady` condition.
+
+Please note that the `Ready` condition is expected to surface the status of the InfraMachine during its own entire lifecycle,
+including initial provisioning, the final deletion process, and the period in between these two moments.
+
+See [Cluster API condition proposal] for more context.
+
+<aside class="note warning">
+
+<h1>Heads up! this will change with the v1beta2 contract</h1>
+
+When the v1beta2 contract will be released (tentative Apr 2025), Cluster API will start using Kubernetes metav1.Condition
+types and fully comply to [Kubernetes API Conventions].
+
+In order to support providers continuing to use legacy Cluster API condition types, providers transitioning to
+metav1.Condition or even providers adopting custom condition types, Cluster API will start to accept `Ready` condition that
+provides following information:
+- `type`
+- `status`
+- `reason` ((optional, if omitted, a default one will be used)
+- `message` (optional)
+- `lastTransitionTime` (optional, if omitted, time.Now will be used)
+
+Other fields will be ignored
+
+See [Improving status in CAPI resources] for more context.
+
+Please note that provider that will continue to use legacy Cluster API condition types MUST carefully take into account
+the implication of this choice which are described both in the document above and in the notice at the beginning of the [Cluster API condition proposal]..
+
+</aside>
+
+### InfraMachine: terminal failures
+
+Each InfraMachine SHOULD report when Machine's enter in a state that cannot be recovered (terminal failure) by
+setting `status.failureReason` and `status.failureMessage` in the InfraMachine resource.
+
+```go
+type FooMachineStatus struct {
+    // FailureReason will be set in the event that there is a terminal problem reconciling the FooMachine 
+    // 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 FooMachine 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 FooMachine
+    // 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,
+    // but instead indicate that something is fundamentally wrong with the FooMachine and that it cannot be recovered.
+    // +optional
+    FailureMessage *string `json:"failureMessage,omitempty"`
+    
+    // See other rules for more details about mandatory/optional fields in InfraMachine status.
+    // Other fields SHOULD be added based on the needs of your provider.
+}
+```
+
+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`.
+
+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).
+
+<aside class="note warning">
+
+<h1>Heads up! this will change with the v1beta2 contract</h1>
+
+When the v1beta2 contract will be released (tentative Apr 2025), support for `status.failureReason` and `status.failureMessage`
+will be dropped.
+
+See [Improving status in CAPI resources].
+
+</aside>
+
+### InfraMachineTemplate, InfraMachineTemplateList resource definition
+
+For a given InfraMachine resource, you MUST also add a corresponding InfraMachineTemplate resources in order to use it
+when defining set of machines, e.g. MachineDeployments.
+
+The template resource MUST be named as `<InfraMachine>Template`.
+
+```go
+// +kubebuilder:object:root=true
+// +kubebuilder:resource:path=foomachinetemplates,scope=Namespaced,categories=cluster-api
+// +kubebuilder:storageversion
+
+// FooMachineTemplate is the Schema for the foomachinetemplates API.
+type FooMachineTemplate struct {
+    metav1.TypeMeta   `json:",inline"`
+    metav1.ObjectMeta `json:"metadata,omitempty"`
+
+    Spec FooMachineTemplateSpec `json:"spec,omitempty"`
+}
+
+type FooMachineTemplateSpec struct {
+    Template FooMachineTemplateResource `json:"template"`
+}
+
+type FooMachineTemplateResource struct {
+    // 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"`
+    Spec FooMachineSpec `json:"spec"`
+}
+```
+
+NOTE: in this example InfraMachineTemplate's `spec.template.spec` embeds `FooMachineSpec` from InfraMachine. This might not always be
+the best choice depending of if/how InfraMachine's spec fields applies to many machines vs only one.
+
+For each InfraMachineTemplate resource, you MUST also add the corresponding list resource.
+The list resource MUST be named as `<InfraMachineTemplate>List`.
+
+```go
+// +kubebuilder:object:root=true
+
+// FooMachineTemplateList contains a list of FooMachineTemplates.
+type FooMachineTemplateList struct {
+    metav1.TypeMeta `json:",inline"`
+    metav1.ListMeta `json:"metadata,omitempty"`
+    Items           []FooMachineTemplate `json:"items"`
+}
+```
+
+### InfraMachineTemplate: support for SSA dry run
+
+When Cluster API's topology controller is trying to identify differences between templates defined in a ClusterClass and
+the current Cluster topology, it is required to run [Server Side Apply] (SSA) dry run call.
+
+However, in case you immutability checks for your InfraMachineTemplate, this can lead the SSA dry run call to errors.
+
+In order to avoid this InfraMachineTemplate MUST specifically implement support for SSA dry run calls from the topology controller. 
+
+The implementation requires to use controller runtime's `CustomValidator`, available in CR versions >= v0.12.3.
+
+This will allow to skip the immutability check only when the topology controller is dry running while preserving the
+validation behavior for all other cases.
+
+See [the DockerMachineTemplate webhook] as a reference for a compatible implementation.
+
+### Multi tenancy
+
+Multi tenancy in Cluster API defines the capability of an infrastructure provider to manage different credentials,
+each one of them corresponding to an infrastructure tenant.
+
+See [infrastructure Provider Security Guidance] for considerations about cloud provider credential management.
+
+Please also note that Cluster API does not support running multiples instances of the same provider, which someone can
+assume an alternative solution to implement multi tenancy; same applies to the clusterctl CLI.
+
+See [Support running multiple instances of the same provider] for more context.
+
+However, if you want to make it possible for users to run multiples instances of your provider, your controller's SHOULD:
+
+- support the `--namespace` flag.
+- support the `--watch-filter` flag.
+
+Please, read carefully the page linked above to fully understand implications and risks related to this option.
+
+### Clusterctl support
+
+The clusterctl command is designed to work with all the providers compliant with the rules defined in the [clusterctl provider contract].
+
+## Typical InfraMachine reconciliation workflow
+
+A machine infrastructure provider must respond to changes to its InfraMachine resources. This process is
 typically called reconciliation. The provider must watch for new, updated, and deleted resources and respond
 accordingly.
 
-The following diagram shows the typical logic for a machine infrastructure provider:
+As a reference you can look at the following workflow to understand how the typical reconciliation workflow
+is implemented in InfraMachine controllers:
 
 ![Machine infrastructure provider activity diagram](../../../images/machine-infra-provider.png)
 
@@ -150,66 +527,28 @@ The following diagram shows the typical logic for a machine infrastructure provi
 1. Remove the provider-specific finalizer from the resource
 1. Patch the resource to persist changes
 
-## RBAC
-
-### Provider controller
-
-A machine infrastructure provider must have RBAC permissions for the types it defines. If you are using `kubebuilder` to
-generate new API types, these permissions should be configured for you automatically. For example, the AWS provider has
-the following configuration for its `AWSMachine` type:
-
-```
-// +kubebuilder:rbac:groups=infrastructure.cluster.x-k8s.io,resources=awsmachines,verbs=get;list;watch;create;update;patch;delete
-// +kubebuilder:rbac:groups=infrastructure.cluster.x-k8s.io,resources=awsmachines/status,verbs=get;update;patch
-```
-
-A machine infrastructure provider may also need RBAC permissions for other types, such as `Cluster` and `Machine`. If
-you need read-only access, you can limit the permissions to `get`, `list`, and `watch`. You can use the following
-configuration for retrieving `Cluster` and `Machine` resources:
-
-```
-// +kubebuilder:rbac:groups=cluster.x-k8s.io,resources=clusters;clusters/status,verbs=get;list;watch
-// +kubebuilder:rbac:groups=cluster.x-k8s.io,resources=machines;machines/status,verbs=get;list;watch
-```
-
-### Cluster API controllers
-
-The Cluster API controller for `Machine` resources is configured with full read/write RBAC
-permissions for all resources in the `infrastructure.cluster.x-k8s.io` API group. This group
-represents all machine infrastructure providers for SIG Cluster Lifecycle-sponsored provider
-subprojects. If you are writing a provider not sponsored by the SIG, you must grant full read/write
-RBAC permissions for the "infrastructure machine" resource in your API group to the Cluster API
-manager's `ServiceAccount`. `ClusterRoles` can be granted using the [aggregation label]
-`cluster.x-k8s.io/aggregate-to-manager: "true"`. The following is an example `ClusterRole` for a
-`FooMachine` resource:
-
-```yaml
-apiVersion: rbac.authorization.k8s.io/v1
-kind: ClusterRole
-metadata:
-  name: capi-foo-machines
-  labels:
-    cluster.x-k8s.io/aggregate-to-manager: "true"
-rules:
-- apiGroups:
-  - infrastructure.foo.com
-  resources:
-  - foomachines
-  verbs:
-  - create
-  - delete
-  - get
-  - list
-  - patch
-  - update
-  - watch
-```
-
-Note, the write permissions allow the `Machine` controller to set owner references and labels on the
-"infrastructure machine" resources; they are not used for general mutations of these resources.
-
+[All resources: Scope]: #all-resources-scope
+[All resources: `TypeMeta` and `ObjectMeta`field]: #all-resources-typemeta-and-objectmeta-field
+[All resources: `APIVersion` field value]: #all-resources-apiversion-field-value
 [aggregation label]: https://kubernetes.io/docs/reference/access-authn-authz/rbac/#aggregated-clusterroles
-
-## Security Guidelines
-
-Please refer to [Infrastructure Provider Security Guidance](../security-guidelines.md).
+[Kubernetes API Deprecation Policy]: https://kubernetes.io/docs/reference/using-api/deprecation-policy/
+[InfraMachine, InfraMachineList resource definition]: #inframachine-inframachinelist-resource-definition
+[InfraMachine: provider ID]: #inframachine-provider-id
+[InfraMachine: failure domain]: #inframachine-failure-domain
+[InfraMachine: addresses]: #inframachine-addresses
+[InfraMachine: initialization completed]: #inframachine-initialization-completed
+[Improving status in CAPI resources]: https://github.com/kubernetes-sigs/cluster-api/blob/main/docs/proposals/20240916-improve-status-in-CAPI-resources.md
+[InfraMachine: conditions]: #inframachine-conditions
+[Kubernetes API Conventions]: https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md#typical-status-properties
+[Cluster API condition proposal]: https://github.com/kubernetes-sigs/cluster-api/blob/main/docs/proposals/20200506-conditions.md
+[InfraMachine: terminal failures]: #inframachine-terminal-failures
+[InfraMachineTemplate, InfraMachineTemplateList resource definition]: #inframachinetemplate-inframachinetemplatelist-resource-definition
+[InfraMachineTemplate: support for SSA dry run]: #inframachinetemplate-support-for-ssa-dry-run
+[Multi tenancy]: #multi-tenancy
+[Support running multiple instances of the same provider]: ../../core/support-multiple-instances.md
+[Clusterctl support]: #clusterctl-support
+[clusterctl provider contract]: clusterctl.md
+[implementation best practices]: ../best-practices.md
+[infrastructure Provider Security Guidance]: ../security-guidelines.md
+[Server Side Apply]: https://kubernetes.io/docs/reference/using-api/server-side-apply/
+[the DockerMachineTemplate webhook]: https://github.com/kubernetes-sigs/cluster-api/blob/main/test/infrastructure/docker/internal/webhooks/dockermachinetemplate_webhook.go
diff --git a/docs/book/src/developer/providers/getting-started/webhooks.md b/docs/book/src/developer/providers/getting-started/webhooks.md
index 07ee8b9c930b..a4e5a9f28e5d 100644
--- a/docs/book/src/developer/providers/getting-started/webhooks.md
+++ b/docs/book/src/developer/providers/getting-started/webhooks.md
@@ -17,28 +17,6 @@ A validating webhook allows developers to test whether values supplied by users
 the Infrastructure reference supplied at the Cluster's `.spec.infrastructureRef` is in the same namespace as the Cluster itself
 and rejects the object creation or update if not.
 
-<aside class="note">
-
-<h1> ClusterClass and managed topology support in validating webhooks </h1>
-
-Validating webhooks implemented for a `InfrastructureMachineTemplate` or `BootstrapConfigTemplate` resource
-are required to not block due to immutability checks when the controller for managed
-topology and ClusterClass does [Server Side Apply] dry-run requests.
-[Server Side Apply] implementation in ClusterClass and managed topologies requires to dry-run changes on templates.
-If infrastructure or bootstrap providers have implemented immutability checks in their InfrastructureMachineTemplate
-or BootstrapConfigTemplate webhooks, it is required to implement the following changes in order to prevent dry-run
-to return errors. The implementation requires sigs.k8s.io/controller-runtime in version >= v0.12.3.
-In order to do so it is required to use a controller runtime CustomValidator.
-This will allow to skip the immutability check only when the topology controller is dry running while preserving the
-validation behavior for all other cases.
-
-See [the DockerMachineTemplate webhook] as a reference for a compatible implementation.
-
-[Server Side Apply]: https://kubernetes.io/docs/reference/using-api/server-side-apply/
-[the DockerMachineTemplate webhook]: https://github.com/kubernetes-sigs/cluster-api/blob/main/test/infrastructure/docker/internal/webhooks/dockermachinetemplate_webhook.go
-
-</aside>
-
 ## Defaulting webhooks
 Defaulting webhooks are an implementation of a [Kubernetes mutating webhook](https://kubernetes.io/docs/reference/access-authn-authz/admission-controllers/#mutatingadmissionwebhook). 
 
@@ -52,7 +30,7 @@ Conversion webhooks are what allow Cluster API to work with multiple API version
 It does this by converting the incoming version to a `Hub` version which is used internally by the controllers. 
 To read more about conversion see the [Kubebuilder documentation](https://book.kubebuilder.io/multiversion-tutorial/conversion.html)
 
-For a walkthrough on implementing conversion webhooks see the video in the [Developer Guide](../../guide.md#videos-explaining-capi-architecture-and-code-walkthroughs)
+For a walkthrough on implementing conversion webhooks see the video in the [Developer Guide](../../getting-started.md#videos-explaining-capi-architecture-and-code-walkthroughs)
 
 ## Implementing webhooks with Controller Runtime, Controller Tools and Kubebuilder