Expand MR Status Condition Type details #752
Conversation
Signed-off-by: Pete Lumbis <[email protected]>
✅ Deploy Preview for crossplane ready!
To edit notification comments on pull requests, go to your Netlify site configuration. |
There was a problem hiding this comment.
Thanks @plumbis!
My comments might be too much detail for the docs, so take from them whatever you think is appropriate.
Another note of potential interest: readiness is cumulative but synced-ness is not.
A claim only becomes ready when its XR and its entire tree of composed resources (including nested XRs and their composed resources) become ready.
On the other hand, a claim becomes synced as soon as it applies it desired state to the XR, even if that state is nonsensical and results in a broken XR. (The claim controller still did what it was asked to without hitting an error.) Ditto with XRs and MRs - as long as they successfully do what you told them they'll be synced.
In general (across claims, XRs, and MRs) you can think of "synced" as meaning "Crossplane was able to do what you told it to do". "Ready" means "what you told Crossplane to do resulted in (apparently) working infrastructure".
Signed-off-by: Pete Lumbis <[email protected]>
|
Thanks @negz ! I updated those two sections, let me know if you're good with this or have any other feedback. When we're good I'll copy this to the v1.15 folder as well. |
| The condition `Type: Synced` and `Status: True` means Crossplane successfully | ||
| communicated with the Provider on the status of the manged resource and synced | ||
| the managed resource's desired state with the observed state of the external | ||
| resource. |
There was a problem hiding this comment.
I'd suggest leaving out "Crossplane communicated with the provider". I think it's misleading.
There's really no communication between Crossplane and the provider here, everything is done entirely by the provider.
You could either just talk about what the provider did, without mentioning Crossplane, or simplify and talk about what Crossplane did. I'd prefer the former, but the latter also makes sense if I think of "Crossplane" as a whole system, rather than a specific component.
Edit: Or by "Provider" do you mean "external system"? The capital P in Provider makes me think you're talking about the component of Crossplane, not the external system,
There was a problem hiding this comment.
No, I meant the Provider component. How's this:
Condition
Type: Syncedindicates the Provider has checked the status of the
managed resource with the external service.
(I don't love 'external service` but I don't want to say Provider twice)
| Condition `Type: Synced` indicates Crossplane has checked the status of the managed | ||
| resource with the Provider. |
There was a problem hiding this comment.
Is there a verb other than "checked" that could work here?
Checked reads as if "syncing" a resource is a read-only operation, but it isn't.
I like "update or determine" below if that's not too unwieldy here. So "Crossplane has updated and determined the status of the managed resource".
There was a problem hiding this comment.
How about "validated the status of the managed resource..."?
I'm trying to break the Condition and Status into two parts, where the Condition is "we tried to inspect at the MR" and the status is "inspection worked and now update if needed". Because of that I want to avoid "updated" in the first paragraph.
There was a problem hiding this comment.
I'm trying to break the Condition and Status into two parts, where the Condition is "we tried to inspect at the MR" and the status is "inspection worked and now update if needed".
Breaking it into two parts doesn't make sense to me. The status condition represents the entire reconcile operation, not only the inspection of the MR.
Maybe writing out what happens in pseudocode would help explain this better:
def sync_resource():
desired = read_desired_state()
actual = read_actual_state()
if actual != desired:
update_actual_state(desired)
def main():
while True:
try:
sync_resource()
except SyncException:
set_condition_synced_false()
else:
set_condition_synced_true()
sleep(60)Most reconcile loops boil down to read desired state, read actual state, update actual state to match desired state. If all of that works we set Synced: true. If any of that fails we set Synced: false.
There was a problem hiding this comment.
Got it.
When does a resource move from Ready/True to Synced/True? On the first reconcile after it's ready?
There was a problem hiding this comment.
When does a resource move from Ready/True to Synced/True?
The two condition types (Synced and Ready) are independent of each other, so I wouldn't think a resource moving from one to the other.
That said, Synced: True is usually going to happen first, because for Synced to be True the controller just needs to get through one reconcile loop without hitting an error.
Let's say it's the very first reconcile of an MR, and the code managed to observe the external resource, notice it doesn't exist, and create it. Synced would be True because the controller just "synced" the desired state. In this case, by creating the external resource.
Often Ready: True would happen a bit later, because many MR controllers observe the external resource to see whether it appears to be ready (according to the API). So at that point the MR would be Synced: True and Ready: True.
There was a problem hiding this comment.
Expanding on the pseudocode to include the ready condition:
def sync_resource():
desired = read_desired_state()
actual = read_actual_state()
if actual != desired:
update_actual_state(desired)
return actual
def main():
while True:
try:
actual_state = sync_resource()
if is_ready(actual_state):
set_condition_ready_true()
else:
set_condition_ready_false()
except SyncException:
set_condition_synced_false()
else:
set_condition_synced_true()
sleep(60)
This PR resolves #750, adding details on the Condition types.
I also added
hovertags for all status reasons.