Support ClusterExtension progress deadline detection

Adds optional `.spec.progressDeadlineMinutes` field to `ClusterExtension`
and `ClusterExtensionRevision` that defines
the maximum time an extension version can take to roll out before being marked as failed.

When configured, if a `ClusterExtensionRevision` fails to roll out within
the specified duration, the `Progressing` condition is set to `False` with reason
`ProgressDeadlineExceeded`. This signals that manual intervention is required
and stops automatic retry attempts.

Added unit and e2e test asserting the added behavior.

Author: pedjak

api/v1/clusterextension_types.go

@@ -107,6 +107,17 @@ type ClusterExtensionSpec struct {
 	//
 	// +optional
 	Config *ClusterExtensionConfig `json:"config,omitempty"`
+
+	// 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).
+	//
+	// +kubebuilder:validation:Minimum:=10
+	// +kubebuilder:validation:Maximum:=720
+	// +optional
+	// <opcon:experimental>
+	ProgressDeadlineMinutes int32 `json:"progressDeadlineMinutes,omitempty"`
 }
 
 const SourceTypeCatalog = "Catalog"

api/v1/clusterextensionrevision_types.go

@@ -87,6 +87,17 @@ type ClusterExtensionRevisionSpec struct {
 	// +listMapKey=name
 	// +optional
 	Phases []ClusterExtensionRevisionPhase `json:"phases,omitempty"`
+
+	// 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).
+	//
+	// +kubebuilder:validation:Minimum:=10
+	// +kubebuilder:validation:Maximum:=720
+	// +optional
+	// <opcon:experimental>
+	ProgressDeadlineMinutes int32 `json:"progressDeadlineMinutes,omitempty"`
 }
 
 // ClusterExtensionRevisionLifecycleState specifies the lifecycle state of the ClusterExtensionRevision.

api/v1/clusterextensionrevision_types_test.go

@@ -140,3 +140,56 @@ func TestClusterExtensionRevisionValidity(t *testing.T) {
 		})
 	}
 }
+
+func TestClusterExtensionProgressDeadlineValidity(t *testing.T) {
+	c := newClient(t)
+	ctx := context.Background()
+	i := 0
+	for name, tc := range map[string]struct {
+		spec  ClusterExtensionRevisionSpec
+		valid bool
+	}{
+		"invalid progress deadline < 10": {
+			spec: ClusterExtensionRevisionSpec{
+				ProgressDeadlineMinutes: 9,
+			},
+			valid: false,
+		},
+		"valid progress deadline = 10": {
+			spec: ClusterExtensionRevisionSpec{
+				ProgressDeadlineMinutes: 10,
+			},
+			valid: true,
+		},
+		"valid progress deadline <= 720": {
+			spec: ClusterExtensionRevisionSpec{
+				ProgressDeadlineMinutes: 720,
+			},
+			valid: true,
+		},
+		"invalid progress deadline > 720": {
+			spec: ClusterExtensionRevisionSpec{
+				ProgressDeadlineMinutes: 721,
+			},
+			valid: false,
+		},
+	} {
+		t.Run(name, func(t *testing.T) {
+			cer := &ClusterExtensionRevision{
+				ObjectMeta: metav1.ObjectMeta{
+					Name: fmt.Sprintf("bla%d", i),
+				},
+				Spec: tc.spec,
+			}
+			cer.Spec.Revision = 1
+			i = i + 1
+			err := c.Create(ctx, cer)
+			if tc.valid && err != nil {
+				t.Fatal("expected create to succeed, but got:", err)
+			}
+			if !tc.valid && !errors.IsInvalid(err) {
+				t.Fatal("expected create to fail due to invalid payload, but got:", err)
+			}
+		})
+	}
+}

api/v1/common_types.go

@@ -32,6 +32,7 @@ const (
 	ReasonDeprecated = "Deprecated"
 
 	// Common reasons
-	ReasonSucceeded = "Succeeded"
-	ReasonFailed    = "Failed"
+	ReasonSucceeded                = "Succeeded"
+	ReasonFailed                   = "Failed"
+	ReasonProgressDeadlineExceeded = "ProgressDeadlineExceeded"
 )

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

@@ -344,6 +344,7 @@ _Appears in:_
 | `source` _[SourceConfig](#sourceconfig)_ | source is required and selects the installation source of content for this ClusterExtension.<br />Set the sourceType field to perform the selection.<br />Catalog is currently the only implemented sourceType.<br />Setting sourceType to "Catalog" requires the catalog field to also be defined.<br />Below is a minimal example of a source definition (in yaml):<br />source:<br />  sourceType: Catalog<br />  catalog:<br />    packageName: example-package |  | Required: \{\} <br /> |
 | `install` _[ClusterExtensionInstallConfig](#clusterextensioninstallconfig)_ | install is optional and configures installation options for the ClusterExtension,<br />such as the pre-flight check configuration. |  |  |
 | `config` _[ClusterExtensionConfig](#clusterextensionconfig)_ | config is optional and specifies bundle-specific configuration.<br />Configuration is bundle-specific and a bundle may provide a configuration schema.<br />When not specified, the default configuration of the resolved bundle is used.<br />config is validated against a configuration schema provided by the resolved bundle. If the bundle does not provide<br />a configuration schema the bundle is deemed to not be configurable. More information on how<br />to configure bundles can be found in the OLM documentation associated with your current OLM version. |  |  |
+| `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 /><opcon:experimental> |  | Maximum: 720 <br />Minimum: 10 <br /> |
 
 
 #### ClusterExtensionStatus

helm/olmv1/base/operator-controller/crd/experimental/olm.operatorframework.io_clusterextensionrevisions.yaml

@@ -166,6 +166,16 @@ spec:
                 x-kubernetes-validations:
                 - message: phases is immutable
                   rule: self == oldSelf || oldSelf.size() == 0
+              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).
+                format: int32
+                maximum: 720
+                minimum: 10
+                type: integer
               revision:
                 description: |-
                   revision is a required, immutable sequence number representing a specific revision

helm/olmv1/base/operator-controller/crd/experimental/olm.operatorframework.io_clusterextensions.yaml

@@ -165,6 +165,16 @@ spec:
                   rule: self == oldSelf
                 - message: namespace must be a valid DNS1123 label
                   rule: self.matches("^[a-z0-9]([-a-z0-9]*[a-z0-9])?$")
+              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).
+                format: int32
+                maximum: 720
+                minimum: 10
+                type: integer
               serviceAccount:
                 description: |-
                   serviceAccount specifies a ServiceAccount used to perform all interactions with the cluster

internal/operator-controller/applier/boxcutter.go

@@ -191,7 +191,7 @@ func (r *SimpleRevisionGenerator) buildClusterExtensionRevision(
 	annotations[labels.ServiceAccountNameKey] = ext.Spec.ServiceAccount.Name
 	annotations[labels.ServiceAccountNamespaceKey] = ext.Spec.Namespace
 
-	return &ocv1.ClusterExtensionRevision{
+	cer := &ocv1.ClusterExtensionRevision{
 		ObjectMeta: metav1.ObjectMeta{
 			Annotations: annotations,
 			Labels: map[string]string{
@@ -206,6 +206,10 @@ func (r *SimpleRevisionGenerator) buildClusterExtensionRevision(
 			Phases:         PhaseSort(objects),
 		},
 	}
+	if p := ext.Spec.ProgressDeadlineMinutes; p > 0 {
+		cer.Spec.ProgressDeadlineMinutes = p
+	}
+	return cer
 }
 
 // BoxcutterStorageMigrator migrates ClusterExtensions from Helm-based storage to

internal/operator-controller/applier/boxcutter_test.go

@@ -22,6 +22,7 @@ import (
 	"k8s.io/apimachinery/pkg/runtime"
 	"k8s.io/apimachinery/pkg/util/validation/field"
 	k8scheme "k8s.io/client-go/kubernetes/scheme"
+	"k8s.io/utils/ptr"
 	"sigs.k8s.io/controller-runtime/pkg/client"
 	"sigs.k8s.io/controller-runtime/pkg/client/fake"
 	"sigs.k8s.io/controller-runtime/pkg/client/interceptor"
@@ -327,6 +328,65 @@ func Test_SimpleRevisionGenerator_AppliesObjectLabelsAndRevisionAnnotations(t *t
 	require.Equal(t, revAnnotations, rev.Annotations)
 }
 
+func Test_SimpleRevisionGenerator_PropagatesProgressDeadlineMinutes(t *testing.T) {
+	r := &FakeManifestProvider{
+		GetFn: func(b fs.FS, e *ocv1.ClusterExtension) ([]client.Object, error) {
+			return []client.Object{}, nil
+		},
+	}
+
+	b := applier.SimpleRevisionGenerator{
+		Scheme:           k8scheme.Scheme,
+		ManifestProvider: r,
+	}
+
+	type args struct {
+		progressDeadlineMinutes *int32
+	}
+	type want struct {
+		progressDeadlineMinutes int32
+	}
+	type testCase struct {
+		args args
+		want want
+	}
+	for name, tc := range map[string]testCase{
+		"propagates when set": {
+			args: args{
+				progressDeadlineMinutes: ptr.To(int32(10)),
+			},
+			want: want{
+				progressDeadlineMinutes: 10,
+			},
+		},
+		"do not propagate when unset": {
+			want: want{
+				progressDeadlineMinutes: 0,
+			},
+		},
+	} {
+		ext := &ocv1.ClusterExtension{
+			ObjectMeta: metav1.ObjectMeta{
+				Name: "test-extension",
+			},
+			Spec: ocv1.ClusterExtensionSpec{
+				Namespace:      "test-namespace",
+				ServiceAccount: ocv1.ServiceAccountReference{Name: "test-sa"},
+			},
+		}
+		empty := map[string]string{}
+		t.Run(name, func(t *testing.T) {
+			if pd := tc.args.progressDeadlineMinutes; pd != nil {
+				ext.Spec.ProgressDeadlineMinutes = *pd
+			}
+
+			rev, err := b.GenerateRevision(t.Context(), fstest.MapFS{}, ext, empty, empty)
+			require.NoError(t, err)
+			require.Equal(t, tc.want.progressDeadlineMinutes, rev.Spec.ProgressDeadlineMinutes)
+		})
+	}
+}
+
 func Test_SimpleRevisionGenerator_Failure(t *testing.T) {
 	r := &FakeManifestProvider{
 		GetFn: func(b fs.FS, e *ocv1.ClusterExtension) ([]client.Object, error) {

internal/operator-controller/conditionsets/conditionsets.go

@@ -41,4 +41,5 @@ var ConditionReasons = []string{
 	ocv1.ReasonRetrying,
 	ocv1.ReasonAbsent,
 	ocv1.ReasonRollingOut,
+	ocv1.ReasonProgressDeadlineExceeded,
 }