Skip to content

Commit

Permalink
Update provider contract to account for the paused condition
Browse files Browse the repository at this point in the history
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.
  • Loading branch information
theobarberbany committed Jul 8, 2024
1 parent d79694c commit 7207fac
Show file tree
Hide file tree
Showing 4 changed files with 62 additions and 2 deletions.
12 changes: 12 additions & 0 deletions docs/book/src/developer/architecture/controllers/control-plane.md
Original file line number Diff line number Diff line change
Expand Up @@ -264,6 +264,18 @@ 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
// Return early and set the paused condition to True if the object or Cluster
// is paused.
if annotations.IsPaused(cluster, m) {
log.Info("Reconciliation is paused for this object")
conditions.MarkTrue(m, clusterv1.PausedCondition)
return ctrl.Result{}, nil
}
conditions.MarkFalse(m, clusterv1.PausedCondition, clusterv1.ResourceNotPausedReason, clusterv1.ConditionSeverityInfo, "Resource is operating as expected")
```

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).
Expand Down
17 changes: 17 additions & 0 deletions docs/book/src/developer/providers/bootstrap.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,23 @@ 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
// 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")
conditions.MarkTrue(m, clusterv1.PausedCondition)
return ctrl.Result{}, nil
}

conditions.MarkFalse(m, clusterv1.PausedCondition, clusterv1.ResourceNotPausedReason, clusterv1.ConditionSeverityInfo, "Resource is operating as expected")
```


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).
Expand Down
15 changes: 15 additions & 0 deletions docs/book/src/developer/providers/cluster-infrastructure.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,21 @@ A cluster infrastructure provider must define an API type for "infrastructure cl
`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.
7. Should have a `Status.Conditions` with the following:
1. A `Paused` condition to report if the cluster or cluster infrastructure 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
// 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")
conditions.MarkTrue(m, clusterv1.PausedCondition)
return ctrl.Result{}, nil
}

conditions.MarkFalse(m, clusterv1.PausedCondition, clusterv1.ResourceNotPausedReason, clusterv1.ConditionSeverityInfo, "Resource is operating as expected")

Note: once any of `failureReason` or `failureMessage` surface on the cluster who is referencing the infrastructureCluster object,
they cannot be restored anymore (it is considered a terminal error; the only way to recover is to delete and recreate the cluster).
Expand Down
20 changes: 18 additions & 2 deletions docs/book/src/developer/providers/machine-infrastructure.md
Original file line number Diff line number Diff line change
Expand Up @@ -42,8 +42,24 @@ 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
// 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")
conditions.MarkTrue(m, clusterv1.PausedCondition)
return ctrl.Result{}, nil
}

conditions.MarkFalse(m, clusterv1.PausedCondition, clusterv1.ResourceNotPausedReason, clusterv1.ConditionSeverityInfo, "Resource is operating as expected")
```


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).
Expand Down

0 comments on commit 7207fac

Please sign in to comment.