kubernetes / kubernetes/website
Improve k8s storage CSI topology docs for multi topology volumes
- Dominant language
- HTML
- Stars
- 5.4k
- Forks
- 15.7k
- Avg merge
- 4d 18h
- Merged PRs (30d)
- 204
Description
**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](https://kubernetes.io/docs/reference/kubernetes-api/config-and-storage-resources/storage-class-v1/):
```
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
Contributor guide
Assessment
This issue has not been assessed yet.