From f660eb7748e5c3650dd917b40b7d95a4946ab4fa Mon Sep 17 00:00:00 2001 From: Nikhil Prajapati Date: Mon, 1 Jun 2026 15:02:04 +0530 Subject: [PATCH 1/2] docs: Document CustomNoUpgrade featureSet in the feature gates user guide MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- ...nodes-cluster-enabling-features-about.adoc | 35 +++--- ...-cluster-enabling-features-cli-custom.adoc | 110 ++++++++++++++++++ .../nodes-cluster-enabling-features-cli.adoc | 1 + ...des-cluster-enabling-features-console.adoc | 1 + .../nodes-cluster-enabling-features.adoc | 2 + 5 files changed, 131 insertions(+), 18 deletions(-) create mode 100644 modules/nodes-cluster-enabling-features-cli-custom.adoc diff --git a/modules/nodes-cluster-enabling-features-about.adoc b/modules/nodes-cluster-enabling-features-about.adoc index 61665dac8a94..a92d5f9d2021 100644 --- a/modules/nodes-cluster-enabling-features-about.adoc +++ b/modules/nodes-cluster-enabling-features-about.adoc @@ -11,7 +11,7 @@ You can use the `FeatureGate` custom resource (CR) to enable specific feature se A feature set is a collection of {product-title} features that are not enabled by default. -You can activate the following feature set by using the `FeatureGate` CR: +You can activate the following feature sets by using the `FeatureGate` CR: * `TechPreviewNoUpgrade`. This feature set is a subset of the current Technology Preview features. This feature set allows you to enable these Technology Preview features on test clusters, where you can fully test them, while leaving the features disabled on production clusters. + @@ -19,6 +19,13 @@ You can activate the following feature set by using the `FeatureGate` CR: ==== Enabling the `TechPreviewNoUpgrade` feature set on your cluster cannot be undone and prevents minor version updates. You should not enable this feature set on production clusters. ==== + +* `CustomNoUpgrade`. This feature set allows you to enable or disable individual feature gates without activating the entire Technology Preview suite. Use this feature set when you need granular control over specific feature gates. ++ +[WARNING] +==== +Enabling the `CustomNoUpgrade` feature set on your cluster cannot be undone and prevents minor version updates. This feature set is not supported, cannot be validated, and should not be enabled on production clusters. If you apply incorrect feature gate names or invalid combinations, your cluster may fail in an unrecoverable way. +==== + The following Technology Preview features are enabled by this feature set: + @@ -128,20 +135,12 @@ The following Technology Preview features are enabled by this feature set: See the _Additional resources_ sections for information on some of these features. -//// -Do not document per Derek Carr: https://github.com/openshift/api/pull/370#issuecomment-510632939 -|`CustomNoUpgrade` ^[2]^ -|Allows the enabling or disabling of any feature. Turning on this feature set on is not supported, cannot be undone, and prevents upgrades. - -[.small] --- -1. -2. If you use the `CustomNoUpgrade` feature set to disable a feature that appears in the web console, you might see that feature, but -no objects are listed. For example, if you disable builds, you can see the *Builds* tab in the web console, but there are no builds present. If you attempt to use commands associated with a disabled feature, such as `oc start-build`, {product-title} displays an error. - -[NOTE] -==== -If you disable a feature that any application in the cluster relies on, the application might not -function properly, depending upon the feature disabled and how the application uses that feature. -==== -//// +// Historical note: CustomNoUpgrade was previously excluded from documentation per +// https://github.com/openshift/api/pull/370#issuecomment-510632939 (July 2019). +// Since then, CustomNoUpgrade has become widely used across the ecosystem: +// - OCP 4.16 release notes reference it for Cluster API on GCP +// - Red Hat KCS articles 7065352 and 7074157 address customer usage +// - OCPSTRAT-2485 (4.22) relies on it for CVO manifest gating +// - Multiple OpenShift component teams use it in their documentation +// The decision to document it was made to address documented customer confusion +// and to align with current usage patterns. diff --git a/modules/nodes-cluster-enabling-features-cli-custom.adoc b/modules/nodes-cluster-enabling-features-cli-custom.adoc new file mode 100644 index 000000000000..f6656410fa48 --- /dev/null +++ b/modules/nodes-cluster-enabling-features-cli-custom.adoc @@ -0,0 +1,110 @@ +// Module included in the following assemblies: +// +// * nodes/cluster/nodes-cluster-enabling-features.adoc + +:_mod-docs-content-type: PROCEDURE +[id="nodes-cluster-enabling-features-cli-custom_{context}"] += Enabling individual feature gates using the CustomNoUpgrade feature set + +[role="_abstract"] +You can use the {oc-first} to enable or disable individual feature gates on your cluster by setting the `CustomNoUpgrade` feature set on the `FeatureGate` custom resource (CR). Unlike `TechPreviewNoUpgrade`, which enables all Technology Preview features, `CustomNoUpgrade` gives you granular control over individual feature gates. + +[WARNING] +==== +Enabling the `CustomNoUpgrade` feature set on your cluster cannot be undone and prevents minor version updates. Once applied, you cannot revert the `featureSet` field back to its default value. You can continue to modify the individual gates within `customNoUpgrade.enabled` and `customNoUpgrade.disabled`, but the `CustomNoUpgrade` feature set itself is permanent. + +This feature set is not supported for production clusters. Because of its nature, this setting cannot be validated. If you have any typos or accidentally apply invalid combinations, your cluster may fail in an unrecoverable way. +==== + +.Prerequisites + +* You have installed the {oc-first}. +* You have cluster administrator privileges. + +.Procedure + +. Enable a specific feature gate by patching the `FeatureGate` CR: ++ +[source,terminal] +---- +$ oc patch featuregate cluster --type=merge -p \ + '{"spec":{"featureSet":"CustomNoUpgrade","customNoUpgrade":{"enabled":[""]}}}' +---- ++ +where `` is the name of the feature gate you want to enable, for example `ClusterAPIMachineManagement`. ++ +[NOTE] +==== +The `spec.customNoUpgrade.enabled` field accepts a string array. Each element is a feature gate name as a plain string. Do not use the object format `{"name": "FeatureGateName"}`. The object format is used in `status.featureGates` but is not valid for the spec. +==== + +. To enable multiple feature gates at once: ++ +[source,terminal] +---- +$ oc patch featuregate cluster --type=merge -p \ + '{"spec":{"featureSet":"CustomNoUpgrade","customNoUpgrade":{"enabled":["",""]}}}' +---- + +. To remove a previously enabled feature gate from the enabled list: ++ +[source,terminal] +---- +$ oc patch featuregate cluster --type=merge -p \ + '{"spec":{"customNoUpgrade":{"enabled":[]}}}' +---- ++ +[NOTE] +==== +This removes all individually enabled gates but does not revert the `CustomNoUpgrade` feature set. The cluster remains on `CustomNoUpgrade` and minor version upgrades remain blocked. +==== + +. Alternatively, you can enable the feature set by editing the `FeatureGate` CR directly: ++ +[source,terminal] +---- +$ oc edit featuregate cluster +---- ++ +.Sample FeatureGate custom resource with CustomNoUpgrade +[source,yaml] +---- +apiVersion: config.openshift.io/v1 +kind: FeatureGate +metadata: + name: cluster +spec: + featureSet: CustomNoUpgrade <1> + customNoUpgrade: + enabled: <2> + - + disabled: <3> + - +---- ++ +-- +<1> Must be set to `CustomNoUpgrade` to use the `customNoUpgrade` field. +<2> A list of feature gate names to enable, specified as plain strings. +<3> Optional. A list of feature gate names to explicitly disable. +-- ++ +After you save the changes, new machine configs are created, the machine config pools are updated, and scheduling on each node is disabled while the change is being applied. + +[NOTE] +==== +The syntax for enabling feature gates differs between the `install-config.yaml` file and the `FeatureGate` CR: + +* In `install-config.yaml`, use `featureGates: ["=true"]` +* In the `FeatureGate` CR at runtime, use `customNoUpgrade.enabled: [""]` +==== + +.Verification + +include::snippets/nodes-cluster-enabling-features-verification.adoc[] + +You can also verify the enabled feature gates by checking the `FeatureGate` CR status: + +[source,terminal] +---- +$ oc get featuregate cluster -o jsonpath='{.status.featureGates[0].enabled[*].name}' | tr ' ' '\n' +---- diff --git a/modules/nodes-cluster-enabling-features-cli.adoc b/modules/nodes-cluster-enabling-features-cli.adoc index 1e4801af9d39..62dbd1320d7d 100644 --- a/modules/nodes-cluster-enabling-features-cli.adoc +++ b/modules/nodes-cluster-enabling-features-cli.adoc @@ -45,6 +45,7 @@ where: `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]. -- + After you save the changes, new machine configs are created, the machine config pools are updated, and scheduling on each node is disabled while the change is being applied. diff --git a/modules/nodes-cluster-enabling-features-console.adoc b/modules/nodes-cluster-enabling-features-console.adoc index 1bd4c13c4f43..2626db775209 100644 --- a/modules/nodes-cluster-enabling-features-console.adoc +++ b/modules/nodes-cluster-enabling-features-console.adoc @@ -45,6 +45,7 @@ where: `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]. -- + After you save the changes, new machine configs are created, the machine config pools are updated, and scheduling on each node is disabled while the change is being applied. diff --git a/nodes/clusters/nodes-cluster-enabling-features.adoc b/nodes/clusters/nodes-cluster-enabling-features.adoc index 1c0d2e71a8d0..df8f9e946e35 100644 --- a/nodes/clusters/nodes-cluster-enabling-features.adoc +++ b/nodes/clusters/nodes-cluster-enabling-features.adoc @@ -17,6 +17,8 @@ include::modules/nodes-cluster-enabling-features-console.adoc[leveloffset=+1] include::modules/nodes-cluster-enabling-features-cli.adoc[leveloffset=+1] +include::modules/nodes-cluster-enabling-features-cli-custom.adoc[leveloffset=+1] + [role="_additional-resources"] [id="additional-resources_nodes-cluster-enabling"] == Additional resources From b559aa50ff09236c477acd4b664fa9076f2bae67 Mon Sep 17 00:00:00 2001 From: Nikhil Prajapati Date: Tue, 2 Jun 2026 08:01:30 +0530 Subject: [PATCH 2/2] fix: resolve Vale linter and portal build errors - 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 --- ...-cluster-enabling-features-cli-custom.adoc | 20 ++++++++----------- .../nodes-cluster-enabling-features-cli.adoc | 2 +- ...des-cluster-enabling-features-console.adoc | 2 +- .../nodes-cluster-enabling-features.adoc | 2 ++ 4 files changed, 12 insertions(+), 14 deletions(-) diff --git a/modules/nodes-cluster-enabling-features-cli-custom.adoc b/modules/nodes-cluster-enabling-features-cli-custom.adoc index f6656410fa48..c75ec89bd33a 100644 --- a/modules/nodes-cluster-enabling-features-cli-custom.adoc +++ b/modules/nodes-cluster-enabling-features-cli-custom.adoc @@ -31,12 +31,7 @@ $ oc patch featuregate cluster --type=merge -p \ '{"spec":{"featureSet":"CustomNoUpgrade","customNoUpgrade":{"enabled":[""]}}}' ---- + -where `` is the name of the feature gate you want to enable, for example `ClusterAPIMachineManagement`. -+ -[NOTE] -==== -The `spec.customNoUpgrade.enabled` field accepts a string array. Each element is a feature gate name as a plain string. Do not use the object format `{"name": "FeatureGateName"}`. The object format is used in `status.featureGates` but is not valid for the spec. -==== +where `` is the name of the feature gate you want to enable, for example `ClusterAPIMachineManagement`. The `spec.customNoUpgrade.enabled` field accepts a string array. Each element is a feature gate name as a plain string. Do not use the object format `{"name": "FeatureGateName"}`, which appears in `status.featureGates` but is not valid for the spec. . To enable multiple feature gates at once: + @@ -74,18 +69,19 @@ kind: FeatureGate metadata: name: cluster spec: - featureSet: CustomNoUpgrade <1> + featureSet: CustomNoUpgrade customNoUpgrade: - enabled: <2> + enabled: - - disabled: <3> + disabled: - ---- +where: + -- -<1> Must be set to `CustomNoUpgrade` to use the `customNoUpgrade` field. -<2> A list of feature gate names to enable, specified as plain strings. -<3> Optional. A list of feature gate names to explicitly disable. +`spec.featureSet`:: Must be set to `CustomNoUpgrade` to use the `customNoUpgrade` field. +`spec.customNoUpgrade.enabled`:: A list of feature gate names to enable, specified as plain strings. +`spec.customNoUpgrade.disabled`:: Optional. A list of feature gate names to explicitly disable. -- + After you save the changes, new machine configs are created, the machine config pools are updated, and scheduling on each node is disabled while the change is being applied. diff --git a/modules/nodes-cluster-enabling-features-cli.adoc b/modules/nodes-cluster-enabling-features-cli.adoc index 62dbd1320d7d..188720f88464 100644 --- a/modules/nodes-cluster-enabling-features-cli.adoc +++ b/modules/nodes-cluster-enabling-features-cli.adoc @@ -45,7 +45,7 @@ where: `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]. +* `CustomNoUpgrade` enables granular control over individual feature gates. -- + After you save the changes, new machine configs are created, the machine config pools are updated, and scheduling on each node is disabled while the change is being applied. diff --git a/modules/nodes-cluster-enabling-features-console.adoc b/modules/nodes-cluster-enabling-features-console.adoc index 2626db775209..132deba6fba2 100644 --- a/modules/nodes-cluster-enabling-features-console.adoc +++ b/modules/nodes-cluster-enabling-features-console.adoc @@ -45,7 +45,7 @@ where: `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]. +* `CustomNoUpgrade` enables granular control over individual feature gates. -- + After you save the changes, new machine configs are created, the machine config pools are updated, and scheduling on each node is disabled while the change is being applied. diff --git a/nodes/clusters/nodes-cluster-enabling-features.adoc b/nodes/clusters/nodes-cluster-enabling-features.adoc index df8f9e946e35..a46a39d94f5d 100644 --- a/nodes/clusters/nodes-cluster-enabling-features.adoc +++ b/nodes/clusters/nodes-cluster-enabling-features.adoc @@ -38,3 +38,5 @@ include::modules/nodes-cluster-enabling-features-cli-custom.adoc[leveloffset=+1] * xref:../../storage/container_storage_interface/persistent-storage-csi-sc-manage.adoc#persistent-storage-csi-sc-manage[Managing the default storage class] * xref:../../authentication/understanding-and-managing-pod-security-admission.adoc#understanding-and-managing-pod-security-admission[Pod security admission enforcement] + +* 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]