Skip to content

✨ Gate ownerless ClusterObjectSet adoption on object-controller label #3099

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

Merged
openshift-merge-bot merged 1 commit into from
Nov 6, 2026
Merged

✨ Gate ownerless ClusterObjectSet adoption on object-controller label #3099

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
23 changes: 20 additions & 3 deletions api/v1/clusterobjectdeployment_types.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,7 @@ const (
ClusterObjectDeploymentReasonRevisionObjectCollision = "RevisionObjectCollision"
ClusterObjectDeploymentReasonRevisionInvalidSpecification = "RevisionInvalidSpecification"
ClusterObjectDeploymentReasonOwnerConflict = "OwnerConflict"
ClusterObjectDeploymentReasonUnmanagedRevision = "UnmanagedRevision"

@fao89 fao89 Nov 3, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

[P3] Document the adoption gate and UnmanagedRevision condition

The public ClusterObjectDeploymentStatus.Conditions comment below still says that revisions without a controller owner are adopted before status is calculated, without mentioning the new label requirement. Its Progressing reason documentation also omits UnmanagedRevision. Please update those API comments to describe the adoption condition, blocked behavior, and recovery, and regenerate the CRD/reference documentation as appropriate so users can discover the new behavior.

@perdasilva perdasilva Nov 4, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Updated the ClusterObjectDeploymentStatus.Conditions doc comment: the Progressing paragraph now documents the UnmanagedRevision reason (blocked behavior + recovery), and the Available paragraph now describes the adoption gate — a revision is only adopted when it is already controlled by this deployment or carries the apps.kubernetes.io/managed-by=object-controller label. Regenerated the CRD, manifests, and API reference docs. (529f9aa)


// Available condition reasons.
ClusterObjectDeploymentReasonAvailable = "Available"
Expand Down Expand Up @@ -157,6 +158,15 @@ type ClusterObjectDeploymentStatus struct {
// non-deleting revision in the deployment's group is controlled by another
// controller. No new revision is created while the conflict persists, even if
// an owned revision has completed or exceeded its progress deadline.
// Progressing is False with reason UnmanagedRevision when the highest active,
// non-deleting revision in the deployment's group has no controller owner and is
// not labeled apps.kubernetes.io/managed-by=object-controller, the proof that the
// object-controller created it; such a revision is not adopted and no higher
// revision is created while it persists. Recover by removing the revision or by
// restoring the managed-by label on it. A revision that instead still references an
// older UID of this deployment (for example after a restore) is left to garbage
// collection rather than adopted, and no higher revision is created until GC removes
// it; this resolves without user action and is not reported as a distinct condition.
//
// While a rollout is incomplete, Progressing also reflects why the latest (head
// active) ClusterObjectSet revision is not yet Ready. It is True with reason
Expand All @@ -173,9 +183,16 @@ type ClusterObjectDeploymentStatus struct {
// owned ClusterObjectSet revision is Ready, so the deployment remains available across
// rollouts while a previous revision is still Ready. It is False with reason
// Unavailable when owned active revisions exist but none are Ready yet, or with reason
// NoActiveRevision when no owned active revision exists. Revisions without a
// controller owner, or controlled by a same-named deployment with an older UID,
// are adopted before status is calculated. Foreign-owned revisions are excluded.
// NoActiveRevision when no owned active revision exists. Only an ownerless revision
// is adopted before status is calculated, and only when it carries the
// apps.kubernetes.io/managed-by=object-controller label that proves the
// object-controller created it; an ownerless revision missing that label is left
// untouched and, when it leads the group, blocks the rollout and is reported on the
// Progressing condition with reason UnmanagedRevision. A revision that still carries a
// controller owner reference is never adopted: foreign-owned revisions are excluded,
// and a stale reference to an older UID of this deployment (for example after a
// restore) is left to garbage collection rather than rewriting the reference to race
// it.
// +optional
// +listType=map
// +listMapKey=type
Expand Down
22 changes: 19 additions & 3 deletions applyconfigurations/api/v1/clusterobjectdeploymentstatus.go
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion docs/api-reference/olmv1-api-reference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -458,7 +458,7 @@ _Appears in:_

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `conditions` _[Condition](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#condition-v1-meta) array_ | conditions describes rollout progress and availability for the observed generation.<br />Progressing is True with reason NewClusterObjectSetProgressing while the desired<br />rollout is incomplete, or False with reason NewClusterObjectSetProgressed after<br />completion. Completion remains recorded even if the completed revision later<br />becomes unhealthy. Progressing is False with reason ProgressDeadlineExceeded when<br />the latest revision does not roll out within spec.template.spec.progressDeadlineMinutes.<br />Progressing is False with reason InvalidSpecification when spec.template.metadata<br />contains labels or annotations that are not valid for the resulting<br />ClusterObjectSet; no new revision is created until the metadata is corrected.<br />Progressing is False with reason OwnerConflict when the highest active,<br />non-deleting revision in the deployment's group is controlled by another<br />controller. No new revision is created while the conflict persists, even if<br />an owned revision has completed or exceeded its progress deadline.<br />While a rollout is incomplete, Progressing also reflects why the latest (head<br />active) ClusterObjectSet revision is not yet Ready. It is True with reason<br />RevisionPreconditionsNotMet when the revision's preconditions are not yet met<br />(for example RBAC or a dependency CRD that has not propagated); the controller<br />keeps retrying. It is False with reason RevisionObjectCollision when the<br />revision's objects are owned by another controller or already exist, which the<br />user must resolve. It is False with reason RevisionInvalidSpecification when the<br />revision's own objects are invalid; this is distinct from InvalidSpecification<br />above, which refers to the deployment's spec.template.metadata. Inspect the<br />named ClusterObjectSet revision for the specific cause.<br />Available is True with reason Available when at least one active (non-archived)<br />owned ClusterObjectSet revision is Ready, so the deployment remains available across<br />rollouts while a previous revision is still Ready. It is False with reason<br />Unavailable when owned active revisions exist but none are Ready yet, or with reason<br />NoActiveRevision when no owned active revision exists. Revisions without a<br />controller owner, or controlled by a same-named deployment with an older UID,<br />are adopted before status is calculated. Foreign-owned revisions are excluded. | | Optional: \{\} <br /> |
| `conditions` _[Condition](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#condition-v1-meta) array_ | conditions describes rollout progress and availability for the observed generation.<br />Progressing is True with reason NewClusterObjectSetProgressing while the desired<br />rollout is incomplete, or False with reason NewClusterObjectSetProgressed after<br />completion. Completion remains recorded even if the completed revision later<br />becomes unhealthy. Progressing is False with reason ProgressDeadlineExceeded when<br />the latest revision does not roll out within spec.template.spec.progressDeadlineMinutes.<br />Progressing is False with reason InvalidSpecification when spec.template.metadata<br />contains labels or annotations that are not valid for the resulting<br />ClusterObjectSet; no new revision is created until the metadata is corrected.<br />Progressing is False with reason OwnerConflict when the highest active,<br />non-deleting revision in the deployment's group is controlled by another<br />controller. No new revision is created while the conflict persists, even if<br />an owned revision has completed or exceeded its progress deadline.<br />Progressing is False with reason UnmanagedRevision when the highest active,<br />non-deleting revision in the deployment's group has no controller owner and is<br />not labeled apps.kubernetes.io/managed-by=object-controller, the proof that the<br />object-controller created it; such a revision is not adopted and no higher<br />revision is created while it persists. Recover by removing the revision or by<br />restoring the managed-by label on it. A revision that instead still references an<br />older UID of this deployment (for example after a restore) is left to garbage<br />collection rather than adopted, and no higher revision is created until GC removes<br />it; this resolves without user action and is not reported as a distinct condition.<br />While a rollout is incomplete, Progressing also reflects why the latest (head<br />active) ClusterObjectSet revision is not yet Ready. It is True with reason<br />RevisionPreconditionsNotMet when the revision's preconditions are not yet met<br />(for example RBAC or a dependency CRD that has not propagated); the controller<br />keeps retrying. It is False with reason RevisionObjectCollision when the<br />revision's objects are owned by another controller or already exist, which the<br />user must resolve. It is False with reason RevisionInvalidSpecification when the<br />revision's own objects are invalid; this is distinct from InvalidSpecification<br />above, which refers to the deployment's spec.template.metadata. Inspect the<br />named ClusterObjectSet revision for the specific cause.<br />Available is True with reason Available when at least one active (non-archived)<br />owned ClusterObjectSet revision is Ready, so the deployment remains available across<br />rollouts while a previous revision is still Ready. It is False with reason<br />Unavailable when owned active revisions exist but none are Ready yet, or with reason<br />NoActiveRevision when no owned active revision exists. Only an ownerless revision<br />is adopted before status is calculated, and only when it carries the<br />apps.kubernetes.io/managed-by=object-controller label that proves the<br />object-controller created it; an ownerless revision missing that label is left<br />untouched and, when it leads the group, blocks the rollout and is reported on the<br />Progressing condition with reason UnmanagedRevision. A revision that still carries a<br />controller owner reference is never adopted: foreign-owned revisions are excluded,<br />and a stale reference to an older UID of this deployment (for example after a<br />restore) is left to garbage collection rather than rewriting the reference to race<br />it. | | Optional: \{\} <br /> |


#### ClusterObjectDeploymentTemplate
Expand Down
22 changes: 19 additions & 3 deletions ...object-controller/crd/experimental/olm.operatorframework.io_clusterobjectdeployments.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -555,6 +555,15 @@ spec:
non-deleting revision in the deployment's group is controlled by another
controller. No new revision is created while the conflict persists, even if
an owned revision has completed or exceeded its progress deadline.
Progressing is False with reason UnmanagedRevision when the highest active,
non-deleting revision in the deployment's group has no controller owner and is
not labeled apps.kubernetes.io/managed-by=object-controller, the proof that the
object-controller created it; such a revision is not adopted and no higher
revision is created while it persists. Recover by removing the revision or by
restoring the managed-by label on it. A revision that instead still references an
older UID of this deployment (for example after a restore) is left to garbage
collection rather than adopted, and no higher revision is created until GC removes
it; this resolves without user action and is not reported as a distinct condition.

While a rollout is incomplete, Progressing also reflects why the latest (head
active) ClusterObjectSet revision is not yet Ready. It is True with reason
Expand All @@ -571,9 +580,16 @@ spec:
owned ClusterObjectSet revision is Ready, so the deployment remains available across
rollouts while a previous revision is still Ready. It is False with reason
Unavailable when owned active revisions exist but none are Ready yet, or with reason
NoActiveRevision when no owned active revision exists. Revisions without a
controller owner, or controlled by a same-named deployment with an older UID,
are adopted before status is calculated. Foreign-owned revisions are excluded.
NoActiveRevision when no owned active revision exists. Only an ownerless revision
is adopted before status is calculated, and only when it carries the
apps.kubernetes.io/managed-by=object-controller label that proves the
object-controller created it; an ownerless revision missing that label is left
untouched and, when it leads the group, blocks the rollout and is reported on the
Progressing condition with reason UnmanagedRevision. A revision that still carries a
controller owner reference is never adopted: foreign-owned revisions are excluded,
and a stale reference to an older UID of this deployment (for example after a
restore) is left to garbage collection rather than rewriting the reference to race
it.
items:
description: Condition contains details for one aspect of the current
state of this API Resource.
Expand Down
Loading
Loading