From d32da544075dbe840c3576f4d2d2dcc142ab11ef 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 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". Co-Authored-By: Claude Opus 4.8 Signed-off-by: Per G. da Silva --- docs/draft/concepts/clusterobjectsets.md | 24 ++++++------------------ 1 file changed, 6 insertions(+), 18 deletions(-) diff --git a/docs/draft/concepts/clusterobjectsets.md b/docs/draft/concepts/clusterobjectsets.md index 96c9a67147..bded79c3ca 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 @@ -222,16 +210,16 @@ Indicates whether all objects in the revision have been successfully rolled out | False | `ObjectCollision` | One or more objects are controlled by another owner, or are unowned and collision protection prevents adoption | | 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 | | False | `InvalidSpecification` | The revision spec is invalid (a malformed revision/phase object or progression probe); requires a spec change | +| False | `ProgressDeadlineExceeded` | The revision did not roll out within `spec.progressDeadlineMinutes` | | False | `Archiving` | The revision is being archived; owned objects are still being torn down | | False | `Archived` | Objects torn down after archival | | Unknown | `Pending` | The revision has not yet been evaluated (initial state) | -| Unknown | `Migrated` | Migrated from existing release; probes not yet observed | 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`). -### 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 @@ -254,7 +242,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