docs: Document CustomNoUpgrade featureSet in the feature gates user guide by nikhilprajapati-world · Pull Request #112545 · openshift/openshift-docs

nikhilprajapati-world · 2026-06-01T09:33:05Z

Summary

Add documentation for the CustomNoUpgrade featureSet to the "Enabling features using feature gates"
section of the Nodes guide. Currently, only TechPreviewNoUpgrade is documented. CustomNoUpgrade is
actively used by customers, operators, and upstream projects to enable individual feature gates, but
has no user-facing guidance.

Changes

Added CustomNoUpgrade description and WARNING callout to the "Understanding feature gates" module
(nodes-cluster-enabling-features-about.adoc)
Created new procedure module nodes-cluster-enabling-features-cli-custom.adoc covering:
- oc patch CLI examples for enabling/disabling individual gates at runtime
- FeatureGate CR YAML example with correct customNoUpgrade.enabled ([]string) syntax
- NOTE clarifying that [{"name": "..."}] object format is invalid for the spec
- NOTE clarifying syntax difference between install-config.yaml (Name=true) and the runtime CR (["Name"])
- Verification steps using oc get featuregate
Added CustomNoUpgrade cross-references to CLI and web console modules
Included the new module in the assembly (nodes-cluster-enabling-features.adoc)

Why this matters

CustomNoUpgrade is the only way to enable individual feature gates without the full TechPreview suite
It is irreversible — once set, it cannot be reverted, permanently blocking minor version upgrades
The API reference mentions the warning but it is buried — the user-facing guide where administrators
look for instructions has zero coverage
Real-world customer issues exist:
KCS 7074157 ("CustomNoUpgrade featureSet blocks the
RHOCP 4 upgrade between minor version")
Third-party projects document it independently with varying quality
(CNCF blog,
kata-containers#12864)
OCPSTRAT-2485 (4.22) relies on CustomNoUpgrade for CVO feature-gate-based manifest gating

Historical context

A 2019 comment by @derekwaynecarr
originally categorized CustomNoUpgrade as "not documented". Since then, the landscape has changed:

OCP 4.16 release notes reference CustomNoUpgrade for Cluster API on GCP
Red Hat KCS articles (7065352, 7074157) address customer questions about it
OCPSTRAT-2485 makes it foundational for CVO manifest gating in 4.22
OpenShift component teams (network-edge-tools, cluster-api) document it in their own repos
The 4.10 CSI Storage docs included a CustomNoUpgrade YAML example

The old commented-out section in nodes-cluster-enabling-features-about.adoc has been replaced with a
historical note explaining why documentation is now appropriate.

Technical detail

The CustomNoUpgrade featureSet is enforced via a CEL validation rule in
openshift/api:

// +kubebuilder:validation:XValidation:rule="oldSelf == 'CustomNoUpgrade'
//   ? self == 'CustomNoUpgrade' : true",
//   message="CustomNoUpgrade may not be changed"

The spec.customNoUpgrade.enabled field is []string (not []object), which differs from the
status.featureGates[].enabled format ([{name: "..."}]). This type mismatch is the root cause
of user confusion and is explicitly addressed in the new documentation.

Testing

Verified on OCP 4.22.0-rc.4 (AWS us-east-2):

CustomNoUpgrade correctly enables individual feature gates
Irreversibility confirmed (CEL validation rejects reversion)
oc patch with ["GateName"] syntax confirmed working
oc patch with [{"name":"GateName"}] confirmed rejected with type error

Duplicate check

No existing PR or doc bug found:

No openshift/openshift-docs PR adds CustomNoUpgrade to the feature gates user guide
No OCPDOCS-* Jira ticket references this gap

Related code PRs (not documentation):

openshift/cluster-version-operator#1273 — OCPSTRAT-2485 implementation
openshift/installer#7246 — CustomNoUpgrade in install-config

Related: OCPSTRAT-2485

Made with Cursor

…uide The "Enabling features using feature gates" user guide currently only documents TechPreviewNoUpgrade. CustomNoUpgrade — the only way to enable individual feature gates without the full TechPreview suite — has no user-facing guidance, no correct syntax examples, and no warning about its irreversible nature. Changes: - Add CustomNoUpgrade description and WARNING to the "about" module - Add new procedure module for enabling individual feature gates via oc patch with correct []string syntax - Add cross-references from CLI and web console modules - Include the new module in the assembly - Replace the 2019 "do not document" comment with a historical note explaining why documentation is now appropriate (KCS articles, release notes, OCPSTRAT-2485 CVO manifest gating, ecosystem usage) Tested on OCP 4.22.0-rc.4 (AWS). Related: OCPSTRAT-2485 Co-authored-by: Cursor <cursoragent@cursor.com>

ocpdocs-previewbot · 2026-06-01T09:41:03Z

🤖 Tue Jun 02 02:41:15 - Prow CI generated the docs preview:

https://112545--ocpdocs-pr.netlify.app/openshift-enterprise/latest/nodes/clusters/nodes-cluster-enabling-features.html
https://112545--ocpdocs-pr.netlify.app/openshift-enterprise/latest/post_installation_configuration/cluster-tasks.html

ocpdocs-vale-bot · 2026-06-01T09:41:59Z

+
+where `<feature_gate_name>` is the name of the feature gate you want to enable, for example `ClusterAPIMachineManagement`.
+
+[NOTE]


🤖 [error] AsciiDocDITA.TaskStep: Content other than a single list cannot be mapped to DITA steps.

ocpdocs-vale-bot · 2026-06-01T09:42:02Z

+----
+
+--
+<1> Must be set to `CustomNoUpgrade` to use the `customNoUpgrade` field.


🤖 [error] AsciiDocDITA.CalloutList: Callouts are not supported in DITA.

ocpdocs-vale-bot · 2026-06-01T09:42:05Z


 `spec.featureSet`:: Specifies the feature set that you want to enable:
 * `TechPreviewNoUpgrade` enables specific Technology Preview features.
+* `CustomNoUpgrade` enables granular control over individual feature gates. See xref:../../nodes/clusters/nodes-cluster-enabling-features.adoc#nodes-cluster-enabling-features-cli-custom_nodes-cluster-enabling[Enabling individual feature gates using the CustomNoUpgrade feature set].


🤖 [error] OpenShiftAsciiDoc.NoXrefInModules: Do not include xrefs in modules, only assemblies (exception: release notes modules).

ocpdocs-vale-bot · 2026-06-01T09:42:08Z


 `spec.featureSet`:: Specifies the feature set that you want to enable:
 * `TechPreviewNoUpgrade` enables specific Technology Preview features.
+* `CustomNoUpgrade` enables granular control over individual feature gates. See xref:../../nodes/clusters/nodes-cluster-enabling-features.adoc#nodes-cluster-enabling-features-cli-custom_nodes-cluster-enabling[Enabling individual feature gates using the CustomNoUpgrade feature set].


🤖 [error] OpenShiftAsciiDoc.NoXrefInModules: Do not include xrefs in modules, only assemblies (exception: release notes modules).

- Remove xref cross-references from cli.adoc and console.adoc modules (OpenShiftAsciiDoc.NoXrefInModules) and move to assembly Additional resources section - Merge NOTE into paragraph in cli-custom.adoc step 1 to fix AsciiDocDITA.TaskStep (mixed content in procedure steps) - Replace callout markers with description list in cli-custom.adoc to fix AsciiDocDITA.CalloutList (callouts not supported in DITA) Co-authored-by: Cursor <cursoragent@cursor.com>

ocpdocs-vale-bot · 2026-06-02T02:42:14Z

+  '{"spec":{"customNoUpgrade":{"enabled":[]}}}'
+----
+
+[NOTE]


🤖 [error] AsciiDocDITA.TaskStep: Content other than a single list cannot be mapped to DITA steps.

openshift-ci · 2026-06-02T02:42:25Z

@nikhilprajapati-world: all tests passed!

Full PR test history. Your PR dashboard.

Details

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository. I understand the commands that are listed here.

nikhilprajapati-world · 2026-06-05T04:14:46Z

/label merge-review-needed

openshift-ci Bot added the size/L Denotes a PR that changes 100-499 lines, ignoring generated files. label Jun 1, 2026

ocpdocs-vale-bot reviewed Jun 1, 2026

View reviewed changes

ocpdocs-vale-bot reviewed Jun 2, 2026

View reviewed changes

openshift-ci Bot added the merge-review-needed Signifies that the merge review team needs to review this PR label Jun 5, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: Document CustomNoUpgrade featureSet in the feature gates user guide#112545

docs: Document CustomNoUpgrade featureSet in the feature gates user guide#112545
nikhilprajapati-world wants to merge 2 commits into
openshift:mainfrom
nikhilprajapati-world:docs/custom-no-upgrade-feature-gate-guide

nikhilprajapati-world commented Jun 1, 2026 •

edited by openshift-ci Bot

Loading

Uh oh!

ocpdocs-previewbot commented Jun 1, 2026 •

edited

Loading

Uh oh!

ocpdocs-vale-bot Jun 1, 2026

Uh oh!

ocpdocs-vale-bot Jun 1, 2026

Uh oh!

ocpdocs-vale-bot Jun 1, 2026

Uh oh!

ocpdocs-vale-bot Jun 1, 2026

Uh oh!

ocpdocs-vale-bot Jun 2, 2026

Uh oh!

openshift-ci Bot commented Jun 2, 2026

Uh oh!

nikhilprajapati-world commented Jun 5, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

nikhilprajapati-world commented Jun 1, 2026 • edited by openshift-ci Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

Why this matters

Historical context

Technical detail

Testing

Duplicate check

Uh oh!

ocpdocs-previewbot commented Jun 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ocpdocs-vale-bot Jun 1, 2026

Choose a reason for hiding this comment

Uh oh!

ocpdocs-vale-bot Jun 1, 2026

Choose a reason for hiding this comment

Uh oh!

ocpdocs-vale-bot Jun 1, 2026

Choose a reason for hiding this comment

Uh oh!

ocpdocs-vale-bot Jun 1, 2026

Choose a reason for hiding this comment

Uh oh!

ocpdocs-vale-bot Jun 2, 2026

Choose a reason for hiding this comment

Uh oh!

openshift-ci Bot commented Jun 2, 2026

Uh oh!

nikhilprajapati-world commented Jun 5, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

nikhilprajapati-world commented Jun 1, 2026 •

edited by openshift-ci Bot

Loading

ocpdocs-previewbot commented Jun 1, 2026 •

edited

Loading