Merge pull request #2623 from detiber/updateFailureDomainDocs

📖 Update provider documentation for failureDomains

docs/book/src/developer/providers/machine-infrastructure.md

@@ -17,7 +17,14 @@ A machine infrastructure provider must define an API type for "infrastructure ma
     1. Required fields:
         1. `providerID` (string): the identifier for the provider's machine instance
     2. Optional fields:
-        1. `failureDomain` (string): the string identifier of the failure domain the instance is running in
+        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

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

@@ -166,6 +166,10 @@ An infrastructure provider can implement this by setting the `InfraCluster.Statu
 unique keys to `failureDomainSpec`s as well as respecting a set `Machine.Spec.FailureDomain` field when creating
 instances.
 
+To support migration from failure domains that were previously specified through provider-specific resources, the
+Machine controller will support updating `Machine.Spec.FailureDomain` field if `Spec.FailureDomain` is present and
+defined on the provider-defined infrastructure resource.
+
 Please see the cluster and machine infrastructure provider specifications for more detail.
 
 ## Refactor kustomize `config/` folder to support multi-tenancy when using webhooks.
@@ -475,4 +479,4 @@ spec:
 It is the recommended way to setup a management cluster and it implements best practices to avoid common mis-configurations
 and for managing the life-cycle of deployed providers, e.g. upgrades.
 
-see [clusterctl provider contract](../../clusterctl/provider-contract.md) for more details.
+see [clusterctl provider contract](../../clusterctl/provider-contract.md) for more details.