From bfb4ec880a3ead5db8aa523366e3f28d0bb274b6 Mon Sep 17 00:00:00 2001 From: Theo Barber-Bany Date: Thu, 25 Apr 2024 16:45:08 +0100 Subject: [PATCH] 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. --- .../src/developer/providers/code-examples.md | 28 +++++++++++++++++++ .../providers/contracts/bootstrap-config.md | 5 ++++ .../providers/contracts/control-plane.md | 4 +++ .../providers/contracts/infra-machine.md | 9 ++++-- 4 files changed, 44 insertions(+), 2 deletions(-) create mode 100644 docs/book/src/developer/providers/code-examples.md diff --git a/docs/book/src/developer/providers/code-examples.md b/docs/book/src/developer/providers/code-examples.md new file mode 100644 index 000000000000..79cba76c1d87 --- /dev/null +++ b/docs/book/src/developer/providers/code-examples.md @@ -0,0 +1,28 @@ + + // 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) diff --git a/docs/book/src/developer/providers/contracts/bootstrap-config.md b/docs/book/src/developer/providers/contracts/bootstrap-config.md index baf890fda2cd..4b5447252f05 100644 --- a/docs/book/src/developer/providers/contracts/bootstrap-config.md +++ b/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). diff --git a/docs/book/src/developer/providers/contracts/control-plane.md b/docs/book/src/developer/providers/contracts/control-plane.md index 036d87a8d923..b909ffaca2fc 100644 --- a/docs/book/src/developer/providers/contracts/control-plane.md +++ b/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). diff --git a/docs/book/src/developer/providers/contracts/infra-machine.md b/docs/book/src/developer/providers/contracts/infra-machine.md index 3ec498714872..3c781bc03af5 100644 --- a/docs/book/src/developer/providers/contracts/infra-machine.md +++ b/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).