kubernetes / kubernetes/website

Improve k8s storage CSI topology docs for multi topology volumes

Open
#30,237 8 comments 0 reactions 1 assignee Claimed by @mogfrey View on GitHub
kind/bug language/en lifecycle/frozen priority/backlog sig/storage triage/accepted
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.