📖 Update provider contract to account for the paused condition

[theobarberbany]

What this PR does / why we need it:
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. See issue for more context.

Relates #10130

/area documentation

[k8s-ci-robot]

Hi @theobarberbany. Thanks for your PR.

I'm waiting for a kubernetes-sigs member to verify that this patch is reasonable to test. If it is, they should reply with /ok-to-test on its own line. Until that is done, I will not automatically test new commits in this PR, but the usual testing commands by org members will still work. Regular contributors should join the org to skip this step.

Once the patch is verified, the new status will be reflected by the ok-to-test label.

I understand the commands that are listed here.

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

[theobarberbany]

/area documentation

[sbueringer]

/ok-to-test

[k8s-ci-robot]

PR needs rebase.

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

[k8s-ci-robot]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
Once this PR has been reviewed and has the lgtm label, please assign chrischdi for approval. For more information see the Kubernetes Code Review Process.

The full list of commands accepted by this bot can be found here.

Needs approval from an approver in each of these files:

• OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[theobarberbany]

I'm not sure if I want a FalseConditionWithNegativePolarity here? Does a resource not being paused, therefore reconciling now count as a positive polarity event?

Although, then the helper does not accept a reason or severity.

Maybe This would be more straightforward with just conditions.Set(), I think I'm agreeing more with the paused condition not being polar.

cc @sbueringer

[sbueringer]

I would say let's use conditions.Set()

Let's only provide severity + reason + message if the object is paused. Goal would be to precisely write in the message why the object is paused (e.g. because the Cluster is paused, or the object itself is paused, but we can finalize wording of that message on the implementation PR)

[theobarberbany]

Ok - I've updated the PR to do this! :)

I'm not sure if it makes sense to have reason + message, where reason can be the cluster is paused, or that the annotation is present. What extra would we gain from adding a message?

[sbueringer]

There are multiple reasons why a resource could be paused. One example: A Machine can be paused because the Machine itself is paused or because the Cluster is paused.

I would like to surface all the reasons why something is paused so folks know what to change to unpause (and also after which "unpause" the reconciliation continues)

[theobarberbany]

Ah yep, I understand and agree with your motivation there! I just imagined those having different reasons:

// ClusterPausedReason (Severity=Info) documents a CAPI object that is paused due to the cluster being paused (.Spec.Paused).
ClusterPausedReason = "ClusterPaused"

// AnnotationPausedReason (Severity=Info) documents a CAPI object that is paused due to the paused annotation being present.
AnnotationPausedReason = "PausedAnnotationSet"

// MachineDeploymentPausedReason (Severity=Info) documents a CAPI object that is paused due to the machine deployment being paused.
MachineDeploymentPausedReason = "MachineDeploymentPaused"

In this instance I'm not sure what extra useful information we might add in a message? E.g in the scenario where a cluster is paused, adding the name of the cluster? Name of the annotation?

Or would a single reason make more sense, with more information in the message about the specifics of the reason?

[sbueringer]

Ah sorry that was confusing :D. I would use one Reason constant and then just describe the details in the message

[theobarberbany]

Ahh ok - makes sense! :)

[theobarberbany]

Ok, I think the latest changes should have short reason + more descriptive message!