v1alpha2 KEP update: status conditions

[BlaineEXE]

Enhancement

Why is this needed?:

Latest Kubernetes API conventions highly recommend status conditions

• https://book.kubebuilder.io/reference/good-practices#why-you-should-adopt-status-conditions
• https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md#typical-status-properties

Particularly, boolean statuses like the planned ReadyToUse are strongly advised against, with conditions being the recommended replacement.

Similarly, advice is that error statuses like TimestampedError don't age well, and conditions are recommended as an alternative.

COSI should draft a plan for what conditions to have, and if they look good, the v1alpha2 KEP will be updated. IMO, it should be possible for the v1a2 KEP to be approved with the current API and to make these changes here, which will need to be more formally okayed for v1beta1.

Describe the solution you'd like in detail:

For the v1alpha2 implementation, COSI should draft a plan for using conditions instead of these 2 status patterns.

Describe alternatives you've considered:

Alternatives considered are the ReadyToUse bool and TimestampedError inherited as recommendations from the Volume Snapshot project.

Other alternative considerations haven't been considered as of Dec 2025.

Additional context:

This came up in API review here: #199

[BlaineEXE]

First Draft of Conditions Proposal

Let's keep the conditions to a minimum to help make implementation as easy as possible. We know that we need to represent ReadyToUse as a condition as well as TimestampedError.

1. Provisioned - positive polarity - True as long as any provision has been successful throughout the BucketClaim/Bucket/BucketAccess lifetime. We expect this to be monotonic, never reverting back to false. This helps identify when a backend resource has been successfully provisioned at least once and the last time the provision was successful. Replaces ReadyToUse as we have intended it to work. (Corner case: Deletion: IMO, there should be no need to transition this to False/Unknown when deleting a resource, but this is an option for us.)

2. ControllerFalied - negative polarity - True when the required Controller reconciliation of the resource has failed for any reason. Message will include the controller error. Applies to BucketClaim and BucketAccess initialization. Replaces TimestampedError and additionally clarifies the source component (Controller) of the error.

3. SidecarFailed - negative polarity - True when required Sidecar reconciliation of the resource has failed for any reason. Message will include the sidecar error. Applies to Bucket and BucketAccess provisioning. Replaces TimestampedError and additionally clarifies the source component (Sidecar) of the error.

This summarizes the core set of conditions we would need.

At this early stage, I think it is reasonable for us to not keep track of a Ready condition. It could be quite complex for a driver to make an accurate determination of whether a previously-provisioned Provisioned==True resource has become inaccessible to end users.

For example, if the backend isn't responding to the driver's administrative commands, does that mean that provisioned buckets are also unusable? Or is it merely an issue with the admin credentials or the backend's admin interface? Questions like this make it hard to understand when transition is appropriate and how to document that for driver implementers.

I think it is sufficient to report failures as planned above, and in the (hopefully rare) event that the driver is having issues that affect end users, the administrator can rely on driver documentation and the existing errors to troubleshoot and resolve issues.

If COSI users are experiencing gaps in the recommended API above, we can revisit this conversation and include design plans for how drivers can report when they belive end-users are negatively affected via gRPC return.

[BlaineEXE]

Alternative proposal for Ready. It might work like this:

• We keep the Provisioned condition as planned above to track the last successful provision
• When the status is first initialized, before the resource is reconciled, Ready is set to False
• When a reconcile is successful, Ready is set to True.
• When a reconcile is unsuccessful after Ready has become True, Ready is transitioned to Unknown.

This way, we can include a Ready condition as recommended, and we can acknowledge for end users when COSI is uncertain whether it is still ready or not. And we don't have to be too specific about knowing with certainty when Ready becomes False after initial provisioning.

[BlaineEXE]

Second draft after offline feedback from Joel:

We have 2 conditions:

• Provisioned - positive polarity - False initially. True as long as any provision has been successful throughout the BucketClaim/Bucket/BucketAccess lifetime. We expect this to be monotonic, never reverting back to false. This helps identify when a backend resource has been successfully provisioned at least once and the last time the provision was successful. Replaces ReadyToUse.
• Ready - positive polarity - False initially. True when a reconcile is successful. Transitions to Unknown when an RPC error is encountered. In the future, COSI can explore an API whereby drivers can report readiness from an end-user standpoint. For now Unknown is the most accurate value when there is an RPC error after initial provisioning is successful. When an error is encountered, the error message will be added to this condition, allowing this to be a replacement for TimestampedError.