search

kubernetes / website

Kubernetes website and documentation repo:
https://kubernetes.io
Creative Commons Attribution 4.0 International
4.51k stars 14.46k forks source link

Inconsistent documentation of default StorageClass #42288

Open Nuru opened 1 year ago

Nuru commented 1 year ago

The documentation page "Change the default Storage Class" has a significant inconsistency regarding having more than one StorageClass marked as default.

"Changing the default StorageClass -> Mark a StorageClass as default" says:

Please note that at most one StorageClass can be marked as default. If two or more of them are marked as default, a PersistentVolumeClaim without storageClassName explicitly specified cannot be created.

The above is wrong as far as I know, and it is also contradicted by Storage Classes, which says:

The cluster can only have one default StorageClass. If more than one default StorageClass is accidentally set, the newest default is used when the PVC is dynamically provisioned.

See also https://github.com/kubernetes/website/issues/42413

Update

Also in need of updating:

This admission controller does not do anything when no default storage class is configured. When more than one storage class is marked as default, it rejects any creation of PersistentVolumeClaim with an error and an administrator must revisit their StorageClass objects and mark only one as default.

I believe this was correct for Kubernetes 1.25 (and several earlier versions) but is wrong as of Kubernetes 1.26. See https://github.com/kubernetes/kubernetes/pull/110559

If more than one default is specified, the admission plugin forbids the creation of all PVCs.

Which again I believe is wrong as of Kubernetes 1.26.

Summary of Affected pages

The following are links to the current documentation page and the v1.26 version of pages affected by the issue and therefore in need of updating. Likely all versions in between also need to be updated.

Administration Tasks

Admission Controllers

Persistent volumes

k8s-ci-robot commented 1 year ago

This issue is currently awaiting triage.

SIG Docs takes a lead on issue triage for this website, but any Kubernetes member can accept issues by applying the triage/accepted label.

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](https://git.k8s.io/community/contributors/guide/pull-requests.md). If you have questions or suggestions related to my behavior, please file an issue against the [kubernetes/test-infra](https://github.com/kubernetes/test-infra/issues/new?title=Prow%20issue:) repository.
dipesh-rawat commented 1 year ago

(Updated list) Pages reported in issue:

/language en

dipesh-rawat commented 1 year ago

/sig storage

Nuru commented 1 year ago

After further research, based on https://github.com/kubernetes/kubernetes/pull/110559, I believe the correct documentation is:

Prior to Kubernetes 1.26, if more than one StorageClass is marked as default, a PersistentVolumeClaim without storageClassName explicitly specified cannot be created. In Kubernetes 1.26 and later, if more than one StorageClass is marked as default, the last one created will be used.

Please have someone with detailed knowledge confirm, and then update the documentation accordingly.

basuarunava commented 1 year ago

/assign

Nuru commented 1 year ago

@dipesh-rawat Please amend this Issue to note the following pages are also affected:

Admission Controllers

Persistent volumes

@Affan-7 This is not a duplicate of #42176, it is a superset of it, and will not be completely fixed by #42177.

k8s-triage-robot commented 10 months ago

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

This bot triages un-triaged issues according to the following rules:

You can:

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

/lifecycle stale

k8s-triage-robot commented 9 months ago

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

This bot triages un-triaged issues according to the following rules:

You can:

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

/lifecycle rotten

Nuru commented 9 months ago

/remove-lifecycle rotten

Nuru commented 9 months ago

@Affan-7 Please note that you are incorrect in marking this a duplicate of #42176. Although the subject matter is the same, the specific piece of documentation that needs to be revised is different, and still incorrect even after #42177 has been applied.

Affan-7 commented 9 months ago

@Affan-7 Please note that you are incorrect in marking this a duplicate of #42176. Although the subject matter is the same, the specific piece of documentation that needs to be revised is different, and still incorrect even after #42177 has been applied.

Sure I have deleted the comment.

k8s-triage-robot commented 6 months ago

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

This bot triages un-triaged issues according to the following rules:

You can:

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

/lifecycle stale

Nuru commented 6 months ago

/remove-lifecycle stale

sftim commented 3 months ago

Also see https://github.com/kubernetes/website/issues/47297#issuecomment-2255754589

… https://kubernetes.io/docs/concepts/storage/dynamic-provisioning/#defaulting-behavior

"Note that if you set the storageclass.kubernetes.io/is-default-class annotation to true on more than one StorageClass in your cluster, and you then create a PersistentVolumeClaim with no storageClassName set, Kubernetes uses the most recently created default StorageClass."

sftim commented 3 months ago

Contributors are welcome to work on this issue. See https://k8s.io/docs/contribute/docs/ for a guide on getting started, if that's helpful.

iheartNathan commented 1 month ago

/assign