OTA-253: Add cluster update preflight mode API

config/v1/tests/clusterversions.config.openshift.io/ClusterUpdatePreflight.yaml

@@ -0,0 +1,235 @@
+apiVersion: apiextensions.k8s.io/v1 # Hack because controller-gen complains if we don't have this
+name: "ClusterVersion"
+crdName: clusterversions.config.openshift.io
+featureGates:
+  - ClusterUpdatePreflight
+tests:
+  onCreate:
+    - name: Should be able to create with mode Preflight
+      initial: |
+        apiVersion: config.openshift.io/v1
+        kind: ClusterVersion
+        spec:
+          clusterID: foo
+          desiredUpdate:
+            version: 4.22.0
+            mode: Preflight
+      expected: |
+        apiVersion: config.openshift.io/v1
+        kind: ClusterVersion
+        spec:
+          clusterID: foo
+          desiredUpdate:
+            version: 4.22.0
+            mode: Preflight
+    - name: Should be able to omit mode field (default behavior)
+      initial: |
+        apiVersion: config.openshift.io/v1
+        kind: ClusterVersion
+        spec:
+          clusterID: foo
+          desiredUpdate:
+            version: 4.22.0
+      expected: |
+        apiVersion: config.openshift.io/v1
+        kind: ClusterVersion
+        spec:
+          clusterID: foo
+          desiredUpdate:
+            version: 4.22.0
+    - name: Should be able to use Preflight mode with acceptRisks
+      initial: |
+        apiVersion: config.openshift.io/v1
+        kind: ClusterVersion
+        spec:
+          clusterID: foo
+          desiredUpdate:
+            version: 4.22.0
+            mode: Preflight
+            acceptRisks:
+              - name: RiskA
+              - name: RiskB
+      expected: |
+        apiVersion: config.openshift.io/v1
+        kind: ClusterVersion
+        spec:
+          clusterID: foo
+          desiredUpdate:
+            version: 4.22.0
+            mode: Preflight
+            acceptRisks:
+              - name: RiskA
+              - name: RiskB
+    - name: Should be able to use Preflight mode with image
+      initial: |
+        apiVersion: config.openshift.io/v1
+        kind: ClusterVersion
+        spec:
+          clusterID: foo
+          desiredUpdate:
+            image: quay.io/openshift-release-dev/ocp-release@sha256:example
+            mode: Preflight
+      expected: |
+        apiVersion: config.openshift.io/v1
+        kind: ClusterVersion
+        spec:
+          clusterID: foo
+          desiredUpdate:
+            image: quay.io/openshift-release-dev/ocp-release@sha256:example
+            mode: Preflight
+    - name: Invalid mode value should be rejected
+      initial: |
+        apiVersion: config.openshift.io/v1
+        kind: ClusterVersion
+        spec:
+          clusterID: foo
+          desiredUpdate:
+            version: 4.22.0
+            mode: InvalidMode
+      expectedError: "Unsupported value: \"InvalidMode\""
+    - name: Empty mode value should be rejected
+      initial: |
+        apiVersion: config.openshift.io/v1
+        kind: ClusterVersion
+        spec:
+          clusterID: foo
+          desiredUpdate:
+            version: 4.22.0
+            mode: ""
+      expectedError: "Unsupported value: \"\""
+    - name: Should allow both force and mode to be set together
+      initial: |
+        apiVersion: config.openshift.io/v1
+        kind: ClusterVersion
+        spec:
+          clusterID: foo
+          desiredUpdate:
+            version: 4.22.0
+            mode: Preflight
+            force: true
+      expected: |
+        apiVersion: config.openshift.io/v1
+        kind: ClusterVersion
+        spec:
+          clusterID: foo
+          desiredUpdate:
+            version: 4.22.0
+            mode: Preflight
+            force: true
+    - name: Should allow Preflight mode when force is explicitly false
+      initial: |
+        apiVersion: config.openshift.io/v1
+        kind: ClusterVersion
+        spec:
+          clusterID: foo
+          desiredUpdate:
+            version: 4.22.0
+            mode: Preflight
+            force: false
+      expected: |
+        apiVersion: config.openshift.io/v1
+        kind: ClusterVersion
+        spec:
+          clusterID: foo
+          desiredUpdate:
+            version: 4.22.0
+            mode: Preflight
+            force: false
+  onUpdate:
+    - name: Should be able to transition from normal to Preflight mode
+      initial: |
+        apiVersion: config.openshift.io/v1
+        kind: ClusterVersion
+        spec:
+          clusterID: foo
+          desiredUpdate:
+            version: 4.22.0
+      updated: |
+        apiVersion: config.openshift.io/v1
+        kind: ClusterVersion
+        spec:
+          clusterID: foo
+          desiredUpdate:
+            version: 4.22.0
+            mode: Preflight
+      expected: |
+        apiVersion: config.openshift.io/v1
+        kind: ClusterVersion
+        spec:
+          clusterID: foo
+          desiredUpdate:
+            version: 4.22.0
+            mode: Preflight
+    - name: Should allow clearing Preflight mode back to normal
+      initial: |
+        apiVersion: config.openshift.io/v1
+        kind: ClusterVersion
+        spec:
+          clusterID: foo
+          desiredUpdate:
+            version: 4.22.0
+            mode: Preflight
+      updated: |
+        apiVersion: config.openshift.io/v1
+        kind: ClusterVersion
+        spec:
+          clusterID: foo
+          desiredUpdate:
+            version: 4.22.0
+      expected: |
+        apiVersion: config.openshift.io/v1
+        kind: ClusterVersion
+        spec:
+          clusterID: foo
+          desiredUpdate:
+            version: 4.22.0
+    - name: Should allow changing target version while in Preflight mode
+      initial: |
+        apiVersion: config.openshift.io/v1
+        kind: ClusterVersion
+        spec:
+          clusterID: foo
+          desiredUpdate:
+            version: 4.22.0
+            mode: Preflight
+      updated: |
+        apiVersion: config.openshift.io/v1
+        kind: ClusterVersion
+        spec:
+          clusterID: foo
+          desiredUpdate:
+            version: 4.23.0
+            mode: Preflight
+      expected: |
+        apiVersion: config.openshift.io/v1
+        kind: ClusterVersion
+        spec:
+          clusterID: foo
+          desiredUpdate:
+            version: 4.23.0
+            mode: Preflight
+    - name: Should allow changing from image to version in Preflight mode
+      initial: |
+        apiVersion: config.openshift.io/v1
+        kind: ClusterVersion
+        spec:
+          clusterID: foo
+          desiredUpdate:
+            image: quay.io/openshift-release-dev/ocp-release@sha256:example
+            mode: Preflight
+      updated: |
+        apiVersion: config.openshift.io/v1
+        kind: ClusterVersion
+        spec:
+          clusterID: foo
+          desiredUpdate:
+            version: 4.23.0
+            mode: Preflight
+      expected: |
+        apiVersion: config.openshift.io/v1
+        kind: ClusterVersion
+        spec:
+          clusterID: foo
+          desiredUpdate:
+            version: 4.23.0
+            mode: Preflight

config/v1/types_cluster_version.go

@@ -283,6 +283,16 @@ type UpdateHistory struct {
 // ClusterID is string RFC4122 uuid.
 type ClusterID string
 
+// UpdateMode defines how an update should be processed.
+// +enum
+// +kubebuilder:validation:Enum=Preflight
+type UpdateMode string
+
+const (
+	// UpdateModePreflight allows an update to be checked for compatibility without committing to updating the cluster.
+	UpdateModePreflight UpdateMode = "Preflight"
+)
+
 // ClusterVersionArchitecture enumerates valid cluster architectures.
 // +kubebuilder:validation:Enum="Multi";""
 type ClusterVersionArchitecture string
@@ -760,6 +770,22 @@ type Update struct {
 	// +listMapKey=name
 	// +optional
 	AcceptRisks []AcceptRisk `json:"acceptRisks,omitempty"`
+
+	// mode determines how an update should be processed.
+	// The only valid value is "Preflight".
+	// When omitted, the cluster performs a normal update by applying the specified version or image to the cluster.
+	// This is the standard update behavior.
+	// When set to "Preflight", the cluster runs compatibility checks against the target release without
+	// performing an actual update. Compatibility results, including any detected risks, are reported
+	// in status.conditionalUpdates and status.conditionalUpdateRisks alongside risks from the update
+	// recommendation service.
+	// This allows administrators to assess update readiness and address issues before committing to the update.
+	// Preflight mode is particularly useful for skip-level updates where upgrade compatibility needs to be
+	// verified across multiple minor versions.
+	// When mode is set to "Preflight", the same rules for version, image, and architecture apply as for normal updates.
+	// +openshift:enable:FeatureGate=ClusterUpdatePreflight
+	// +optional
+	Mode UpdateMode `json:"mode,omitempty"`
 }
 
 // AcceptRisk represents a risk that is considered acceptable.

config/v1/zz_generated.crd-manifests/0000_00_cluster-version-operator_01_clusterversions-CustomNoUpgrade.crd.yaml

@@ -218,6 +218,23 @@ spec:
                       When image is set, architecture cannot be specified.
                       If both version and image are set, the version extracted from the referenced image must match the specified version.
                     type: string
+                  mode:
+                    description: |-
+                      mode determines how an update should be processed.
+                      The only valid value is "Preflight".
+                      When omitted, the cluster performs a normal update by applying the specified version or image to the cluster.
+                      This is the standard update behavior.
+                      When set to "Preflight", the cluster runs compatibility checks against the target release without
+                      performing an actual update. Compatibility results, including any detected risks, are reported
+                      in status.conditionalUpdates and status.conditionalUpdateRisks alongside risks from the update
+                      recommendation service.
+                      This allows administrators to assess update readiness and address issues before committing to the update.
+                      Preflight mode is particularly useful for skip-level updates where upgrade compatibility needs to be
+                      verified across multiple minor versions.
+                      When mode is set to "Preflight", the same rules for version, image, and architecture apply as for normal updates.
+                    enum:
+                    - Preflight
+                    type: string
                   version:
                     description: |-
                       version is a semantic version identifying the update version.

config/v1/zz_generated.crd-manifests/0000_00_cluster-version-operator_01_clusterversions-DevPreviewNoUpgrade.crd.yaml

@@ -218,6 +218,23 @@ spec:
                       When image is set, architecture cannot be specified.
                       If both version and image are set, the version extracted from the referenced image must match the specified version.
                     type: string
+                  mode:
+                    description: |-
+                      mode determines how an update should be processed.
+                      The only valid value is "Preflight".
+                      When omitted, the cluster performs a normal update by applying the specified version or image to the cluster.
+                      This is the standard update behavior.
+                      When set to "Preflight", the cluster runs compatibility checks against the target release without
+                      performing an actual update. Compatibility results, including any detected risks, are reported
+                      in status.conditionalUpdates and status.conditionalUpdateRisks alongside risks from the update
+                      recommendation service.
+                      This allows administrators to assess update readiness and address issues before committing to the update.
+                      Preflight mode is particularly useful for skip-level updates where upgrade compatibility needs to be
+                      verified across multiple minor versions.
+                      When mode is set to "Preflight", the same rules for version, image, and architecture apply as for normal updates.
+                    enum:
+                    - Preflight
+                    type: string
                   version:
                     description: |-
                       version is a semantic version identifying the update version.

config/v1/zz_generated.crd-manifests/0000_00_cluster-version-operator_01_clusterversions-TechPreviewNoUpgrade.crd.yaml

@@ -218,6 +218,23 @@ spec:
                       When image is set, architecture cannot be specified.
                       If both version and image are set, the version extracted from the referenced image must match the specified version.
                     type: string
+                  mode:
+                    description: |-
+                      mode determines how an update should be processed.
+                      The only valid value is "Preflight".
+                      When omitted, the cluster performs a normal update by applying the specified version or image to the cluster.
+                      This is the standard update behavior.
+                      When set to "Preflight", the cluster runs compatibility checks against the target release without
+                      performing an actual update. Compatibility results, including any detected risks, are reported
+                      in status.conditionalUpdates and status.conditionalUpdateRisks alongside risks from the update
+                      recommendation service.
+                      This allows administrators to assess update readiness and address issues before committing to the update.
+                      Preflight mode is particularly useful for skip-level updates where upgrade compatibility needs to be
+                      verified across multiple minor versions.
+                      When mode is set to "Preflight", the same rules for version, image, and architecture apply as for normal updates.
+                    enum:
+                    - Preflight
+                    type: string
                   version:
                     description: |-
                       version is a semantic version identifying the update version.

config/v1/zz_generated.featuregated-crd-manifests.yaml

@@ -144,6 +144,7 @@ clusterversions.config.openshift.io:
   Category: ""
   FeatureGates:
   - ClusterUpdateAcceptRisks
+  - ClusterUpdatePreflight
   - ImageStreamImportMode
   - SignatureStores
   FilenameOperatorName: cluster-version-operator