NO-ISSUE: Synchronize From Upstream Repositories

.claude/commands/list-e2e-steps.md

@@ -0,0 +1,100 @@
+---
+description: List all available Godog e2e step definitions with categories, parameters, and descriptions
+---
+
+# List E2E Steps
+
+Generate a categorized reference of all Godog (Cucumber BDD) step definitions available for writing e2e feature files.
+
+## Instructions for Claude AI
+
+When this command is invoked, you MUST:
+
+**CRITICAL:** The final output MUST be a comprehensive categorized reference displayed directly in the conversation. Do NOT just create files - output the full reference as your response.
+
+1. **Get the authoritative list of registered step patterns**
+
+   Run:
+   ```bash
+   go test ./test/e2e/features_test.go -d || true 2>&1
+   ```
+   The `-d` flag prints all registered step definitions without running tests. Parse each step regex pattern from the output.
+
+2. **Read the step registration and handler implementations**
+
+   Read `test/e2e/steps/steps.go` and locate the `RegisterSteps()` function. For each regex pattern from step 1, find its corresponding `sc.Step()` call and the handler function it references.
+
+   Then read each handler function's signature to determine:
+   - What parameters it accepts (string, int, `*godog.DocString`, etc.)
+   - Whether it expects a DocString (multi-line YAML block in the feature file)
+
+   Consult the handler documentation to understand what the step does. If the documentation is missing,
+   check what the handler actually does (kubectl commands, polling, assertions, etc.)
+
+3. **Output a categorized reference**
+
+   Organize all steps into the following categories and format. Use the information gathered from the handler implementations to write accurate descriptions.
+
+### Output Format
+
+Start with a variable substitution reference, then list steps by category.
+
+---
+
+#### Variable Substitution
+
+These variables are automatically replaced in DocString content and some string parameters:
+
+| Variable | Replaced With | Example                                       |
+|---|---|-----------------------------------------------|
+| `${TEST_NAMESPACE}` | Scenario's test namespace | `olmv1-e2e-abc123`                            |
+| `${NAME}` | Current ClusterExtension name | `ce-123`                                      |
+
+---
+
+#### Categories
+
+Organize steps into these 10 categories. For each step, document:
+- **Pattern**: The human-readable Gherkin step text (with capture groups shown as `<arg>`)
+- **Parameters**: Each captured parameter with its Go type
+- **DocString**: Whether the step expects a `"""` YAML block (and what it should contain)
+- **Description**: What the handler function does, based on reading its documentation
+
+**Categories:**
+
+1. **Setup & Prerequisites** - OLM availability, ServiceAccount setup, permissions
+2. **Catalog Management** - ClusterCatalog creation, updates, image tagging, deletion
+3. **ClusterExtension Lifecycle** - Apply, update, remove ClusterExtension resources
+4. **ClusterExtension Status & Conditions** - Condition checks, transition times, reconciliation
+5. **ClusterExtensionRevision** - Revision-specific condition checks, archival, annotations, labels, active revisions
+6. **Generic Resource Operations** - Get, delete, restore, match arbitrary resources
+7. **Test Operator Control** - Marking test-operator deployment ready/not-ready
+8. **Metrics** - Fetching and validating Prometheus metrics
+9. **CRD Patching** - Setting minimum values on CRD fields
+
+Group steps by category.
+
+For each step entry, use this format:
+
+```
+### <N>. <Category Name>
+
+#### `<human-readable pattern>`
+- **Parameters:** `<name>` (string), ...
+- **DocString:** Yes/No — <what to include if yes>
+- **Description:** <what the handler does>
+- **Handler:** `<FunctionName>` in steps.go:<line>
+- **Polling:** Yes/No - <specify the timeout if yes>
+```
+
+---
+
+#### Notes Section
+
+After all categories, include a **Notes** section covering:
+
+- **Case insensitivity**: Most patterns use `(?i)` — step text is case-insensitive
+- **Resource format**: Steps accepting a `"resource"` parameter expect `kind/name` format (e.g., `"deployment/my-deploy"`)
+- **Scenario context**: The ClusterExtension name is auto-captured when a ClusterExtension is applied — subsequent steps reference it implicitly
+- **Duplicate aliases**: Some steps have multiple patterns mapping to the same handler (e.g., `resource "X" is installed` / `resource "X" is available` / `resource "X" exists` all map to `ResourceAvailable`). Note which are aliases.
+- **Catalog naming convention**: Catalog steps automatically append `-catalog` to the name parameter (e.g., `"test"` becomes `"test-catalog"`)

api/v1/clusterextensionrevision_types.go

@@ -42,14 +42,18 @@ const (
 type ClusterExtensionRevisionSpec struct {
 	// lifecycleState specifies the lifecycle state of the ClusterExtensionRevision.
 	//
-	// When set to "Active" (the default), the revision is actively managed and reconciled.
+	// When set to "Active", the revision is actively managed and reconciled.
 	// When set to "Archived", the revision is inactive and any resources not managed by a subsequent revision are deleted.
 	// The revision is removed from the owner list of all objects previously under management.
 	// All objects that did not transition to a succeeding revision are deleted.
 	//
 	// Once a revision is set to "Archived", it cannot be un-archived.
 	//
-	// +kubebuilder:default="Active"
+	// It is possible for more than one revision to be "Active" simultaneously. This will occur when
+	// moving from one revision to another. The old revision will not be set to "Archived" until the
+	// new revision has been completely rolled out.
+	//
+	// +required
 	// +kubebuilder:validation:Enum=Active;Archived
 	// +kubebuilder:validation:XValidation:rule="oldSelf == 'Active' || oldSelf == 'Archived' && oldSelf == self", message="cannot un-archive"
 	LifecycleState ClusterExtensionRevisionLifecycleState `json:"lifecycleState,omitempty"`
@@ -82,7 +86,10 @@ type ClusterExtensionRevisionSpec struct {
 	//
 	// Once set, even if empty, the phases field is immutable.
 	//
+	// Each phase in the list must have a unique name. The maximum number of phases is 20.
+	//
 	// +kubebuilder:validation:XValidation:rule="self == oldSelf || oldSelf.size() == 0", message="phases is immutable"
+	// +kubebuilder:validation:MaxItems=20
 	// +listType=map
 	// +listMapKey=name
 	// +optional
@@ -125,13 +132,17 @@ type ClusterExtensionRevisionPhase struct {
 	//
 	// [RFC 1123]: https://tools.ietf.org/html/rfc1123
 	//
+	// +required
+	// +kubebuilder:validation:MinLength=1
 	// +kubebuilder:validation:MaxLength=63
-	// +kubebuilder:validation:Pattern=`^[a-z]([-a-z0-9]*[a-z0-9])?$`
+	// +kubebuilder:validation:XValidation:rule=`!format.dns1123Label().validate(self).hasValue()`,message="the value must consist of only lowercase alphanumeric characters and hyphens, and must start with an alphabetic character and end with an alphanumeric character."
 	Name string `json:"name"`
 
 	// objects is a required list of all Kubernetes objects that belong to this phase.
 	//
-	// All objects in this list are applied to the cluster in no particular order.
+	// All objects in this list are applied to the cluster in no particular order. The maximum number of objects per phase is 50.
+	// +required
+	// +kubebuilder:validation:MaxItems=50
 	Objects []ClusterExtensionRevisionObject `json:"objects"`
 }
 
@@ -149,7 +160,9 @@ type ClusterExtensionRevisionObject struct {
 	// collisionProtection controls whether the operator can adopt and modify objects
 	// that already exist on the cluster.
 	//
-	// When set to "Prevent" (the default), the operator only manages objects it created itself.
+	// Allowed values are: "Prevent", "IfNoController", and "None".
+	//
+	// When set to "Prevent", the operator only manages objects it created itself.
 	// This prevents ownership collisions.
 	//
 	// When set to "IfNoController", the operator can adopt and modify pre-existing objects
@@ -161,9 +174,8 @@ type ClusterExtensionRevisionObject struct {
 	// Use this setting with extreme caution as it may cause multiple controllers to fight over
 	// the same resource, resulting in increased load on the API server and etcd.
 	//
-	// +kubebuilder:default="Prevent"
+	// +required
 	// +kubebuilder:validation:Enum=Prevent;IfNoController;None
-	// +optional
 	CollisionProtection CollisionProtection `json:"collisionProtection,omitempty"`
 }
 

api/v1/clusterextensionrevision_types_test.go

@@ -21,16 +21,18 @@ func TestClusterExtensionRevisionImmutability(t *testing.T) {
 	}{
 		"revision is immutable": {
 			spec: ClusterExtensionRevisionSpec{
-				Revision: 1,
+				LifecycleState: ClusterExtensionRevisionLifecycleStateActive,
+				Revision:       1,
 			},
 			updateFunc: func(cer *ClusterExtensionRevision) {
 				cer.Spec.Revision = 2
 			},
 		},
 		"phases may be initially empty": {
 			spec: ClusterExtensionRevisionSpec{
-				Revision: 1,
-				Phases:   []ClusterExtensionRevisionPhase{},
+				LifecycleState: ClusterExtensionRevisionLifecycleStateActive,
+				Revision:       1,
+				Phases:         []ClusterExtensionRevisionPhase{},
 			},
 			updateFunc: func(cer *ClusterExtensionRevision) {
 				cer.Spec.Phases = []ClusterExtensionRevisionPhase{
@@ -44,7 +46,8 @@ func TestClusterExtensionRevisionImmutability(t *testing.T) {
 		},
 		"phases may be initially unset": {
 			spec: ClusterExtensionRevisionSpec{
-				Revision: 1,
+				LifecycleState: ClusterExtensionRevisionLifecycleStateActive,
+				Revision:       1,
 			},
 			updateFunc: func(cer *ClusterExtensionRevision) {
 				cer.Spec.Phases = []ClusterExtensionRevisionPhase{
@@ -58,7 +61,8 @@ func TestClusterExtensionRevisionImmutability(t *testing.T) {
 		},
 		"phases are immutable if not empty": {
 			spec: ClusterExtensionRevisionSpec{
-				Revision: 1,
+				LifecycleState: ClusterExtensionRevisionLifecycleStateActive,
+				Revision:       1,
 				Phases: []ClusterExtensionRevisionPhase{
 					{
 						Name:    "foo",
@@ -107,20 +111,87 @@ func TestClusterExtensionRevisionValidity(t *testing.T) {
 	}{
 		"revision cannot be negative": {
 			spec: ClusterExtensionRevisionSpec{
-				Revision: -1,
+				LifecycleState: ClusterExtensionRevisionLifecycleStateActive,
+				Revision:       -1,
 			},
 			valid: false,
 		},
 		"revision cannot be zero": {
-			spec:  ClusterExtensionRevisionSpec{},
+			spec: ClusterExtensionRevisionSpec{
+				LifecycleState: ClusterExtensionRevisionLifecycleStateActive,
+			},
 			valid: false,
 		},
 		"revision must be positive": {
 			spec: ClusterExtensionRevisionSpec{
-				Revision: 1,
+				LifecycleState: ClusterExtensionRevisionLifecycleStateActive,
+				Revision:       1,
 			},
 			valid: true,
 		},
+		"lifecycleState must be set": {
+			spec: ClusterExtensionRevisionSpec{
+				Revision: 1,
+			},
+			valid: false,
+		},
+		"phases must have no more than 20 phases": {
+			spec: ClusterExtensionRevisionSpec{
+				LifecycleState: ClusterExtensionRevisionLifecycleStateActive,
+				Revision:       1,
+				Phases:         make([]ClusterExtensionRevisionPhase, 21),
+			},
+			valid: false,
+		},
+		"phases entries must have no more than 50 objects": {
+			spec: ClusterExtensionRevisionSpec{
+				LifecycleState: ClusterExtensionRevisionLifecycleStateActive,
+				Revision:       1,
+				Phases: []ClusterExtensionRevisionPhase{
+					{
+						Name:    "too-many-objects",
+						Objects: make([]ClusterExtensionRevisionObject, 51),
+					},
+				},
+			},
+			valid: false,
+		},
+		"phases entry names cannot be empty": {
+			spec: ClusterExtensionRevisionSpec{
+				LifecycleState: ClusterExtensionRevisionLifecycleStateActive,
+				Revision:       1,
+				Phases: []ClusterExtensionRevisionPhase{
+					{
+						Name: "",
+					},
+				},
+			},
+			valid: false,
+		},
+		"phases entry names cannot start with symbols": {
+			spec: ClusterExtensionRevisionSpec{
+				LifecycleState: ClusterExtensionRevisionLifecycleStateActive,
+				Revision:       1,
+				Phases: []ClusterExtensionRevisionPhase{
+					{
+						Name: "-invalid",
+					},
+				},
+			},
+			valid: false,
+		},
+		"phases entry names cannot start with numeric characters": {
+			spec: ClusterExtensionRevisionSpec{
+				LifecycleState: ClusterExtensionRevisionLifecycleStateActive,
+				Revision:       1,
+				Phases: []ClusterExtensionRevisionPhase{
+					{
+						Name: "1-invalid",
+					},
+				},
+			},
+			valid: false,
+		},
 	} {
 		t.Run(name, func(t *testing.T) {
 			cer := &ClusterExtensionRevision{

api/v1/validation_test.go

@@ -91,6 +91,7 @@ func TestValidate(t *testing.T) {
 		"ClusterExtensionRevision: invalid progress deadline < 10": {
 			args: args{
 				object: ClusterExtensionRevisionSpec{
+					LifecycleState:          ClusterExtensionRevisionLifecycleStateActive,
 					ProgressDeadlineMinutes: 9,
 				},
 			},
@@ -99,6 +100,7 @@ func TestValidate(t *testing.T) {
 		"ClusterExtensionRevision: valid progress deadline = 10": {
 			args: args{
 				object: ClusterExtensionRevisionSpec{
+					LifecycleState:          ClusterExtensionRevisionLifecycleStateActive,
 					ProgressDeadlineMinutes: 10,
 				},
 			},
@@ -107,6 +109,7 @@ func TestValidate(t *testing.T) {
 		"ClusterExtensionRevision: valid progress deadline = 360": {
 			args: args{
 				object: ClusterExtensionRevisionSpec{
+					LifecycleState:          ClusterExtensionRevisionLifecycleStateActive,
 					ProgressDeadlineMinutes: 360,
 				},
 			},
@@ -115,6 +118,7 @@ func TestValidate(t *testing.T) {
 		"ClusterExtensionRevision: valid progress deadline = 720": {
 			args: args{
 				object: ClusterExtensionRevisionSpec{
+					LifecycleState:          ClusterExtensionRevisionLifecycleStateActive,
 					ProgressDeadlineMinutes: 720,
 				},
 			},
@@ -123,14 +127,17 @@ func TestValidate(t *testing.T) {
 		"ClusterExtensionRevision: invalid progress deadline > 720": {
 			args: args{
 				object: ClusterExtensionRevisionSpec{
+					LifecycleState:          ClusterExtensionRevisionLifecycleStateActive,
 					ProgressDeadlineMinutes: 721,
 				},
 			},
 			want: want{valid: false},
 		},
 		"ClusterExtensionRevision: no progress deadline set": {
 			args: args{
-				object: ClusterExtensionRevisionSpec{},
+				object: ClusterExtensionRevisionSpec{
+					LifecycleState: ClusterExtensionRevisionLifecycleStateActive,
+				},
 			},
 			want: want{valid: true},
 		},

commitchecker.yaml

@@ -1,4 +1,4 @@
-expectedMergeBase: 10c28416b75426e1b1db61efb0d4d0ac5feee6e2
+expectedMergeBase: fb28936f0227ad129151ce04f53598cc08e1b96e
 upstreamBranch: main
 upstreamOrg: operator-framework
 upstreamRepo: operator-controller