🐛 OPRUN-4791: Enforce revision-level progression deadlines in COD

api/v1/clusterobjectdeployment_types.go

@@ -83,12 +83,13 @@ type ClusterObjectDeploymentTemplateSpec struct {
 	// +listMapKey=name
 	Phases []ClusterObjectSetPhase `json:"phases"` //nolint:kubeapilinter // These are ordered groups of objects, not an enum describing lifecycle state.
 
-	// progressDeadlineMinutes is an optional field that defines the maximum period
-	// of time in minutes after which an installation should be considered failed and
-	// require manual intervention. This functionality is disabled when no value
-	// is provided. The minimum period is 10 minutes, and the maximum is 720 minutes (12 hours).
-	//
-	// The value is passed through to each ClusterObjectSet revision created from this template.
+	// progressDeadlineMinutes is the maximum number of minutes a revision may take
+	// to roll out, measured from the ClusterObjectSet's creation timestamp. Time
+	// spent waiting for the ClusterObjectSet to be created is not counted. The
+	// deadline covers all phases together; completing a phase does not reset it.
+	// Once a revision has completed, the deadline no longer applies, even if it
+	// later becomes unhealthy. When omitted, no deadline is enforced. The minimum
+	// period is 10 minutes, and the maximum is 720 minutes (12 hours).
 	//
 	// +kubebuilder:validation:Minimum:=10
 	// +kubebuilder:validation:Maximum:=720
@@ -118,7 +119,7 @@ type ClusterObjectDeploymentStatus struct {
 	// rollout is incomplete, or False with reason NewClusterObjectSetProgressed after
 	// completion. Completion remains recorded even if the completed revision later
 	// becomes unhealthy. Progressing is False with reason ProgressDeadlineExceeded when
-	// the latest revision does not roll out within its spec.progressDeadlineMinutes.
+	// the latest revision does not roll out within spec.template.spec.progressDeadlineMinutes.
 	//
 	// Available is True with reason Available when at least one active (non-archived)
 	// ClusterObjectSet revision is Ready, so the deployment remains available across

docs/api-reference/olmv1-api-reference.md

@@ -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 its spec.progressDeadlineMinutes.<br />Available is True with reason Available when at least one active (non-archived)<br />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 active revisions exist but none are Ready yet, or with reason<br />NoActiveRevision when no active revision exists. |  | 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 />Available is True with reason Available when at least one active (non-archived)<br />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 active revisions exist but none are Ready yet, or with reason<br />NoActiveRevision when no active revision exists. |  | Optional: \{\} <br /> |
 
 
 #### ClusterObjectDeploymentTemplate
@@ -491,7 +491,7 @@ _Appears in:_
 | Field | Description | Default | Validation |
 | --- | --- | --- | --- |
 | `phases` _[ClusterObjectSetPhase](#clusterobjectsetphase) array_ | phases is an ordered list of 1 to 20 uniquely named phases. Each phase contains<br />at most 50 objects using the existing inline object or immutable Secret reference<br />representation. Phase, object, and probe order participate in template identity. |  | MaxItems: 20 <br />MinItems: 1 <br />Required: \{\} <br /> |
-| `progressDeadlineMinutes` _integer_ | progressDeadlineMinutes is an optional field that defines the maximum period<br />of time in minutes after which an installation should be considered failed and<br />require manual intervention. This functionality is disabled when no value<br />is provided. The minimum period is 10 minutes, and the maximum is 720 minutes (12 hours).<br />The value is passed through to each ClusterObjectSet revision created from this template. |  | Maximum: 720 <br />Minimum: 10 <br />Optional: \{\} <br /> |
+| `progressDeadlineMinutes` _integer_ | progressDeadlineMinutes is the maximum number of minutes a revision may take<br />to roll out, measured from the ClusterObjectSet's creation timestamp. Time<br />spent waiting for the ClusterObjectSet to be created is not counted. The<br />deadline covers all phases together; completing a phase does not reset it.<br />Once a revision has completed, the deadline no longer applies, even if it<br />later becomes unhealthy. When omitted, no deadline is enforced. The minimum<br />period is 10 minutes, and the maximum is 720 minutes (12 hours). |  | Maximum: 720 <br />Minimum: 10 <br />Optional: \{\} <br /> |
 | `progressionProbes` _[ProgressionProbe](#progressionprobe) array_ | progressionProbes supplies custom readiness probes for objects in every phase.<br />The existing ClusterObjectSet selector and assertion semantics apply. |  | MaxItems: 20 <br />MinItems: 1 <br />Optional: \{\} <br /> |
 | `collisionProtection` _[CollisionProtection](#collisionprotection)_ | collisionProtection is the required default collision protection strategy for objects in the revision.<br />Objects and phases may override it. |  | Enum: [Prevent IfNoController None] <br />Required: \{\} <br /> |
 

docs/draft/concepts/clusterobjectsets.md

@@ -233,6 +233,37 @@ Indicates whether all objects in the revision have been successfully rolled out
 
 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`).
 
+### Progress deadline
+
+`spec.progressDeadlineMinutes` sets one time budget for the entire
+ClusterObjectSet (COS) revision, measured from its creation timestamp until its
+first successful rollout, recorded in `status.completedAt`. Completing a phase
+does not reset the timer.
+
+For a ClusterObjectDeployment (COD), this is the time allowed for the deployment to
+progress to its desired new revision. Configure it through
+`spec.template.spec.progressDeadlineMinutes`. The COD enforces this budget without
+setting `spec.progressDeadlineMinutes` on the ClusterObjectSets it creates. Time
+spent waiting for the ClusterObjectSet to be created is not counted. Each new
+revision receives its own budget.
+
+If the desired revision is still incomplete when that budget expires, the COD
+reports `Progressing=False` with reason `ProgressDeadlineExceeded`. A five-phase
+revision with a ten-minute deadline has ten minutes total, even if four phases
+have completed. The COD schedules a deadline check even if the COS emits no
+further events.
+
+The COS's `Ready` condition continues to report readiness failures, such as
+`ObjectsNotReady`, `PreconditionsNotMet`, or `InvalidSpecification`. The COD checks
+elapsed time independently of the COS's readiness condition.
+
+Omitting the field disables the deadline. Reconciliation continues after a
+timeout, so a revision can still complete later. Once `status.completedAt` is
+recorded, the COD reports `Progressing=False` with reason
+`NewClusterObjectSetProgressed`. Later health regressions do not restart deadline
+timing. The COD can remain `Available=True` if an older active revision is still
+ready.
+
 ### Completion (`status.completedAt`)
 
 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.

helm/olmv1/base/object-controller/crd/experimental/olm.operatorframework.io_clusterobjectdeployments.yaml

@@ -231,12 +231,13 @@ spec:
                         x-kubernetes-list-type: map
                       progressDeadlineMinutes:
                         description: |-
-                          progressDeadlineMinutes is an optional field that defines the maximum period
-                          of time in minutes after which an installation should be considered failed and
-                          require manual intervention. This functionality is disabled when no value
-                          is provided. The minimum period is 10 minutes, and the maximum is 720 minutes (12 hours).
-
-                          The value is passed through to each ClusterObjectSet revision created from this template.
+                          progressDeadlineMinutes is the maximum number of minutes a revision may take
+                          to roll out, measured from the ClusterObjectSet's creation timestamp. Time
+                          spent waiting for the ClusterObjectSet to be created is not counted. The
+                          deadline covers all phases together; completing a phase does not reset it.
+                          Once a revision has completed, the deadline no longer applies, even if it
+                          later becomes unhealthy. When omitted, no deadline is enforced. The minimum
+                          period is 10 minutes, and the maximum is 720 minutes (12 hours).
                         format: int32
                         maximum: 720
                         minimum: 10
@@ -519,7 +520,7 @@ spec:
                   rollout is incomplete, or False with reason NewClusterObjectSetProgressed after
                   completion. Completion remains recorded even if the completed revision later
                   becomes unhealthy. Progressing is False with reason ProgressDeadlineExceeded when
-                  the latest revision does not roll out within its spec.progressDeadlineMinutes.
+                  the latest revision does not roll out within spec.template.spec.progressDeadlineMinutes.
 
                   Available is True with reason Available when at least one active (non-archived)
                   ClusterObjectSet revision is Ready, so the deployment remains available across