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
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
197 changes: 197 additions & 0 deletions config/v1/tests/clusterversions.config.openshift.io/ClusterUpdatePreflight.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,197 @@
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: \"\""
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
27 changes: 27 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,17 @@ type UpdateHistory struct {
// ClusterID is string RFC4122 uuid.
type ClusterID string

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

@saschagrunert saschagrunert Feb 10, 2026

Choose a reason for hiding this comment

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

+enum adds an Enum constraint to the OpenAPI schema and appends auto-generated enum documentation to the description.

Suggested change
// +kubebuilder:validation:Enum=Preflight
// +enum
// +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 +771,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. The target release's CVO will execute prechecks and report any detected
// risks in status.conditionalUpdateRisks, alongside risks from the update recommendation service.
// status.conditionalUpdates contains references/entries that point to the detailed risk objects
// stored in status.conditionalUpdateRisks from both the update graph and preflight checks executed by the target release's CVO.
// 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"`
Comment on lines 775 to 789
Copy link

@coderabbitai coderabbitai bot Feb 10, 2026

Choose a reason for hiding this comment

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

⚠️ Potential issue | 🟡 Minor

Clarify which status field carries preflight risks.

The doc says risks appear in status.conditionalUpdates, but risk details live in status.conditionalUpdateRisks (with conditionalUpdates referencing them). This could mislead API consumers. Consider tightening the wording.

✏️ Suggested doc tweak 
- // risks in status.conditionalUpdates, alongside risks from the update recommendation service.
- // Results appear in status.conditionalUpdates as a union of risks from both the update graph and
- // preflight checks executed by the target release's CVO.
+ // risks in status.conditionalUpdateRisks, alongside risks from the update recommendation service,
+ // and are referenced by status.conditionalUpdates.
+ // Results appear in status.conditionalUpdateRisks as a union of risks from both the update graph and
+ // preflight checks executed by the target release's CVO.
🤖 Prompt for AI Agents 
In `@config/v1/types_cluster_version.go` around lines 775 - 789, Update the
comment for the Mode field (UpdateModePolicy) to correctly state that preflight
risk details are reported in status.conditionalUpdateRisks and that
status.conditionalUpdates contains references/entries that point to those risk
objects; replace the sentence that says "Results appear in
status.conditionalUpdates as a union of risks..." with wording that clarifies
conditionalUpdates references the risk objects and the detailed risk payloads
are stored in status.conditionalUpdateRisks (keeping the rest of the preflight
explanation and the FeatureGate/optional tags intact).

}

// AcceptRisk represents a risk that is considered acceptable.
Expand Down
17 changes: 17 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,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. The target release's CVO will execute prechecks and report any detected
risks in status.conditionalUpdateRisks, alongside risks from the update recommendation service.
status.conditionalUpdates contains references/entries that point to the detailed risk objects
stored in status.conditionalUpdateRisks from both the update graph and preflight checks executed by the target release's CVO.
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.
enum:
- Preflight
type: string
version:
description: |-
version is a semantic version identifying the update version.
Expand Down
17 changes: 17 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,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. The target release's CVO will execute prechecks and report any detected
risks in status.conditionalUpdateRisks, alongside risks from the update recommendation service.
status.conditionalUpdates contains references/entries that point to the detailed risk objects
stored in status.conditionalUpdateRisks from both the update graph and preflight checks executed by the target release's CVO.
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.
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