Skip to content

Commit 1c71689

Browse files
author
sai chaithanya
authored
chore(doc): update conformance matrix of SC & PVC (#84)
 Signed-off-by: mittachaitu <[email protected]>
1 parent 3094524 commit 1c71689

File tree

2 files changed

+227
-32
lines changed

2 files changed

+227
-32
lines changed

‎docs/persistentvolumeclaim.md‎

Lines changed: 78 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -2,20 +2,79 @@
22

33
Following matrix shows supported PersistentVolumeClaim parameters for lvm-localpv.
44

5-
| PersistentVolumeClaim Parameters | LVM CSI Driver | E2E Coverage |
6-
| -------------------------------- | -------------- | ------------ |
7-
| [AccessMode](#accessmode) <br> Supported access modes are <li> ReadWriteOnce </li> </br> | Supported | [Yes](https://github.com/openebs/lvm-localpv/tree/master/e2e-tests/experiments/lvm-localpv-provisioner#readme) |
8-
| [Storageclass](#storageclassname) | Supported | [Yes](https://github.com/openebs/lvm-localpv/tree/master/e2e-tests/experiments/lvm-localpv-provisioner#readme) |
9-
| [Capacity Resource](#capacity-resource) | Supported | Yes |
10-
| [VolumeMode](#volumemode) <br> Supported volume modes are <li> Block </li> <li> Filesystem </li> </br> | Supported | Yes <br> Test cases available for Filesystem mode </br>|
11-
| [Selectors](#selectors) | Supported | Pending |
12-
| [VolumeName](#volumename) | Supported | Pending |
5+
<table>
6+
<thead>
7+
<tr>
8+
<th> Parameter </th>
9+
<th> Values </th>
10+
<th> Development Status </th>
11+
<th> E2E Coverage Status </th>
12+
</tr>
13+
</thead>
14+
<tbody>
15+
<tr>
16+
<td rowspan=3> <a href="#accessmode"> AccessMode </a> </td>
17+
<td> ReadWriteOnce </td>
18+
<td> Supported </td>
19+
<td rowspan=3> <a href="https://github.com/openebs/lvm-localpv/tree/master/e2e-tests/experiments/lvm-localpv-provisioner#readme"> Yes </a> </td>
20+
</tr>
21+
<tr>
22+
<td> <strike> ReadWriteMany </strkie> </td>
23+
<td> Not Supported </td>
24+
</tr>
25+
<tr>
26+
<td> <strike> ReadOnlyMany </strike> </td>
27+
<td> Not Supported </td>
28+
</tr>
29+
<tr>
30+
<td> <a href="#storageclassname"> Storageclass </td>
31+
<td> StorageClassName </td>
32+
<td> Supported </td>
33+
<td> <a href="https://github.com/openebs/lvm-localpv/tree/master/e2e-tests/experiments/lvm-localpv-provisioner#readme"> Yes </a> </td>
34+
</tr>
35+
<tr>
36+
<td> <a href="#capacity-resource"> Capacity Resource </a> </td>
37+
<td> Number along with size unit </td>
38+
<td> Supported </td>
39+
<td> <a href="https://github.com/openebs/lvm-localpv/tree/master/e2e-tests/experiments/functional/lvm-volume-resize#readme"> Yes </a> </td>
40+
</tr>
41+
<tr>
42+
<td rowspan=2> <a href="#volumemode-optional"> VolumeMode </a> </td>
43+
<td> Block </td>
44+
<td> Supported </td>
45+
<td rowspan=2> <a href="https://github.com/openebs/lvm-localpv/blob/master/e2e-tests/apps/percona/deployers/run_e2e_test.yml"> Yes </a> <br> <i> Test cases available for Filesystem mode </i> </br> </td>
46+
</tr>
47+
<tr>
48+
<td> Filesystem </td>
49+
<td> Supported </td>
50+
</tr>
51+
<tr>
52+
<td> <a href="#selectors-optional"> Selectors </a> </td>
53+
<td> Equality & Set based selections </td>
54+
<td> Supported </td>
55+
<td> Pending </td>
56+
</tr>
57+
<tr>
58+
<td> <a href="#volumename-optional"> VolumeName </a> </td>
59+
<td> Available PV name </td>
60+
<td> Supported </td>
61+
<td> Pending </td>
62+
</tr>
63+
<tr>
64+
<td> DataSource </td>
65+
<td> - </td>
66+
<td> Not Supported </td>
67+
<td> Pending </td>
68+
</tr>
69+
</tbody>
70+
</table>
71+
1372

1473
## PersistentVolumeClaim Parameters
1574

1675
### AccessMode
1776

18-
LVM-LocalPV supports only `ReadWriteOnce` access mode i.e volume can be mounted as read-write by a single node.
77+
LVM-LocalPV supports only `ReadWriteOnce` access mode i.e volume can be mounted as read-write by a single node. AccessMode is a required field, if the field is unspecified then it will lead to a creation error.
1978
```yaml
2079
kind: PersistentVolumeClaim
2180
apiVersion: v1
@@ -32,7 +91,7 @@ spec:
3291
3392
### StorageClassName
3493
35-
LVM CSI-Driver supports dynamic provision of volume for the PVCs refered to lvm storageclass.
94+
LVM CSI-Driver supports dynamic provision of volume for the PVCs referred to lvm storageclass. StorageClassName is a required field, if field is unspecified then it will lead to a provision errors.
3695
3796
```yaml
3897
kind: PersistentVolumeClaim
@@ -50,7 +109,7 @@ spec:
50109
51110
### Capacity Resource
52111
53-
Admin/User can specify the desired capacity for lvm volume. Once the CSI-Driver gets request it will check whether available space in underlying volume group. If it has enough space a success respone will be returned to caller else error will be reported.
112+
Admin/User can specify the desired capacity for lvm volume. CSI-Driver will provision a volume if the underlying volume group has requested capacity available else provisioning volume will be errored. StorageClassName is a required field, if field is unspecified then it will lead to a provision errors.
54113
55114
```yaml
56115
kind: PersistentVolumeClaim
@@ -66,11 +125,12 @@ spec:
66125
storage: 4Gi ## Specify required storage for an application
67126
```
68127
69-
### VolumeMode
128+
### VolumeMode (Optional)
70129
71130
LVM-LocalPV supports two kind of volume modes(Defaults to Filesystem):
72131
- Block (Block mode can be used in a case where application itself maintains filesystem)
73132
- Filesystem (Application which requires filesystem as a prerequisite)
133+
Note: By default K8s will take volume mode as **Filesystem**.
74134
75135
```yaml
76136
kind: PersistentVolumeClaim
@@ -88,9 +148,9 @@ spec:
88148
```
89149
90150
91-
### Selectors
151+
### Selectors (Optional)
92152
93-
Users can bind any of retained lvm volumes to new PersistentVolumeClaim object via selector field.
153+
Users can bind any of retained lvm volumes to new PersistentVolumeClaim object via selector field. If selector and [volumeName](#volumename-optional) fields are unspecified then LVM CSI driver will provision new volume.
94154
Follow below steps to specify selector on PersistentVolumeClaim:
95155
96156
- List the persistentvolumes(PVs) which has status Released.
@@ -126,7 +186,7 @@ spec:
126186
- ReadWriteOnce
127187
resources:
128188
requests:
129-
storage: 4Gi
189+
storage: 4Gi ## Capacity should be less than or equal to available PV capacities
130190
```
131191
- Verify bound status of PV
132192
```sh
@@ -135,9 +195,9 @@ NAME CAPACITY ACCESS MODES RECLAIM POL
135195
pvc-8376b776-75f9-4786-8311-f8780adfabdb 6Gi RWO Retain Bound default/csi-lvmpv openebs-lvmpv 9h
136196
```
137197

138-
### VolumeName
198+
### VolumeName (Optional)
139199

140-
VolumeName can be used to bind PersistentVolumeClaim(PVC) to retained PersistentVolume(PV). When VolumeName is specified K8s will ignore selector field.
200+
VolumeName can be used to bind PersistentVolumeClaim(PVC) to retained PersistentVolume(PV). When VolumeName is specified K8s will ignore [selector field](#selectors-optional). If volumeName is unspecified then CSI driver will try to provision new volume.
141201
Note: Before creating PVC make PersistentVolume `Available` by removing claimRef on PersistentVolume.
142202
```yaml
143203
kind: PersistentVolumeClaim
@@ -151,5 +211,5 @@ spec:
151211
- ReadWriteOnce
152212
resources:
153213
requests:
154-
storage: 4Gi
214+
storage: 4Gi ## Capacity should be less than or equal to available PV capacities
155215
```

‎docs/storageclasses.md‎

Lines changed: 149 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,138 @@
11
## StorageClass Parameters Conformance matrix
22

3-
Following matrix shows supported storageclass parameters for lvm-localpv
3+
Following matrix shows standard storageclass parameters for lvm-localpv
4+
5+
### Standard StorageClass Parameters
6+
7+
<table>
8+
<tr>
9+
<th> Parameter </th>
10+
<th colspan=2> Values </th>
11+
<th> Development Status </th>
12+
<th> E2E Coverage </th>
13+
</tr>
14+
15+
<tr>
16+
<td rowspan=2> <a href="#allowvolumeexpansion-optional"> allowVolumeExpansion </a> </td>
17+
<td> true </td>
18+
<td></td>
19+
<td> Supported </td>
20+
<td rowspan=2> <a href="https://github.com/openebs/lvm-localpv/tree/master/e2e-tests/experiments/functional/lvm-volume-resize#about-this-experiment"> Yes </a> <br><i> (Test coverage exist for ext4 & xfs) </i></br> </td>
21+
</tr>
22+
<tr>
23+
<td> false </td>
24+
<td></td>
25+
<td> Supported </td>
26+
</tr>
27+
28+
<tr>
29+
<td> <a href="#mountoptions-optional"> MountOptions </a> </td>
30+
<td> Options supported by filesystem </td>
31+
<td></td>
32+
<td> Supported </td>
33+
<td> Pending </td>
34+
</tr>
35+
36+
<tr>
37+
<td rowspan=2> <a href="#volumebindingmode-optional"> VolumeBindingMode </a> </td>
38+
<td> Immediate </td>
39+
<td></td>
40+
<td> Supported </td>
41+
<td rowspan=2> <a href="https://github.com/openebs/lvm-localpv/tree/master/e2e-tests/experiments/functional/lvmpv-custom-topology#readme"> Yes </a> </td>
42+
</tr>
43+
<tr>
44+
<td> WaitForFirstConsumer </td>
45+
<td></td>
46+
<td> Supported </td>
47+
</tr>
48+
49+
<tr>
50+
<td rowspan=2> <a href="#reclaim-policy-optional"> Reclaim Policy </a> </td>
51+
<td> Retain </td>
52+
<td></td>
53+
<td> Supported </td>
54+
<td rowspan=2> <a href="https://github.com/openebs/lvm-localpv/blob/master/e2e-tests/apps/percona/deployers/run_e2e_test.yml"> Yes </a> <br> <i> (Test coverage exist for Delete reclaim policy) </i> </br> </td>
55+
</tr>
56+
<tr>
57+
<td> Delete </td>
58+
<td></td>
59+
<td> Supported </td>
60+
</tr>
61+
62+
<tr>
63+
<td> <a href="#storageclass-with-custom-node-labels"> allowedTopologies </a> </td>
64+
<td> - </td>
65+
<td></td>
66+
<td> Supported </td>
67+
<td> <a href="https://github.com/openebs/lvm-localpv/tree/master/e2e-tests/experiments/functional/lvmpv-custom-topology#readme"> Yes </a> </td>
68+
</tr>
69+
70+
<tr>
71+
<td rowspan=6> Parameters </td>
72+
<td> <a href="https://kubernetes-csi.github.io/docs/secrets-and-credentials-storage-class.html#examples"> Passing Secrets </td>
73+
<td></td>
74+
<td> No Use Case </td>
75+
<td> NA </td>
76+
</tr>
77+
<tr>
78+
<td rowspan=5> <a href="#fstype-optional"> fsType </a> </td>
79+
<td>ext2</td>
80+
<td rowspan=5> Supported </td>
81+
<td rowspan=5> <a href="https://github.com/openebs/lvm-localpv/tree/master/e2e-tests/experiments/functional/lvm-controller-high-availability#readme"> Yes </a> <br> <i> (Test coverage exist for ext4 & xfs) </i></br> </td>
82+
</tr>
83+
<tr> <td> ext3 </td> </tr>
84+
<tr> <td> ext4 </td> </tr>
85+
<tr> <td> xfs </td> </tr>
86+
<tr> <td> btrfs </td> </tr>
87+
</table>
88+
89+
### LVM Supported StorageClass Parameters
90+
91+
<table>
92+
<tr>
93+
<th> Parameter </th>
94+
<th colspan=2> Values </th>
95+
<th> Development Status </th>
96+
<th> E2E Coverage </th>
97+
</tr>
98+
99+
<tr>
100+
<td rowspan=6> Parameters </td>
101+
<td> <a href="#shared-optional"> shared </td>
102+
<td> yes </td>
103+
<td> Supported </td>
104+
<td> <a href="https://github.com/openebs/lvm-localpv/tree/master/e2e-tests/experiments/functional/lvmpv-shared-mount#readme"> Yes </a> </td>
105+
</tr>
106+
107+
<tr>
108+
<td> <a href="#vgpattern-must-parameter-if-volgroup-is-not-provided-otherwise-optional"> vgpattern </td>
109+
<td> Regular expression of volume group name </td>
110+
<td> Supported </td>
111+
<td> Pending </td>
112+
</tr>
113+
114+
<tr>
115+
<td> <a href="#volgroup-must-parameter-if-vgpattern-is-not-provided-otherwise-optional"> volgroup </td>
116+
<td> Name of volume group </td>
117+
<td> Supported </td>
118+
<td> <a href="https://github.com/openebs/lvm-localpv/blob/master/e2e-tests/experiments/lvm-localpv-provisioner/openebs-lvmsc.j2"> Yes </a> </td>
119+
</tr>
120+
121+
<tr>
122+
<td> <a href="#thinprovision-optional"> thinProvision </td>
123+
<td> yes </td>
124+
<td> Supported </td>
125+
<td> Pending </td>
126+
</tr>
127+
128+
</table>
4129

5-
| StorageClass Parameters | LVM CSI Driver | E2E Coverage |
6-
| ----------------------- | -------------- | ------------ |
7-
| [allowVolumeExpansion](#allowvolumeexpansion-optional) <br> _(Supports expansion on ext2, ext3, ext4 & xfs)_ </br> | Supported | [Yes](https://github.com/openebs/lvm-localpv/tree/master/e2e-tests/experiments/functional/lvm-volume-resize#about-this-experiment) <br> _(Test coverage exist for ext4 & xfs)_ </br> |
8-
| [MountOptions](#mountoptions-optional) | Supported | Pending |
9-
| Parameters <ol type="a"> <li> [Passing Secrets](https://kubernetes-csi.github.io/docs/secrets-and-credentials-storage-class.html#examples) </li> <li> [fsType](#fstype-optional) <br> _(Supports ext2, ext3, ext4, xfs & btrfs filesystem)_ </br> </li> <li> [shared](#shared-optional) </li> <li> [vgpattern](#vgpattern-must-parameter-if-volgroup-is-not-provided-otherwise-optional) </li> <li> [volgroup](#volgroup-must-parameter-if-vgpattern-is-not-provided-otherwise-optional) </li> <li> [thinProvision](#thinprovision-optional) </ol> | <ol type="a"> <li> No Use Case </li> <li> Supported <br> </br> </li> <li> Supported </li> <li> Supported </li> <li> Supported </li> <li> Supported </li> </ul>| <ol type="a"> <li> NA </li> <li> [Yes](https://github.com/openebs/lvm-localpv/tree/master/e2e-tests/experiments/functional/lvm-controller-high-availability#readme) <br> _(Test coverage exist for ext4 & xfs)_ </br> </li> <li> [Yes](https://github.com/openebs/lvm-localpv/tree/master/e2e-tests/experiments/functional/lvmpv-shared-mount#readme) </li> <li> Pending </li> <li> [Yes](https://github.com/openebs/lvm-localpv/blob/master/e2e-tests/experiments/lvm-localpv-provisioner/openebs-lvmsc.j2) </li> <li> Pending </li> </ol> |
10-
| Reclaim Policy <br> _(Supports Retain & Delete reclaim policy)_ </br> | Supported | Yes <br> _(Test coverage exist for Delete reclaim policy)_ </br> |
11-
| [VolumeBindingMode](#volumebindingmode-optional) <br> _(Supports Immediate & WaitForFirstConsumer modes)_ | Supported | Yes |
12-
| [allowedTopologies](#storageclass-with-custom-node-labels) | Supported | [Yes](https://github.com/openebs/lvm-localpv/tree/master/e2e-tests/experiments/functional/lvmpv-custom-topology#readme) |
13130

14131
## StorageClass Options
15132

16133
### AllowVolumeExpansion (Optional)
17134

18-
Users can expand the volumes when the underlying StorageClass `allowVolumeExpansion` field set to true.
135+
Users can expand the volumes only when `allowVolumeExpansion` field is set to true in storageclass. If a field is unspecified, then volume expansion is not supported.
19136
```yaml
20137
apiVersion: storage.k8s.io/v1
21138
kind: StorageClass
@@ -30,7 +147,7 @@ parameters:
30147
31148
### MountOptions (Optional)
32149
33-
Volumes that are provisioned via lvm-localpv will use the mount options specified in storageclass during volume mounting time.
150+
Volumes that are provisioned via LVM-LocalPV will use the mount options specified in storageclass during volume mounting time inside an application. If a field is unspecified, `-o default` option will be added to mount the volume.
34151
**Note**: Mount options are not validated. If mount options are invalid, then volume mount fails.
35152
```yaml
36153
apiVersion: storage.k8s.io/v1
@@ -51,7 +168,7 @@ LVM-LocalPV storageclass supports various parameters for different use cases. Fo
51168

52169
- #### FsType (Optional)
53170

54-
Admin can specify filesystem in storageclass. lvm-localpv CSI-Driver will format block device with specified filesystem and mount in application pod. If fsType is not specified defaults to "ext4" filesystem.
171+
Admin can specify filesystem in storageclass. LVM-LocalPV CSI-Driver will format block device with specified filesystem and mount in application pod. If fsType is not specified defaults to `ext4` filesystem.
55172
```yaml
56173
apiVersion: storage.k8s.io/v1
57174
kind: StorageClass
@@ -67,7 +184,7 @@ LVM-LocalPV storageclass supports various parameters for different use cases. Fo
67184

68185
- #### Shared (Optional)
69186

70-
lvm-localpv volume mount point can be shared among the multiple pods on the same node. Applications that can share the volume can set value of `shared` parameter to true.
187+
lvm-localpv volume mount point can be shared among the multiple pods on the same node. Applications that can share the volume can set value of `shared` parameter to yes defaults to no.
71188
```yaml
72189
apiVersion: storage.k8s.io/v1
73190
kind: StorageClass
@@ -116,7 +233,7 @@ LVM-LocalPV storageclass supports various parameters for different use cases. Fo
116233

117234
- #### thinProvision (Optional)
118235

119-
For creating thin-provisioned volume, use thinProvision parameter in storage class. It's allowed values are: "yes" and "no". If we don't use this parameter by default it's value will be "no" and it will work as thick provisioned volumes.
236+
For creating thin-provisioned volume, use thinProvision parameter in storage class. It's allowed values are: "yes" and "no". If we don't set thinProvision parameter by default it's value will be `no` and it will work as thick provisioned volumes.
120237

121238
```yaml
122239
apiVersion: storage.k8s.io/v1
@@ -158,6 +275,24 @@ parameters:
158275
volumeBindingMode: WaitForFirstConsumer ## It can also replaced by Immediate volume binding mode depends on use case.
159276
```
160277

278+
### Reclaim Policy (Optional)
279+
280+
lvm-localpv supports both types of reclaim policy that are `Delete` & `Retain`. If not specified defaults to `Delete`.
281+
- Delete: Indicates that backend volume resources(PV, LVMVolume) will be delete as soon as after deleting PVC.
282+
- Retain: Indicates backend volume resources can be recalimed by PVCs or retained the cluster.
283+
```yaml
284+
apiVersion: storage.k8s.io/v1
285+
kind: StorageClass
286+
metadata:
287+
name: openebs-lvm
288+
provisioner: local.csi.openebs.io
289+
parameters:
290+
storage: "lvm"
291+
vgpattern: "lvmvg.*"
292+
reclaimPolicy: Delete ## Reclaim policy can be specified here. It also accepts Retain
293+
```
294+
295+
161296
### StorageClass With Custom Node Labels
162297

163298
There can be a use case where we have certain kinds of Volume Groups present on certain nodes only, and we want a particular type of application to use that VG. We can create a storage class with `allowedTopologies` and mention all the nodes there where that vg is present:

0 commit comments

Comments
 (0)