Skip to content

Expand MR Status Condition Type details #752

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
wants to merge 2 commits into
base: master
Choose a base branch
from
Draft

Expand MR Status Condition Type details #752

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
b103bdc
Add hover labels to status and add status details
plumbis Apr 12, 2024
f91bcf3
updates based on nic's feedback
plumbis Apr 16, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
159 changes: 104 additions & 55 deletions content/master/concepts/managed-resources.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -839,96 +839,143 @@ Providers may define their own custom `Conditions`.
{{</hint >}}


### Available
`Reason: Available` indicates the Provider created the managed resource and it's
ready for use.
### Type: Ready

```yaml {copy-lines="none"}
Condition `Type: Ready` indicates if the external resource is ready to use.

The Condition `Type: Ready` and `Status: True` indicates Provider created
the external resource and notified Crossplane it's ready to use. Either the
external API explicitly indicated the resource is ready or Crossplane appears to
have successfully created the external resource.

{{<hint "important" >}}
Crossplane doesn't update `Status: True` during a resource update.
{{< /hint >}}

The Condition `Type: Ready` and `Status: False` indicates the external resource
isn't available.


#### Available
{{<hover label="available" line="4">}}Reason: Available{{</hover>}} indicates
the Provider created the managed resource and it's ready for use.

```yaml {copy-lines="none",label="available"}
Conditions:
Type: Ready
Status: True
Reason: Available
```
### Creating

`Reason: Creating` indicates the Provider is attempting to create the managed
resource.
#### Creating

```yaml {copy-lines="none"}
{{<hover label="creating" line="4">}}Reason: Creating{{</hover>}} indicates the
Provider is attempting to create the managed resource.

```yaml {copy-lines="none",label="creating"}
Conditions:
Type: Ready
Status: False
Reason: Creating
```

### Deleting
`Reason: Deleting` indicates the Provider is attempting to delete the managed
resource.
#### Deleting
{{<hover label="deleting" line="4">}}Reason: Deleting{{</hover>}} indicates the
Provider is attempting to delete the managed resource.

```yaml {copy-lines="none"}
```yaml {copy-lines="none",label="deleting"}
Conditions:
Type: Ready
Status: False
Reason: Deleting
```

<!-- vale off -->
### ReconcilePaused
<!-- vale on -->
`Reason: ReconcilePaused` indicates the managed resource has a [Pause](#paused)
annotation
#### Unavailable
{{<hover label="unavailable" line="4">}}Reason: Unavailable{{</hover>}}
indicates Crossplane expects the managed resource to be available, but the
Provider reports the resource is unhealthy.

```yaml {copy-lines="none"}
```yaml {copy-lines="none",label="unavailable"}
Conditions:
Type: Synced
Type: Ready
Status: False
Reason: ReconcilePaused
Reason: Unavailable
```

### Type: Synced

Condition `Type: Synced` indicates Crossplane has checked the status of the managed
resource with the Provider.
Comment on lines +907 to +908
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Got it.

When does a resource move from Ready/True to Synced/True? On the first reconcile after it's ready?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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)


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.
Comment on lines +910 to +913
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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,

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No, I meant the Provider component. How's this:

Condition Type: Synced indicates 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)


{{< hint "note" >}}
`Type: Synced` and `Status: True` only shows success between Crossplane and
the Provider. This status doesn't mean the Provider successfully changed the
external resource.
{{< /hint >}}

The condition `Type: Synced` and `Status: False` means Crossplane failed to
update or determine the current state of the managed resource.

<!-- vale off -->
### ReconcileError
#### ReconcileError
<!-- vale on -->
`Reason: ReconcileError` indicates Crossplane encountered an error while
{{<hover label="ReconcileError" line="4">}}Reason: ReconcileError{{</hover>}}
indicates Crossplane encountered an error while
reconciling the managed resource. The `Message:` value of the `Condition` helps
identify the Crossplane error.

```yaml {copy-lines="none"}
```yaml {copy-lines="none",label="ReconcileError"}
Conditions:
Type: Synced
Status: False
Reason: ReconcileError
```

<!-- vale off -->
### ReconcileSuccess
#### ReconcilePaused
<!-- vale on -->
`Reason: ReconcileSuccess` indicates the Provider created and is monitoring the
managed resource.
{{<hover label="ReconcilePaused" line="4">}}Reason: ReconcilePaused{{</hover>}}
indicates the managed resource has a [Pause](#paused) annotation

```yaml {copy-lines="none"}
```yaml {copy-lines="none",label="ReconcilePaused"}
Conditions:
Type: Synced
Status: True
Reason: ReconcileSuccess
Status: False
Reason: ReconcilePaused
```

### Unavailable
`Reason: Unavailable` indicates Crossplane expects the managed resource to be
available, but the Provider reports the resource is unhealthy.
<!-- vale off -->
#### ReconcileSuccess
<!-- vale on -->
{{<hover label="ReconcileSuccess" line="4">}}Reason: ReconcileSuccess{{</hover>}}
indicates the Provider created and is monitoring the managed resource.

```yaml {copy-lines="none"}
```yaml {copy-lines="none",label="ReconcileSuccess"}
Conditions:
Type: Ready
Status: False
Reason: Unavailable
Type: Synced
Status: True
Reason: ReconcileSuccess
```

### Unknown
`Reason: Unknown` indicates the Provider has an unexpected error with the
managed resource. The `conditions.message` provides more information on what
went wrong.
### Type: Unknown

```yaml {copy-lines="none"}
The `Type: Unknown` indicates that a Provider returned a Condition that
Crossplane doesn't understand.

A managed resource with `Type: Unknown` is an exception condition. Inspect the
`conditions.message` field or Provider logs for more information.

#### Unknown
{{<hover label="unknown" line="4">}}Reason: Unknown{{</hover>}} indicates the
Provider has an unexpected error with the managed resource. The
`conditions.message` provides more information on what went wrong.

```yaml {copy-lines="none",label="unknown"}
Conditions:
Type: Unknown
Status: False
Expand All @@ -951,10 +998,10 @@ an asynchronous operation.


##### Finished
The `Reason: Finished` indicates the asynchronous operation completed
successfully.
{{<hover label="finished" line="4">}}Reason: Finished{{</hover>}} indicates the
asynchronous operation completed successfully.

```yaml {copy-lines="none"}
```yaml {copy-lines="none",label="finished"}
Conditions:
Type: AsyncOperation
Status: True
Expand All @@ -964,9 +1011,10 @@ Conditions:

##### Ongoing

`Reason: Ongoing` indicates the managed resource operation is still in progress.
{{<hover label="ongoing" line="4">}}Reason: Ongoing{{</hover>}} indicates the
managed resource operation is still in progress.

```yaml {copy-lines="none"}
```yaml {copy-lines="none",label="ongoing"}
Conditions:
Type: AsyncOperation
Status: True
Expand All @@ -984,11 +1032,11 @@ operation status as either `Success` or a failure `Reason`.
##### ApplyFailure
<!-- vale on -->

`Reason: ApplyFailure` indicates the Provider failed to apply a setting to the
managed resource. The `conditions.message` provides more information on what
went wrong.
{{<hover label="applyfailure" line="4">}}Reason: ApplyFailure{{</hover>}}
indicates the Provider failed to apply a setting to the managed resource.
The `conditions.message` provides more information on what went wrong.

```yaml {copy-lines="none"}
```yaml {copy-lines="none",label="applyfailure"}
Conditions:
Type: LastAsyncOperation
Status: False
Expand All @@ -999,22 +1047,23 @@ Conditions:
##### DestroyFailure
<!-- vale on -->

`Reason: DestroyFailure` indicates the Provider failed to delete the managed
{{<hover label="destroyfailure" line="4">}}Reason: DestroyFailure{{</hover>}}
indicates the Provider failed to delete the managed
resource. The `conditions.message` provides more information on what
went wrong.

```yaml {copy-lines="none"}
```yaml {copy-lines="none",label="destroyfailure"}
Conditions:
Type: LastAsyncOperation
Status: False
Reason: DestroyFailure
```

##### Success
`Reason: Success` indicates the Provider successfully created the managed
resource asynchronously.
{{<hover label="success" line="4">}}Reason: Success{{</hover>}} indicates the
Provider successfully created the managed resource asynchronously.

```yaml {copy-lines="none"}
```yaml {copy-lines="none",label="success"}
Conditions:
Type: LastAsyncOperation
Status: True
Expand Down
Loading