Skip to content

OTA-253: Add cluster update preflight mode API #2684

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

Open
fao89 wants to merge 1 commit into
base: master
Choose a base branch
from
+1,036 −0
Open

OTA-253: Add cluster update preflight mode API #2684

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
181 changes: 181 additions & 0 deletions config/v1/tests/clusterversions.config.openshift.io/ClusterUpdatePreflight.yaml
View file
Open in desktop
Copy link
Member

@saschagrunert saschagrunert Feb 4, 2026

Choose a reason for hiding this comment

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

I'd keep tests cases only which validate actual behavior constraints. Means that basic CRUD is probably out of scope.

We also need a test for mode: "" as invalid value.

Original file line number Diff line number Diff line change
@@ -0,0 +1,181 @@
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 set mode to 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 image
initial: |
apiVersion: config.openshift.io/v1
kind: ClusterVersion
spec:
clusterID: foo
desiredUpdate:
image: quay.io/openshift-release-dev/ocp-release@sha256:abc123
mode: Preflight
expected: |
apiVersion: config.openshift.io/v1
kind: ClusterVersion
spec:
clusterID: foo
desiredUpdate:
image: quay.io/openshift-release-dev/ocp-release@sha256:abc123
mode: Preflight
- name: Should be able to use Preflight mode with architecture
initial: |
apiVersion: config.openshift.io/v1
kind: ClusterVersion
spec:
clusterID: foo
desiredUpdate:
architecture: Multi
version: 4.22.0
mode: Preflight
expected: |
apiVersion: config.openshift.io/v1
kind: ClusterVersion
spec:
clusterID: foo
desiredUpdate:
architecture: Multi
version: 4.22.0
mode: Preflight
- 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: 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\""
onUpdate:
- name: Should be able to change mode from normal to Preflight
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 be able to change mode from Preflight 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 be able to change 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
18 changes: 18 additions & 0 deletions config/v1/types_cluster_version.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -283,6 +283,15 @@ type UpdateHistory struct {
// ClusterID is string RFC4122 uuid.
type ClusterID string

// UpdateModePolicy defines how an update should be processed.
// +kubebuilder:validation:Enum=Preflight
Comment on lines +286 to +287
Copy link
Member

@saschagrunert saschagrunert Feb 4, 2026

Choose a reason for hiding this comment

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

nit nit:

Suggested change
// UpdateModePolicy defines how an update should be processed.
// +kubebuilder:validation:Enum=Preflight
// UpdateModePolicy defines how an update should be processed.
// Valid values are defined as constants below.
// +kubebuilder:validation:Enum=Preflight

type UpdateModePolicy string

const (
// UpdateModePolicyPreflight allows an update to be checked for compatibility without committing to updating the cluster.
UpdateModePolicyPreflight UpdateModePolicy = "Preflight"
)

// ClusterVersionArchitecture enumerates valid cluster architectures.
// +kubebuilder:validation:Enum="Multi";""
type ClusterVersionArchitecture string
Expand Down Expand Up @@ -760,6 +769,15 @@ type Update struct {
// +listMapKey=name
// +optional
AcceptRisks []AcceptRisk `json:"acceptRisks,omitempty"`

// mode allows an update to be checked for compatibility without committing to updating the cluster.
// Allowed values are "Preflight" and omitted.
// When omitted, the default mode allows existing clients to request normal updates.
// When set to "Preflight", the cluster will run compatibility checks against the target release
// without performing an actual update.
// +openshift:enable:FeatureGate=ClusterUpdatePreflight
// +optional
Mode UpdateModePolicy `json:"mode,omitempty"`
Comment on lines +773 to +780
Copy link
Member

@saschagrunert saschagrunert Feb 4, 2026

Choose a reason for hiding this comment

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

As I can see from the slack thread, the documentation should reflect that preflight results appear in status.conditionalUpdates:

conditional update risks becomes a union of things coming from the update graph and pre flight checks

How about something like:

Suggested change
// mode allows an update to be checked for compatibility without committing to updating the cluster.
// Allowed values are "Preflight" and omitted.
// When omitted, the default mode allows existing clients to request normal updates.
// When set to "Preflight", the cluster will run compatibility checks against the target release
// without performing an actual update.
// +openshift:enable:FeatureGate=ClusterUpdatePreflight
// +optional
Mode UpdateModePolicy `json:"mode,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. The target release's CVO will execute prechecks and report any detected
// risks in status.conditionalUpdates, 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.
// +openshift:enable:FeatureGate=ClusterUpdatePreflight
// +optional
Mode UpdateModePolicy `json:"mode,omitempty"`

We have to:

  • Explicitly state WHERE results appear (status.conditionalUpdates)
  • Explain the union behavior (update graph + preflight checks)
  • Mention skip-level use case (primary motivation from enhancement PR)

}

// AcceptRisk represents a risk that is considered acceptable.
Expand Down
10 changes: 10 additions & 0 deletions ...rd-manifests/0000_00_cluster-version-operator_01_clusterversions-CustomNoUpgrade.crd.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -218,6 +218,16 @@ 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 allows an update to be checked for compatibility without committing to updating the cluster.
Allowed values are "Preflight" and omitted.
When omitted, the default mode allows existing clients to request normal updates.
When set to "Preflight", the cluster will run compatibility checks against the target release
without performing an actual update.
enum:
- Preflight
type: string
version:
description: |-
version is a semantic version identifying the update version.
Expand Down
10 changes: 10 additions & 0 deletions ...nifests/0000_00_cluster-version-operator_01_clusterversions-TechPreviewNoUpgrade.crd.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -218,6 +218,16 @@ 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 allows an update to be checked for compatibility without committing to updating the cluster.
Allowed values are "Preflight" and omitted.
When omitted, the default mode allows existing clients to request normal updates.
When set to "Preflight", the cluster will run compatibility checks against the target release
without performing an actual update.
enum:
- Preflight
type: string
version:
description: |-
version is a semantic version identifying the update version.
Expand Down
1 change: 1 addition & 0 deletions config/v1/zz_generated.featuregated-crd-manifests.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -144,6 +144,7 @@ clusterversions.config.openshift.io:
Category: ""
FeatureGates:
- ClusterUpdateAcceptRisks
- ClusterUpdatePreflight
- ImageStreamImportMode
- SignatureStores
FilenameOperatorName: cluster-version-operator
Expand Down
Loading