Skip to content

Commit ea773ca

Browse files
perdasilvaPer G. da Silvaclaude
authored
📖 align ClusterObjectSet concept doc with the single Ready condition (#3021)
The ClusterObjectSet reports only a Ready condition; the Progressing and Succeeded conditions were removed and rollout completion is tracked by the status.completedAt timestamp. Align the concept doc accordingly: - Drop the stale Progressing and Succeeded condition sections. - Note that completion is recorded in status.completedAt (new "Completion" section). - Remove the Migrated Ready reason row (no such reason is emitted). - Add the ProgressDeadlineExceeded Ready reason row, which the controller emits and the API doc already documents but the concept table was missing. - Replace "reports Succeeded" references in the transition/upgrade flows with "rolled out successfully". Signed-off-by: Per G. da Silva <pegoncal@redhat.com> Co-authored-by: Per G. da Silva <pegoncal@redhat.com> Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
1 parent 9eba952 commit ea773ca

1 file changed

Lines changed: 6 additions & 18 deletions

File tree

‎docs/draft/concepts/clusterobjectsets.md‎

Lines changed: 6 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -88,7 +88,7 @@ When transitioning from one revision to the next:
8888
1. A new ClusterObjectSet is created with the next sequential revision number
8989
2. Both old and new revisions remain `Active` during the transition
9090
3. Objects transition ownership from the old revision to the new one
91-
4. Once the new revision reports `Succeeded`, the old revision can be archived
91+
4. Once the new revision has rolled out successfully, the old revision can be archived
9292

9393
### Archival
9494

@@ -196,19 +196,7 @@ For a detailed design discussion, see [Large Bundle Support](large-bundle-suppor
196196

197197
## Status conditions
198198

199-
ClusterObjectSets report three conditions that describe their current state:
200-
201-
### Progressing
202-
203-
Indicates whether the revision is actively rolling out.
204-
205-
| Status | Reason | Meaning |
206-
| --- | --- | --- |
207-
| True | `RollingOut` | Actively making progress |
208-
| True | `Retrying` | Encountered a retryable error |
209-
| True | `Succeeded` | Reached the desired state |
210-
| False | `Blocked` | Error requiring manual intervention |
211-
| False | `Archived` | No longer actively reconciled |
199+
ClusterObjectSets report a single `Ready` condition describing their current state. Rollout *completion* is recorded separately as a timestamp in `status.completedAt`, not as a condition.
212200

213201
### Ready
214202

@@ -222,16 +210,16 @@ Indicates whether all objects in the revision have been successfully rolled out
222210
| False | `ObjectCollision` | One or more objects are controlled by another owner, or are unowned and collision protection prevents adoption |
223211
| False | `PreconditionsNotMet` | A precondition for applying the revision is not yet satisfied (a referenced Secret is mutable or has invalid or changed content, or a preflight dry-run was rejected, e.g. an immutable field, a conflicting object, or RBAC/dependency CRDs not yet propagated); the revision keeps retrying and recovers once the precondition is met |
224212
| False | `InvalidSpecification` | The revision spec is invalid (a malformed revision/phase object or progression probe); requires a spec change |
213+
| False | `ProgressDeadlineExceeded` | The revision did not roll out within `spec.progressDeadlineMinutes` |
225214
| False | `Archiving` | The revision is being archived; owned objects are still being torn down |
226215
| False | `Archived` | Objects torn down after archival |
227216
| Unknown | `Pending` | The revision has not yet been evaluated (initial state) |
228-
| Unknown | `Migrated` | Migrated from existing release; probes not yet observed |
229217

230218
On a revision's first reconciliation the `Ready` condition is initialized to `Unknown`/`Pending`, so it is always present. A transient internal error (e.g. an API read failure) leaves the `Ready` condition unchanged and is retried with backoff; it is not reported as a distinct reason (while the revision is still `Pending`, it stays `Unknown`/`Pending`).
231219

232-
### Succeeded
220+
### Completion (`status.completedAt`)
233221

234-
A terminal condition set once the rollout completes. It persists even if the revision later becomes unavailable, marking that this version was successfully deployed at least once.
222+
The first time a revision becomes ready, the controller stamps `status.completedAt` with the current time. This timestamp is set once and never changes, marking that this revision successfully rolled out at least once — it persists even if the revision later becomes not ready. The ClusterExtension controller uses it to determine the installed revision.
235223

236224
## How operator-controller uses ClusterObjectSets
237225

@@ -254,7 +242,7 @@ When a ClusterExtension is upgraded to a new version:
254242
1. A new ClusterObjectSet is created with `revision: N+1`
255243
2. Both old and new revisions are `Active` during the transition
256244
3. Objects transition ownership from the old revision to the new one
257-
4. Once the new revision reports `Succeeded`, the old revision is archived
245+
4. Once the new revision has rolled out successfully, the old revision is archived
258246
5. Older archived revisions are garbage collected, keeping the last 5 for auditing
259247

260248
### Relationship with ClusterExtension

0 commit comments

Comments
 (0)