website Inconsistent documentation of default StorageClass

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:

Admission Controllers says:

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

Persistent Volumes says (with respect to the DefaultStorageClass admission plugin):

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

https://kubernetes.io/docs/tasks/administer-cluster/change-default-storage-class/
https://v1-26.docs.kubernetes.io/docs/tasks/administer-cluster/change-default-storage-class/

Admission Controllers

https://kubernetes.io/docs/reference/access-authn-authz/admission-controllers/#defaultstorageclass
https://v1-26.docs.kubernetes.io/docs/reference/access-authn-authz/admission-controllers/#defaultstorageclass

Persistent volumes

https://kubernetes.io/docs/concepts/storage/persistent-volumes/#class-1
https://v1-26.docs.kubernetes.io/docs/concepts/storage/persistent-volumes/#class-1

Jul 29 '23 22:07 Nuru

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. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

Jul 29 '23 22:07 k8s-ci-robot

(Updated list) Pages reported in issue:

https://kubernetes.io/docs/tasks/administer-cluster/change-default-storage-class/
https://kubernetes.io/docs/concepts/storage/storage-classes/
https://kubernetes.io/docs/reference/access-authn-authz/admission-controllers/
https://kubernetes.io/docs/concepts/storage/persistent-volumes/

/language en

Jul 29 '23 23:07 dipesh-rawat

/sig storage

Jul 29 '23 23:07 dipesh-rawat

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.

Jul 30 '23 08:07 Nuru

/assign

Jul 31 '23 01:07 basuarunava

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

Admission Controllers

https://kubernetes.io/docs/reference/access-authn-authz/admission-controllers/#defaultstorageclass
https://v1-26.docs.kubernetes.io/docs/reference/access-authn-authz/admission-controllers/#defaultstorageclass

Persistent volumes

https://kubernetes.io/docs/concepts/storage/persistent-volumes/#class-1
https://v1-26.docs.kubernetes.io/docs/concepts/storage/persistent-volumes/#class-1

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

Aug 05 '23 21:08 Nuru

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

This bot triages un-triaged 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:

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

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

/lifecycle stale

Jan 25 '24 22:01 k8s-triage-robot

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:

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 as fresh with /remove-lifecycle rotten
Close this issue with /close
Offer to help out with Issue Triage

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

/lifecycle rotten

Feb 24 '24 22:02 k8s-triage-robot

/remove-lifecycle rotten

Feb 25 '24 21:02 Nuru

@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.

Feb 25 '24 21:02 Nuru

@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.

Feb 26 '24 04:02 Affan-7

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

This bot triages un-triaged 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:

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

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

/lifecycle stale

May 26 '24 05:05 k8s-triage-robot

/remove-lifecycle stale

May 26 '24 20:05 Nuru

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."

Jul 29 '24 15:07 sftim

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.

Jul 29 '24 16:07 sftim

/assign

Oct 04 '24 21:10 iheartnathan

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

This bot triages un-triaged 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:

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

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

/lifecycle stale

Jan 02 '25 22:01 k8s-triage-robot

/remove-lifecycle stale

Jan 03 '25 01:01 Nuru