Update provider contract to account for the paused condition

This change updates the provider contract to account for a new paused
condition.

It is intended to start as an optional condition, but then become
required at a later date.

docs/book/src/developer/providers/code-examples.md

@@ -0,0 +1,28 @@
+<!-- DOCTOC SKIP -->
+   // Return early and set the paused condition to True if the object or Cluster
+   // is paused.
+   // We assume that the change to the object has to be written, e.g. via the
+   // patchHelper in defer.
+   if annotations.IsPaused(cluster, m) {
+    log.Info("Reconciliation is paused for this object")
+
+    newPausedCondition := &clusterv1.Condition{
+        Type:     clusterv1.PausedCondition,
+        Status:   corev1.ConditionTrue,
+        Severity: clusterv1.ConditionSeverityInfo,
+    }
+
+    if cluster.Spec.Paused {
+        newPausedCondition.Reason = clusterv1.ClusterPausedReason
+        newPausedCondition.Message = fmt.Sprintf("The cluster %s is paused, pausing this object until the cluster is unpaused", cluster.Name)
+    } else {
+        newPausedCondition.Reason = clusterv1.AnnotationPausedReason
+        newPausedCondition.Message = fmt.Sprintf("The machine %s is paused, pausing this object until the annotation is removed", m.Name)
+
+    }
+
+    conditions.Set(m, newPausedCondition)
+    return ctrl.Result{}, nil
+   }
+
+   conditions.MarkFalseWithNegativePolarity(m, clusterv1.PausedCondition)

docs/book/src/developer/providers/contracts/bootstrap-config.md

@@ -26,6 +26,11 @@ A bootstrap provider must define an API type for bootstrap resources. The type:
             meant to be suitable for programmatic interpretation
         2. `failureMessage` (string): indicates there is a fatal problem reconciling the bootstrap data;
             meant to be a more descriptive value than `failureReason`
+7. Should have `Status.Conditions` with the following:
+   1. A `Status.Conditions[Paused]` to report if the cluster or bootstrap resource is paused. It should check if 'spec.paused' is set on the cluster, and for the paused annotation on the resource. This is currently optional, but will be required in the future.
+   ```go
+{{#include code-examples.md:2:28}}
+   ```
 
 Note: once any of `failureReason` or `failureMessage` surface on the machine/machine pool 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/machine pool). 

docs/book/src/developer/providers/contracts/control-plane.md

@@ -249,6 +249,10 @@ The `status` object **may** define several fields:
 * `externalManagedControlPlane` - is a bool that should be set to true if the Node objects do not
   exist in the cluster. For example, managed control plane providers for AKS, EKS, GKE, etc, should
   set this to `true`. Leaving the field undefined is equivalent to setting the value to `false`.
+* `.Conditions[Paused]` - is a condition that reports if the cluster or control plane resource is paused. It should check if 'spec.paused' is set on the cluster, and for the paused annotation on the resource. This is currently optional, but will become required in future.
+  ```go
+{{#include ../../providers/code-examples.md:2:28}}
+  ```
 
 Note: once any of `failureReason` or `failureMessage` surface on the cluster who is referencing the control plane object,
 they cannot be restored anymore (it is considered a terminal error; the only way to recover is to delete and recreate the cluster).

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

@@ -42,8 +42,13 @@ A machine infrastructure provider must define an API type for "infrastructure ma
             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.
+7. Should have a `Status.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.
+   2. A `Paused` condition to report if the cluster or infrastructure machine is paused. It should check if 'spec.paused' is set on the cluster, and for the paused annotation on the infrastructure. This is currently optional, but will be required in the future.
+   ```go
+{{#include code-examples.md:2:28}}
+   ```
+
 
 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).