more comments

docs/book/src/developer/architecture/controllers/multi-tenancy.md

@@ -4,9 +4,10 @@ Multi tenancy in Cluster API defines the capability of an infrastructure provide
 one of them corresponding to an infrastructure tenant.
 
 ## Contract
+
 In order to support multi tenancy, the following rule applies:
 
 - Infrastructure providers MUST be able to manage different sets of credentials (if any)
 - Providers SHOULD deploy and run any kind of webhook (validation, admission, conversion)
-  following Cluster API codebase best practices for the same release. 
+  following Cluster API codebase best practices for the same release.
 - Providers MUST create and publish a `{type}-component.yaml` accordingly.

docs/book/src/developer/architecture/controllers/support-multiple-instances.md

@@ -5,25 +5,25 @@ instances of the same provider, each one with its own set of credentials while w
 
 However, running multiple instances of the same provider proved to be complicated for several reasons:
 
-- Complexity in packaging providers: CustomResourceDefinitions (CRD) are global resources, these may have a reference 
+- Complexity in packaging providers: CustomResourceDefinitions (CRD) are global resources, these may have a reference
   to a service that can be used to covert between CRD versions (conversion webhooks). Only one of these services should
   be running at any given time, this requirement led us to previously split the webhooks code to a different deployment
   and namespace.
-- Complexity in deploying providers, due to the requirement to ensure consistency of the management cluster, e.g. 
-  controllers watching the same namespaces. 
+- Complexity in deploying providers, due to the requirement to ensure consistency of the management cluster, e.g.
+  controllers watching the same namespaces.
 - The introduction of the concept of management groups in clusterctl, with impacts on the user experience/documentation.
 - Complexity in managing co-existence of different versions of the same provider while there could be only
-  one version of CRDs and webhooks. Please note that this constraint generates a risk, because some version of the provider 
+  one version of CRDs and webhooks. Please note that this constraint generates a risk, because some version of the provider
   de-facto were forced to run with CRDs and webhooks deployed from a different version.
 
-Nevertheless, we want to make it possible for users to choose to deploy multiple instances of the same providers, 
+Nevertheless, we want to make it possible for users to choose to deploy multiple instances of the same providers,
 in case the above limitations/extra complexity are acceptable for them.
 
 ## Contract
 
 In order to make it possible for users to deploy multiple instances of the same provider:
 
-- All the provider MUST support the `--namespace` flag in their controllers.
+- Providers MUST support the `--namespace` flag in their controllers.
 
 ⚠️ Users selecting this deployment model, please be aware:
 

docs/book/src/developer/providers/v1alpha3-to-v1alpha4.md

@@ -41,3 +41,16 @@ the delegating client by default under the hood, so this can be now removed.
 - The functions `fake.NewFakeClientWithScheme` and `fake.NewFakeClient` have been deprecated.
 - Switch to `fake.NewClientBuilder().WithObjects().Build()` instead, which provides a cleaner interface
   to create a new fake client with objects, lists, or a scheme.
+
+## Multi tenancy
+
+Up until v1alpha3, the need of supporting multiple credentials was addressed by running multiple
+instances of the same provider, each one with its own set of credentials while watching different namespaces.
+
+Starting from v1alpha4 instead we are going require that an infrastructure provider should manage different credentials,
+each one of them corresponding to an infrastructure tenant.
+
+see [Multi-tenancy](../architecture/controllers/multi-tenancy.md) and [Support multiple instances](../architecture/controllers/support-multiple-instances.md) for
+more details.
+
+Specific changes related to this topic will be detailed in this document.