Add documentation for “non exhaustive enums”

[sftim]

What happened?

Following a bugfix, we now have a gap where these non-exhaustive, enum-like field values are not documented. Folks will previously have found those explanations useful.

See kubernetes/website#32833 (review) for an example where the v1.23 docs enumerate taint effects and list meanings (NoExecute, NoSchedule and PreferNoSchedule) but the v1.24 docs won't.

https://kubernetes.io/docs/reference/kubernetes-api/cluster-resources/node-v1/#NodeSpec is the URL of the v1.23 docs at the time of writing; that will soon change to be https://v1-23.docs.kubernetes.io/docs/reference/kubernetes-api/cluster-resources/node-v1/

What did you expect to happen?

What I hoped for: API reference information covers known field values, even when the field values known to Kubernetes are not exhaustive.

Aside: I think there are multiple ways to tackle this issue. I don't have a strong view on which might be the best approach.

How can we reproduce it (as minimally and precisely as possible)?

(After the v1.24 release) look at the API reference for Node. See if the possible effects are enumerated and explained.

Anything else we need to know?

This issue covers 3 repos:

• k/kubernetes
• k/website
• k-sigs/reference-docs

Kubernetes version

v1.24

Cloud provider

Netlify 😉

OS version

not applicable

Install tools

not applicable

Container runtime (CRI) and version (if applicable)

not applicable

Related plugins (CNI, CSI, ...) and versions (if applicable)

not applicable

[k8s-ci-robot]

@sftim: This issue is currently awaiting triage.

If a SIG or subproject determines this is a relevant issue, they will accept it by applying the triage/accepted label and provide further guidance.

The triage/accepted label can be added by org members by writing /triage accepted in a comment.

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/test-infra repository.

[sftim]

/wg api-expression
/sig docs
/remove-kind bug
/kind feature

[liggitt]

Note that the inclusion of these in 1.23 docs was an accident... the feature was in alpha state and should not have been enabled in 1.23. The openapi file in release-1.23 and master branches once again has the same amount of information as the API definition in release-1.22

[sftim]

Ah, got it.

Definitely a feature request, then.

[tengqm]

The most relevant reason why enums were removed from docs sound like the CSR test cases. I'm wondering if that is something we need to fix rather than dropping enums from docs. Without this information, users have no idea what values are acceptable for those fields.

The enum feature was discussed at least five years ago, IIRC, and it was rejected because ... the APIs are evolving. However, I don't see that a valid argument. All APIs are evolving, new enum values can be added or removed in the next release. From API's perspective, enum values are always integral parts of the API, versioned, and they should be documented.

[shikha-varun]

I am a beginner and willing to work on with some guidance if fine please assign to me

[k8s-triage-robot]

The Kubernetes project currently lacks enough contributors to adequately respond to all issues and PRs.

This bot triages issues and PRs according to the following rules:

• After 90d of inactivity, lifecycle/stale is applied
• After 30d of inactivity since lifecycle/stale was applied, lifecycle/rotten is applied
• After 30d of inactivity since lifecycle/rotten was applied, the issue is closed

You can:

• Mark this issue or PR as fresh with /remove-lifecycle stale
• Mark this issue or PR as rotten with /lifecycle rotten
• Close this issue or PR with /close
• Offer to help out with Issue Triage

Please send feedback to sig-contributor-experience at kubernetes/community.

/lifecycle stale

[k8s-triage-robot]

The Kubernetes project currently lacks enough active contributors to adequately respond to all issues and PRs.

This bot triages issues and PRs according to the following rules:

• After 90d of inactivity, lifecycle/stale is applied
• After 30d of inactivity since lifecycle/stale was applied, lifecycle/rotten is applied
• After 30d of inactivity since lifecycle/rotten was applied, the issue is closed

You can:

• Mark this issue or PR as fresh with /remove-lifecycle rotten
• Close this issue or PR with /close
• Offer to help out with Issue Triage

Please send feedback to sig-contributor-experience at kubernetes/community.

/lifecycle rotten

[sftim]

/remove-lifecycle rotten
/retitle Add documentation for “non exhaustive enums”

[k8s-triage-robot]

The Kubernetes project currently lacks enough contributors to adequately respond to all issues and PRs.

This bot triages issues and PRs according to the following rules:

• After 90d of inactivity, lifecycle/stale is applied
• After 30d of inactivity since lifecycle/stale was applied, lifecycle/rotten is applied
• After 30d of inactivity since lifecycle/rotten was applied, the issue is closed

You can:

• Mark this issue or PR as fresh with /remove-lifecycle stale
• Mark this issue or PR as rotten with /lifecycle rotten
• Close this issue or PR with /close
• Offer to help out with Issue Triage

Please send feedback to sig-contributor-experience at kubernetes/community.

/lifecycle stale

[k8s-triage-robot]

The Kubernetes project currently lacks enough active contributors to adequately respond to all issues and PRs.

This bot triages issues and PRs according to the following rules:

• After 90d of inactivity, lifecycle/stale is applied
• After 30d of inactivity since lifecycle/stale was applied, lifecycle/rotten is applied
• After 30d of inactivity since lifecycle/rotten was applied, the issue is closed

You can:

• Mark this issue or PR as fresh with /remove-lifecycle rotten
• Close this issue or PR with /close
• Offer to help out with Issue Triage

Please send feedback to sig-contributor-experience at kubernetes/community.

/lifecycle rotten

[k8s-triage-robot]

The Kubernetes project currently lacks enough active contributors to adequately respond to all issues and PRs.

This bot triages issues according to the following rules:

• After 90d of inactivity, lifecycle/stale is applied
• After 30d of inactivity since lifecycle/stale was applied, lifecycle/rotten is applied
• After 30d of inactivity since lifecycle/rotten was applied, the issue is closed

You can:

• Reopen this issue with /reopen
• Mark this issue as fresh with /remove-lifecycle rotten
• Offer to help out with Issue Triage

Please send feedback to sig-contributor-experience at kubernetes/community.

/close not-planned

[k8s-ci-robot]

@k8s-triage-robot: Closing this issue, marking it as "Not Planned".

In response to this:

The Kubernetes project currently lacks enough active contributors to adequately respond to all issues and PRs.

This bot triages issues according to the following rules:

• After 90d of inactivity, lifecycle/stale is applied
• After 30d of inactivity since lifecycle/stale was applied, lifecycle/rotten is applied
• After 30d of inactivity since lifecycle/rotten was applied, the issue is closed

You can:

• Reopen this issue with /reopen
• Mark this issue as fresh with /remove-lifecycle rotten
• Offer to help out with Issue Triage

Please send feedback to sig-contributor-experience at kubernetes/community.

/close not-planned

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/test-infra repository.