📖 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]

[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 oscr 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:

• docs/OWNERS

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

[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

[JoelSpeed]

Should this have additional information as to why it's being paused? A reason, a message, a severity?

[theobarberbany]

Yeah, this occured to me when working on this. I mean to ask but lost track!

We don't currently have a helper to set a reason with a MarkTrue - I could make one, but was wondering if there was reasoning around not having done so previously?

e.g:

cluster-api/util/conditions/setter.go

Lines 80 to 108 in fe9d5bc

	// TrueCondition returns a condition with Status=True and the given type.
	func TrueCondition(t clusterv1.ConditionType) *clusterv1.Condition {
	return &clusterv1.Condition{
	Type: t,
	Status: corev1.ConditionTrue,
	}
	}
	// FalseCondition returns a condition with Status=False and the given type.
	func FalseCondition(t clusterv1.ConditionType, reason string, severity clusterv1.ConditionSeverity, messageFormat string, messageArgs ...interface{}) *clusterv1.Condition {
	return &clusterv1.Condition{
	Type: t,
	Status: corev1.ConditionFalse,
	Reason: reason,
	Severity: severity,
	Message: fmt.Sprintf(messageFormat, messageArgs...),
	}
	}
	// UnknownCondition returns a condition with Status=Unknown and the given type.
	func UnknownCondition(t clusterv1.ConditionType, reason string, messageFormat string, messageArgs ...interface{}) *clusterv1.Condition {
	return &clusterv1.Condition{
	Type: t,
	Status: corev1.ConditionUnknown,
	Reason: reason,
	Message: fmt.Sprintf(messageFormat, messageArgs...),
	}
	}

[JoelSpeed]

Yeah good question, for this condition I definitely imagine it having a reason or message. "PausedAnnotationPresent - Resource is paused as it is annotated with the pause annotation" or "ClusterPaused - Resource is paused due to cluster being paused"

Perhaps we just haven't needed that kind of condition before?

[theobarberbany]

Ok, sounds good to me. I'll update the WIP PR and these docs :)

Perhaps we just haven't needed that kind of annotation before?

Yep, this makes sense!

[fabriziopandini]

That's an interesting one.
According to https://github.com/kubernetes-sigs/cluster-api/blob/main/docs/proposals/20200506-conditions.md, condition types MUST have a consistent polarity (i.e. "True = good").

Also

Condition types in Cluster API core objects MUST represent the operational state of a component in the cluster, where the operational state is when the component is ready to serve application workloads...
Operations like upgrades, scaling-up, or scaling-down, even if orchestrated in a non-disruptive fashion, MUST be considered as a deviation from the normal operational state of the cluster...

So, if we stick to current conditions standard in Cluster, unfortunately paused isn't a compliant condition, because it doesn't have a positive polarity (and this is why it doesn't fit into existing helpers).

The idea of improving conditions have been around since some time now (see eg #7635 + linked docs); we should figure it out if this goes in the critical path for this change or not

[JoelSpeed]

condition types MUST have a consistent polarity (i.e. "True = good").

Well that is an interesting constraint, do you have any idea where that came from? I believe it's pretty common to have conditions that are not True = good, for example, Node's have DiskPressure and other pressures where True = bad

Skimming through the enhancement I have little issue otherwise with what's prescribed there, it seems reasonable apart from this constraint on True = good and the allowed suffixes for conditions 🤔

I don't see any such constraints in the upstream conditions KEP. In fact, in the API conventions you have:

Condition type names should make sense for humans; neither positive nor negative polarity can be recommended as a general rule

---

So, if we stick to current conditions standard in Cluster, unfortunately paused isn't a compliant condition, because it doesn't have a positive polarity (and this is why it doesn't fit into existing helpers).

In theory we could rename the condition to make it compliant, but, to me at least, that feels like we are cutting our nose to spite our face. Paused is a natural term for what we are trying to represent here, ReconcileAllowed or alternatives that fit the convention feel very awkward to me. And as above, this is not recommended in Kube in general.

Also, reviewing this summary, it appears there are a large number of exceptions to the rules there already? Are those still accurate, I appreciate the doc is 18 months old at this point

[fabriziopandini]

The assumption about polarity is backed into the condition package everyone is using to aggregate conditions, roll them up across the hierarchy of objects etc. so I don't think we have exceptions as of today, but we have a lot of room for improvements which I tried to capture in the doc.

I also fully agree we should do a new iteration on the package above + overall conditions, happy to pair if someone is interested in it

[theobarberbany]

I also fully agree we should do a new iteration on the package above + overall conditions, happy to pair if someone is interested in it

I'd be happy to take a stab at this, and also to pair on it :)

Happy to have a quick catch up (meet, slack etc) to clarify expectations as well. Let me know when is good for you!

[sbueringer]

Hm, stupid question. Isn't Paused neither good nor bad? I also think it doesn't really make sense to use it in summaries. How would Paused true or false aggregate into e.g. a Ready condition? (in my opinion neither true nor false should influence something like Ready)

For me the concept of polarity (in the sense of good/bad) doesn't make sense for something like "Paused".

(apart from "Paused" being clearly better then something like "Unpaused" because "Paused" doesn't invert the meaning like "Unpaused" does, so it's easier to grasp)

If it's only baked into the condition package in aggregations we should be okay, as aggregations just don't make sense for this condition. (We also already have other conditions that we intentionally don't aggregate because it doesn't make sense)

[sbueringer]

(Discussed this a bit with Fabrizio and Christian, I think the tl;dr for now is that we likely want to get rid of the polarity thing. I think @fabriziopandini will expand on it somewhere in a bit)

[sbueringer]

/ok-to-test

[sbueringer]

Not sure if we need/want "setting Paused condition" in the log (no strong opinion)

(technically we are also setting the paused condition if we set it to false, and we only actually "set" it if it wasn't already set to the same value before)

[theobarberbany]

Yeah, I agree here - I think this sounds a little weird.

I'll leave it at "Reconciliation is paused for this object"

[sbueringer]

This snippet assumes that there is something writing the modified object in defer. While we usually do this with the patch helper:

1. it's not a contract, not sure who is currently doing this (probably most though)
2. As far as I can tell today most of our controllers are creating the patchHelper after they check for paused

Maybe the best way to address this is to just add a note here that we assume that the change to the object has to be written, e.g. via the patchHelper in defer

[sbueringer]

Usually these bullet points are 1:1 mapping to API fields with the same name.I think it would be good to write this somewhat informally like this. .conditions[Type="ClusterPaused"] (or whatever string we pick for this condition)

(Not sure if we have other places with prior art how to document conditions in these listings)

[theobarberbany]

I'll have a look for prior art, and if not update to your suggestion :)

[sbueringer]

Hm, stupid question. Isn't Paused neither good nor bad? I also think it doesn't really make sense to use it in summaries. How would Paused true or false aggregate into e.g. a Ready condition? (in my opinion neither true nor false should influence something like Ready)

For me the concept of polarity (in the sense of good/bad) doesn't make sense for something like "Paused".

(apart from "Paused" being clearly better then something like "Unpaused" because "Paused" doesn't invert the meaning like "Unpaused" does, so it's easier to grasp)

If it's only baked into the condition package in aggregations we should be okay, as aggregations just don't make sense for this condition. (We also already have other conditions that we intentionally don't aggregate because it doesn't make sense)

[sbueringer]

ResourceNotPausedReason seems very strange to me. Do we need a reason for something not being paused?

[sbueringer]

I think this could be addressed as part of getting rid of the polarity thing. Basically currently we sort of assume that we only need a reason if a condition is "not good" (i.e. not true). Without polarity we can set reason/message independent of true/false. This allows us to:

• not provide a reason when Paused is false
• provide a reason when Paused is true

[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.