updating feature gates docs #24132

mburke5678 · 2020-07-23T17:54:50Z

https://bugzilla.redhat.com/show_bug.cgi?id=1860289

Reorganized the information; updated feature set list; added console instructions; renamed files for consistency.

Preview: https://deploy-preview-24132--osdocs.netlify.app/openshift-enterprise/latest/nodes/clusters/nodes-cluster-enabling-features.html

Wording for unsupported feature sets from: https://github.com/openshift/machine-config-operator/blob/master/vendor/github.com/openshift/api/config/v1/types_feature.go#L41

LatencySentitive feature set no longer required for Topology Manager per https://access.redhat.com/solutions/5807641 and https://bugzilla.redhat.com/show_bug.cgi?id=1921160

LatencySensitive feature set does not affect any other feature and can be removed from docs: https://coreos.slack.com/archives/CQNBUEVM2/p1618238903115900?thread_ts=1616327266.083200&cid=CQNBUEVM2

mburke5678 · 2020-10-22T21:44:11Z

@sttts Here is a second attempt at reworking the feature gates docs. WDYT?

sttts · 2020-10-23T10:52:04Z

modules/nodes-cluster-enabling-features-cli.adoc

how do I know the set of feature gates I can set?

sttts · 2020-10-23T10:53:29Z

modules/nodes-cluster-enabling-features-cluster.adoc

there is no easier way than this to reach a config CR? @jhadvig can you confirm?

sttts · 2020-10-23T10:53:57Z

modules/nodes-cluster-enabling-features-cluster.adoc

same as above: this needs a link to all possible values.

sttts · 2020-10-23T10:55:44Z

modules/nodes-cluster-features-about.adoc

double "enables"

sttts · 2020-10-23T10:56:54Z

Nits and missing links.

mburke5678 · 2020-10-28T16:47:31Z

@xltian Can you please assign this issue to a QE resource for review? Thank you!

lyman9966 · 2020-10-29T09:58:38Z

modules/nodes-cluster-features-about.adoc

from https://github.com/openshift/api/blob/master/config/v1/types_feature.go, I saw "IPv6DualStackNoUpgrade enables dual-stack. Turning this feature set on IS NOT SUPPORTED". Since turn this feature set on is not supported, we should remove IPv6DualStackNoUpgrade feature set.

cc networking team @danwinship

I'm not sure what the rules about documenting feature sets are. In this case, we don't want the featureset to be used by people who don't already know about it, so not documenting it seems like the right thing.

modules/nodes-cluster-features-about.adoc

lyman9966 · 2020-10-29T10:10:09Z

modules/nodes-cluster-features-about.adoc

from https://docs.openshift.com/container-platform/4.5/nodes/clusters/nodes-cluster-enabling-features.html#feature-gate-features_nodes-cluster-enabling ，do we need add Technology Preview features like MachineHealthCheck and LocalStorageCapacityIsolation?

@lyman9966 @sttts The list came from here: https://github.com/openshift/api/blob/release-4.6/config/v1/types_feature.go#L29
Stefan, these are the 4 feature sets that the user can enable?

@mburke5678 I think you misunderstood me. "https://docs.openshift.com/container-platform/4.5/nodes/clusters/nodes-cluster-enabling-features.html#feature-gate-features_nodes-cluster-enabling" show us there are 4 features affected by feature set "TechPreviewNoUpgrade", such as "RotateKubeletServerCertificate","SupportPodPidsLimit","MachineHealthCheck","LocalStorageCapacityIsolation". Yet your doc lack the latter two.

@lyman9966 MachineHealthCheck went GA in 4.3: https://docs.openshift.com/container-platform/4.3/machine_management/deploying-machine-health-checks.html
It appears that LocalStorageCapacityIsolation was enabled at some point https://github.com/openshift/api/pull/462/files

I assume this means that the TechPreviewNoUpgrade feature gate would not enable these features.

@mburke5678 , Okay, then "MachineHealthCheck" and "LocalStorageCapacityIsolation" doesn't belong to TechPreview feature, so they can be removed.

sttts · 2020-11-02T12:59:32Z

General question: why do we place feature gates under node configuration in the docs? We had a similar case with audit and moved it out from there. Both audit and features gates are cluster-wide settings, and have nothing to do with nodes in particular.

lyman9966 · 2020-11-03T09:29:15Z

General question: why do we place feature gates under node configuration in the docs? We had a similar case with audit and moved it out from there. Both audit and features gates are cluster-wide settings, and have nothing to do with nodes in particular.

@sttts I see the feature gates under Node->Working with clusters chapter, It seems in 4.x, we move cluster-wide settings to Node chapter.

mburke5678 · 2020-11-03T15:00:26Z

@sttts I would guess that Feature Gates was added to nodes (likely by me) because in 3.x the user could activate feature gates by node in addition to the entire cluster.
Enabling feature gates is also included in the Post-installation cluster tasks topic.
https://docs.openshift.com/container-platform/4.6/post_installation_configuration/cluster-tasks.html#nodes-cluster-enabling-features-cluster_post-install-cluster-tasks
If you can think of another or a better location for this information, please met me know!

mburke5678 · 2020-11-03T15:16:18Z

@sferich888 There has been discussion here about whether we want to document Feature Gates that enable unsupported features in the end user docs. What do you think?

mburke5678 · 2020-11-10T21:34:32Z

modules/nodes-cluster-features-about.adoc

The following is commented-out. No need for review at this time

mburke5678 · 2020-12-03T18:33:22Z

@sferich888 There has been discussion here about whether we want to document Feature Gates that enable unsupported features in the end user docs. What do you think?

mburke5678 · 2020-12-08T16:38:37Z

@sferich888 There has been discussion here about whether we want to document Feature Gates that enable unsupported features in the end user docs. What do you think?

mburke5678 · 2021-01-04T18:18:01Z

@reestr Can you weigh in here in Eric Rich's absence? Do we want to document Feature Gates that enable unsupported features in the end user docs?

mburke5678 · 2021-03-18T21:42:34Z

@sferich888 Do we want to document Feature Gates that enable unsupported features in the end user docs?

|IPv6DualStackNoUpgrade
|Enables the dual-stack networking mode in your cluster. Dual-stack networking supports the use of IPv4 and IPv6 simultaneously. Turning on this feature set is not supported, cannot be undone, and prevents upgrades.

@lyman9966 said: Turning this feature set on IS NOT SUPPORTED". Since turn this feature set on is not supported, we should remove IPv6DualStackNoUpgrade feature set.

sferich888 · 2021-03-30T20:41:19Z

@mburke5678 documenting the 'available' feature gates 'supported' or 'unsupported' is fine, so long as we 'clearly' (boldly) call out what 'features' are 'experimental' and or 'risky' for production usecases.

The term 'unsupported' (or inversely - supported) is a loaded term, because it means many things to many different people (or classes of users), so I would 'try and avoid it'. however in your 'statement' what you say is fine as your clearly outlining that enabling this / blocks upgrades.

mburke5678 · 2021-03-30T21:10:52Z

@sferich888 @lyman9966 I can add the term experimental, as we do use that in the docs. I am not sure if IPv6DualStackNoUpgrade is officially experimental (or who decides something is experimental and how it is decided).

@lyman9966 Can I ask you to please take another look at the udated warnings for TechPreviewNoUpgrade or IPv6DualStackNoUpgrade.

netlify · 2021-03-30T21:51:28Z

Deploy preview for osdocs ready!

Built with commit b0191852e5ecca65b02d8a87d421fb176b09534a

https://deploy-preview-24132--osdocs.netlify.app

openshift-ci-robot · 2021-04-09T14:45:22Z

New changes are detected. LGTM label has been removed.

lbarbeevargas

Great job on this! Just a few comments per the OCP guidelines and some small wording suggestions. :)

lbarbeevargas · 2021-04-09T19:29:34Z

modules/nodes-cluster-enabling-features-about.adoc

If you are specifying say that this is a custom resource, what do you think of:

s/the Feature Gate custom resource (CR)/the FeatureGate custom resource (CR)/.

It is also in backticks in modules/nodes-cluster-enabling-features-cli.adoc.

Yeah, I caught that one, but missed the others. D'oh!

lbarbeevargas · 2021-04-09T19:31:14Z

modules/nodes-cluster-enabling-features-about.adoc

Similar comment as for the module intro above:
s/Feature Gate CR/FeatureGate CR/

lbarbeevargas · 2021-04-09T19:36:00Z

modules/nodes-cluster-enabling-features-about.adoc

I think we recently switched from bold to italics to emphasize text. s/*not supported*/_not supported_/
Per the doc guidelines:

Use of underscores for general emphasis is allowed but should only be used very sparingly.

I am now watching the Doc Guidelines. Hope I get notified of such changes!

lbarbeevargas · 2021-04-09T19:38:56Z

modules/nodes-cluster-enabling-features-about.adoc

Does the feature set need to be in backticks here? s/SupportPodPidsLimit/SupportPodPidsLimit/

@lbarbeevargas That is the name of a feature in the feature set. I don't think we mark-up feature names(??). We don't in Tech Preview notes, apparently: https://github.com/openshift/openshift-docs/pull/13878/files#diff-99eeb6425c261c0f96653039df58187866a5429c67f34e40c6364f0bd3d5e6a0L10

@mburke5678 The feature names caught my attention here because they are in PascalCase, whereas the feature name (:FeatureName: variable) example linked in the guidelines is spelled out.

@lbarbeevargas The Pascal case spelling is the common usage on the internet. But, the Kubernetes docs use Pascal case in the feature gates docs and Pod PID limits in the release notes.
What if we go with both, too? Pod PID limits (SupportPodPidsLimit)

I haven't come across this situation before, but LGTM if it makes sense to the other reviewers. 👍 If going with the dual format, the first bullet can be updated as well:

link:https://kubernetes.io/docs/reference/command-line-tools-reference/kubelet-tls-bootstrapping/#certificate-rotation[Certificate rotation (RotateKubeletServerCertificate)]. Enables the rotation of the server TLS certificate on the kubelet.

lbarbeevargas · 2021-04-09T19:43:12Z

modules/nodes-cluster-enabling-features-cli.adoc

s/Feature Gate CR/FeatureGate CR/

lbarbeevargas · 2021-04-09T20:25:25Z

modules/nodes-cluster-enabling-features-console.adoc

Same feedback as for the CLI module: s/enable feature sets for all the nodes/enable feature sets for all of the nodes/
or
/enable feature sets for all nodes/

lbarbeevargas · 2021-04-09T20:29:16Z

modules/nodes-cluster-enabling-features-console.adoc

Small nit for these two bullets:

IPv6DualStackNoUpgrade enables the dual-stack networking mode.

TechPreviewNoUpgrade enables specific Technology Preview features.

lbarbeevargas · 2021-04-09T20:29:49Z

modules/nodes-cluster-enabling-features-cli.adoc

Small nit for these two bullets:

IPv6DualStackNoUpgrade enables the dual-stack networking mode.

TechPreviewNoUpgrade enables specific Technology Preview features.

lbarbeevargas · 2021-04-09T20:31:16Z

modules/nodes-cluster-enabling-features-about.adoc

Should the full assembly path be here? nodes/clusters/nodes-cluster-enabling-features.adoc

Good catch. I moved these files around a lot when converting from 3.11 to 4.x. I'm sure there are others just like this,

lbarbeevargas · 2021-04-09T20:31:44Z

modules/nodes-cluster-enabling-features-console.adoc

Should the full assembly path be here? nodes/clusters/nodes-cluster-enabling-features.adoc

lbarbeevargas · 2021-04-09T20:35:57Z

post_installation_configuration/cluster-tasks.adoc

s/FeatureGates/feature gates/

lbarbeevargas · 2021-04-09T20:41:47Z

post_installation_configuration/cluster-tasks.adoc

Small rewording suggestion:

You can enable Technology Preview features for all nodes in your cluster by editing the FeatureGate custom resource in the openshift-config project.

mburke5678 · 2021-04-12T15:19:01Z

Separate PR required for 4.5 as LatencySensitive is still required for Topology Manager.

lyman9966 · 2021-04-13T07:58:57Z

the Topololgy Manager part LGTM. I mean for bug https://bugzilla.redhat.com/show_bug.cgi?id=1921160

sferich888 · 2021-04-15T19:46:41Z

modules/nodes-cluster-features-about.adoc

I don't think we want to remove this.

@sferich888 I renamed this module for consistency. This sentence is still in the docs: https://github.com/openshift/openshift-docs/pull/24132/files#diff-17f46d9305040639ceb3dfbc0f5bc64625da1d3b3174750c4b2f377abaf90bb5R10

mburke5678 · 2021-04-23T19:32:02Z

New TP features for 4.8??
https://issues.redhat.com/browse/STOR-361

openshift-ci-robot added the size/M Denotes a PR that changes 30-99 lines, ignoring generated files. label Jul 23, 2020

openshift-ci-robot added the needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. label Oct 22, 2020

mburke5678 force-pushed the fix-feature-gate-numbers branch from fb8a7fd to f07a670 Compare October 22, 2020 20:57

openshift-ci-robot added size/L Denotes a PR that changes 100-499 lines, ignoring generated files. and removed needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. size/M Denotes a PR that changes 30-99 lines, ignoring generated files. labels Oct 22, 2020

mburke5678 mentioned this pull request Oct 22, 2020

FeatureGate documentation is incomplete and incomprehensible #24849

Closed

sttts reviewed Oct 23, 2020

View reviewed changes

modules/nodes-cluster-enabling-features-cli.adoc Outdated

Copy link

sttts Oct 23, 2020

Choose a reason for hiding this comment

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

how do I know the set of feature gates I can set?

sttts reviewed Oct 23, 2020

View reviewed changes

modules/nodes-cluster-enabling-features-cluster.adoc Outdated

Copy link

sttts Oct 23, 2020

Choose a reason for hiding this comment

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

there is no easier way than this to reach a config CR? @jhadvig can you confirm?

sttts reviewed Oct 23, 2020

View reviewed changes

modules/nodes-cluster-enabling-features-cluster.adoc Outdated

Copy link

sttts Oct 23, 2020

Choose a reason for hiding this comment

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

same as above: this needs a link to all possible values.

sttts reviewed Oct 23, 2020

View reviewed changes

modules/nodes-cluster-features-about.adoc Outdated

Copy link

sttts Oct 23, 2020

Choose a reason for hiding this comment

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

double "enables"

lyman9966 reviewed Oct 29, 2020

View reviewed changes

mburke5678 changed the title ~~updating feature gates in master to match branches~~ updating feature gates docs Nov 10, 2020

mburke5678 commented Nov 10, 2020

View reviewed changes

modules/nodes-cluster-features-about.adoc Outdated

Copy link

Contributor Author

mburke5678 Nov 10, 2020

Choose a reason for hiding this comment

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

The following is commented-out. No need for review at this time

mburke5678 force-pushed the fix-feature-gate-numbers branch 2 times, most recently from e1a745b to 43206be Compare January 4, 2021 19:16

openshift-ci-robot added the lgtm Indicates that a PR is ready to be merged. label Apr 8, 2021

mburke5678 force-pushed the fix-feature-gate-numbers branch from 18d9386 to 81adaa2 Compare April 9, 2021 14:45

openshift-ci-robot removed the lgtm Indicates that a PR is ready to be merged. label Apr 9, 2021

mburke5678 force-pushed the fix-feature-gate-numbers branch from 81adaa2 to 98153c1 Compare April 9, 2021 18:26

mburke5678 added branch/enterprise-4.5 branch/enterprise-4.6 branch/enterprise-4.7 branch/enterprise-4.8 labels Apr 9, 2021

mburke5678 added this to the Next Release milestone Apr 9, 2021

mburke5678 force-pushed the fix-feature-gate-numbers branch from 98153c1 to 3d7df4a Compare April 9, 2021 19:12

lbarbeevargas reviewed Apr 9, 2021

View reviewed changes

lbarbeevargas added the peer-review-done Signifies that the peer review team has reviewed this PR label Apr 9, 2021

mburke5678 removed the branch/enterprise-4.5 label Apr 12, 2021

mburke5678 force-pushed the fix-feature-gate-numbers branch from d1d10f4 to 7ea7680 Compare April 12, 2021 15:35

sferich888 reviewed Apr 15, 2021

View reviewed changes

updating feature gates in master to match branches

d146cbf

mburke5678 force-pushed the fix-feature-gate-numbers branch from b019185 to d146cbf Compare April 30, 2021 15:32

mburke5678 merged commit 86a4054 into openshift:master May 6, 2021

mburke5678 deleted the fix-feature-gate-numbers branch May 6, 2021 16:05

openshift deleted a comment from openshift-cherrypick-robot May 6, 2021

This was referenced May 6, 2021

[enterprise-4.6] updating feature gates docs #32277

Merged

[enterprise-4.8] updating feature gates docs #32280

Merged

[enterprise-4.7] updating feature gates docs #32281

Merged

lpettyjo mentioned this pull request Jun 10, 2021

OSDOC-1175 Migration #31774

Merged

updating feature gates docs #24132

updating feature gates docs #24132

Uh oh!

Conversation

mburke5678 commented Jul 23, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mburke5678 commented Oct 22, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sttts commented Oct 23, 2020

Uh oh!

mburke5678 commented Oct 28, 2020

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sttts commented Nov 2, 2020

Uh oh!

lyman9966 commented Nov 3, 2020

Uh oh!

mburke5678 commented Nov 3, 2020

Uh oh!

mburke5678 commented Nov 3, 2020

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mburke5678 commented Dec 3, 2020

Uh oh!

mburke5678 commented Dec 8, 2020

Uh oh!

mburke5678 commented Jan 4, 2021

Uh oh!

mburke5678 commented Mar 18, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

sferich888 commented Mar 30, 2021

Uh oh!

mburke5678 commented Mar 30, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

netlify bot commented Mar 30, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

openshift-ci-robot commented Apr 9, 2021

Uh oh!

lbarbeevargas left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

mburke5678 commented Jul 23, 2020 •

edited

Loading

mburke5678 commented Oct 22, 2020 •

edited

Loading

mburke5678 commented Mar 18, 2021 •

edited

Loading

mburke5678 commented Mar 30, 2021 •

edited

Loading

netlify bot commented Mar 30, 2021 •

edited

Loading

lbarbeevargas Apr 12, 2021 •

edited

Loading