Feature gates reference documentation

[tengqm]

This adds a reference document for feature-gates.

---

This change is 

[k8sio-netlify-preview-bot]

Deploy preview for kubernetes-io-master-staging ready!

Built with commit 4db0bcb

https://deploy-preview-6364--kubernetes-io-master-staging.netlify.com

[chenopis]

@tengqm This is great, but how do we keep this up-to-date for every release?

[chenopis]

A couple minor issues.

[chenopis]

I would title this "Using a feature".

[chenopis]

I'm seeing an issue w/ the CSS where it's clipping off the right end of the table (see below screenshot). Consider moving the Since and Till columns to the left, after Stage, because I think it's more important for them to be seen. Also, consider renaming "Till" to "Until" so that it is more clear, especially to non-native English speakers.

[tengqm]

@chenopis My understanding of this ... is about open source. When a doc/software is useful, it will be maintained by the community, otherwise it will be outdated anyway and someone will propose to remove it.

[chenopis]

@tengqm Ok, I just want to make sure we don't have inaccurate information on the website. We may need to add this to the docs release process to make sure it has been checked and updated.

[chenopis]

@steveperry-53 You have any thoughts on this?

[steveperry-53]

@chenopis If we add a note about this to our release process, then I think it's fine to publish this.

[steveperry-53]

@vishh @Random-Liu @tallclair Can one of you do a tech review, or suggest another person who would be the appropriate reviewer? Thanks.

[tengqm]

@chenopis If we have a doc release process to ensure inaccurate contents are cleaned up, that would be great.

[msau42]

Instead of setting the flag per component, can we just say to enable the feature gate on all components? It is much simpler to remember and maintain

[tengqm]

@msau42 Well I'm seeing benefits from both ends. Turning on/off a feature-gate across all components could be a preferred option during initial set up; for most administrators, this saves a lot headache on remembering the exact mapping between features and components. However, starting from day 2, there will be needs to tune your cluster for behaviors. People will prefer knowing exactly which components need a change to turn something on, instead of changing the command lines and rolling out to all nodes. For example, if the feature to toggle only concerns with the scheduler, you will want to just tune that component instead of restarting all kubelets.

[steveperry-53]

It looks like we still need tech review/approval. @nikhita Can you approve this?

[steveperry-53]

@chenopis @tengqm I added a note about this to our Release Playbook.

[tengqm]

@steveperry-53 Thanks for including this into the playbook

[nikhita]

It looks like we still need tech review/approval. @nikhita Can you approve this?

Deferring to @liggitt since he worked on alpha fields/feature gates docs in the past.

[liggitt]

I'm skeptical this table will ever be up to date. It's fine to have the list of feature gates and associated descriptions (tag feature gate owners as identified in https://github.com/kubernetes/kubernetes/blob/master/pkg/features/kube_features.go#L28 for summaries in this doc)

I also think it is misadvised to try to document the matrix of which components make use of which gates. The cluster should have a consistent view of which features are enabled, so I'd expect cluster administrators to decide what features they want, and pass the same --feature-gates value to all components.

[tengqm]

@liggitt
Regarding whether the same --feature-gates should be applied to all components, I have posted my thoughts here: #6364 (comment)

Regarding how to keep this up to date, Steve has added this to the release playbook so team will check if the table is up to date before doing new releases.

[liggitt]

Regarding how to keep this up to date, Steve has added this to the release playbook so team will check if the table is up to date before doing new releases.

That can catch if a new feature gate was added, but if there's no automated process for sweeping the whole code base for every use of every feature gate, and tracking the call trees for those to determine which components are affected by it, the table that indicates which components use which gates will be inaccurate.

[liggitt]

To be clear, I'm in favor of the list of gates and associated descriptions, just not maintaining the matrix of all gates and all components

[tengqm]

@liggitt Based on the efforts made to compile the table, I have to admit that keeping the maps to components would be difficult, if possible at all. The initial table cost my several days. Given that there is no easy way to automatically produce such a matrix, I'm removing the component columns in the PR. Hopefully, someday we can have a better solution.

[zacharysarah]

@liggitt 👋 Given the discussion and follow-up, does this PR look good to you?

@tengqm 👋 If @liggitt gives an /lgtm, are you ready for this PR to merge?

[liggitt]

the amount of information lgtm. I didn't review for accuracy.

[tengqm]

@zacharysarah yes.

[zacharysarah]

/lgtm

[k8s-ci-robot]

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: tengqm, zacharysarah

The full list of commands accepted by this bot can be found here.

Needs approval from an approver in each of these OWNERS Files:

• OWNERS [zacharysarah]

You can indicate your approval by writing /approve in a comment
You can cancel your approval by writing /approve cancel in a comment