Update optional fields in controller contracts

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

@@ -44,6 +44,11 @@ The `status` object **may** define several fields that do not affect functionali
 
 * `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.
+* `failureDomains` - is a `FailureDomains` type indicating the failure domains that machines should be placed in. `FailureDomains`
+is a map, defined as `map[string]FailureDomainSpec`. A unique key must be used for each `FailureDomainSpec`.
+`FailureDomainSpec` is defined as:
+    - `controlPlane` (bool): indicates if failure domain is appropriate for running control plane instances.
+    - `attributes` (`map[string]string`): arbitrary attributes for users to apply to a failure domain.
 
 Example:
 ```yaml

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

@@ -81,6 +81,12 @@ 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:
@@ -93,6 +99,11 @@ The `status` object **may** define several fields that do not affect functionali
 
 * `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)
 
 Example:
 ```yaml

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

@@ -30,7 +30,7 @@ A cluster infrastructure provider must define an API type for "infrastructure cl
             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. `failureDomains` (`failureDomains`): the failure domains that machines should be placed in. `failureDomains`
+        3. `failureDomains` (`FailureDomains`): the failure domains that machines should be placed in. `FailureDomains`
             is a map, defined as `map[string]FailureDomainSpec`. A unique key must be used for each `FailureDomainSpec`.
             `FailureDomainSpec` is defined as:
             - `controlPlane` (bool): indicates if failure domain is appropriate for running control plane instances.

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

@@ -37,11 +37,11 @@ A machine infrastructure provider must define an API type for "infrastructure ma
             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` (`MachineAddress`): a list of the host names, external IP addresses, internal IP addresses,
+        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)
+            - `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.