Improve k8s storage CSI topology docs for multi topology volumes

[saad-ali]

This is a Bug Report

Problem:

@SandeepPissay was asking how in k8s one can ask for a volume that is accessible for more than one topological segment (e.g. from >1 zones).

After discussing, I believe there is room for improvement the Kubernetes docs for allowedTopologies.matchLabelExpressions.values.

For background, the number of topologies a provisioned volume is accessible from is not controlled by a first class field in CSI or Kubernetes. Instead, it is passed as an opaque StorageClass parameter (e.g. replication-type for GCE PD in the example below). CSI drivers use TopologyRequirement at volume provision time as a set of constraints and pick one or more topologies based on the type of volume being provisioned. IMO the CSI spec is fairly clear about this, but the k8s documentation is not. It currently reads as follows:

allowedTopologies.matchLabelExpressions.values ([]string), required

An array of string values. One value must match the label to be selected. Each entry in Values is ORed.

Example

StorageClass for Regional GCE PD ```yaml kind: StorageClass apiVersion: storage.k8s.io/v1 metadata: name: regionalpd-storageclass provisioner: pd.csi.storage.gke.io parameters: type: pd-standard replication-type: regional-pd volumeBindingMode: WaitForFirstConsumer allowedTopologies: - matchLabelExpressions: - key: topology.gke.io/zone values: - europe-west1-b - europe-west1-c ```

CC @msau42 @xing-yang @bswartz

Proposed Solution:

This should probably be updated to match the CSI wording at least one or something similar.

Page to Update: https://kubernetes.io/docs/reference/kubernetes-api/config-and-storage-resources/storage-class-v1

[sftim]

/triage accepted /sig storage /priority backlog

/lifecycle frozen (we should do this at some point)

[sftim]

https://kubernetes.io/docs/reference/kubernetes-api/config-and-storage-resources/storage-class-v1 is generated documentation.

We should improve https://kubernetes.io/docs/concepts/storage/storage-classes/ and we should also tweak the upstream code in k/kubernetes that defines the StorageClass API.

[SandeepPissay]

@saad-ali Thanks for filing this issue!

[k8s-triage-robot]

This issue has not been updated in over 1 year, and should be re-triaged.

You can:

• Confirm that this issue is still relevant with /triage accepted (org members only)
• Close this issue with /close

For more details on the triage process, see https://www.kubernetes.dev/docs/guide/issue-triage/

/remove-triage accepted

[natalisucks]

/triage accepted

I agree with the current frozen lifecycle status, and would welcome folks to check @sftim's comment about tweaking the upstream code for this generated documentation