From 40cd4dde7fb82e24e75d1b1b83e5a580f605522c Mon Sep 17 00:00:00 2001 From: "Per G. da Silva" Date: Mon, 12 Oct 2026 18:29:05 +0200 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=96=20align=20ClusterObjectSet=20conce?= =?UTF-8?q?pt=20doc=20with=20the=20single=20Ready=20condition?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The ClusterObjectSet now reports only a Ready condition; the Progressing and Succeeded conditions were removed and rollout completion is tracked by the status.completedAt timestamp. Update 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). - Replace "reports Succeeded" references in the transition/upgrade flows with "rolled out successfully (status.completedAt is set)". Co-Authored-By: Claude Opus 4.8 Signed-off-by: Per G. da Silva --- docs/draft/concepts/clusterobjectsets.md | 23 +++++------------------ 1 file changed, 5 insertions(+), 18 deletions(-) diff --git a/docs/draft/concepts/clusterobjectsets.md b/docs/draft/concepts/clusterobjectsets.md index 469b1883e6..c7fe565d0a 100644 --- a/docs/draft/concepts/clusterobjectsets.md +++ b/docs/draft/concepts/clusterobjectsets.md @@ -88,7 +88,7 @@ When transitioning from one revision to the next: 1. A new ClusterObjectSet is created with the next sequential revision number 2. Both old and new revisions remain `Active` during the transition 3. Objects transition ownership from the old revision to the new one -4. Once the new revision reports `Succeeded`, the old revision can be archived +4. Once the new revision has rolled out successfully, the old revision can be archived ### Archival @@ -196,19 +196,7 @@ For a detailed design discussion, see [Large Bundle Support](large-bundle-suppor ## Status conditions -ClusterObjectSets report three conditions that describe their current state: - -### Progressing - -Indicates whether the revision is actively rolling out. - -| Status | Reason | Meaning | -| --- | --- | --- | -| True | `RollingOut` | Actively making progress | -| True | `Retrying` | Encountered a retryable error | -| True | `Succeeded` | Reached the desired state | -| False | `Blocked` | Error requiring manual intervention | -| False | `Archived` | No longer actively reconciled | +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. ### Ready @@ -223,13 +211,12 @@ Indicates whether all objects in the revision have been successfully rolled out | False | `ValidationFailure` | A pre-apply check failed (an invalid revision/phase object or probe, preflight validation, a mutable referenced Secret, or changed referenced content); requires manual intervention | | False | `Archiving` | The revision is being archived; owned objects are still being torn down | | False | `Archived` | Objects torn down after archival | -| Unknown | `Migrated` | Migrated from existing release; probes not yet observed | 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, so on a first reconcile the condition may remain absent (`Unknown`). -### Succeeded +### Completion (`status.completedAt`) -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. +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. ## How operator-controller uses ClusterObjectSets @@ -252,7 +239,7 @@ When a ClusterExtension is upgraded to a new version: 1. A new ClusterObjectSet is created with `revision: N+1` 2. Both old and new revisions are `Active` during the transition 3. Objects transition ownership from the old revision to the new one -4. Once the new revision reports `Succeeded`, the old revision is archived +4. Once the new revision has rolled out successfully, the old revision is archived 5. Older archived revisions are garbage collected, keeping the last 5 for auditing ### Relationship with ClusterExtension