Inconsistent documentation of default StorageClass

[Nuru]

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 #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 kubernetes/kubernetes#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

[k8s-ci-robot]

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.

[dipesh-rawat]

(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

[dipesh-rawat]

/sig storage

[Nuru]

After further research, based on kubernetes/kubernetes#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]

/assign

[Nuru]

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

[k8s-triage-robot]

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

[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

[Nuru]

/remove-lifecycle rotten

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

[Affan-7]

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

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

[Nuru]

/remove-lifecycle stale

[sftim]

Also see #47297 (comment)

… 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]

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]

/assign