Skip to content

Commit 885a06c

Browse files
saad-alisaad-ali
committed
Update Kubernetse-CSI Secret Documentation
1 parent 2dfe138 commit 885a06c

File tree

4 files changed

+313
-190
lines changed

4 files changed

+313
-190
lines changed

‎book/src/SUMMARY.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,8 @@
1616
- [CSINode Object](csi-node-object.md)
1717
- [Features](features.md)
1818
- [Secrets & Credentials](secrets-and-credentials.md)
19+
- [StorageClass Secrets](secrets-and-credentials-external-provisioner.md)
20+
- [SnapshotClass Secrets](secrets-and-credentials-external-snapshotter.md)
1921
- [Topology](topology.md)
2022
- [Raw Block Volume](raw-block.md)
2123
- [Skip Attach](skip-attach.md)

‎book/src/secrets-and-credentials-external-provisioner.md

Lines changed: 256 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,256 @@
1+
# StorageClass Secrets
2+
3+
The CSI [external-provisioner](external-provisioner.md) sidecar container facilitates the handling of secrets for the following operations:
4+
* `CreateVolumeRequest`
5+
* `DeleteVolumeRequest`
6+
* `ControllerPublishVolumeRequest`
7+
* `ControllerUnpublishVolumeRequest`
8+
* `ControllerExpandVolumeRequest`
9+
* `NodeStageVolumeRequest`
10+
* `NodePublishVolumeRequest`
11+
12+
CSI `external-provisioner` v1.0.1+ support the following keys in `StorageClass.parameters`:
13+
14+
* `csi.storage.k8s.io/provisioner-secret-name`
15+
* `csi.storage.k8s.io/provisioner-secret-namespace`
16+
* `csi.storage.k8s.io/controller-publish-secret-name`
17+
* `csi.storage.k8s.io/controller-publish-secret-namespace`
18+
* `csi.storage.k8s.io/node-stage-secret-name`
19+
* `csi.storage.k8s.io/node-stage-secret-namespace`
20+
* `csi.storage.k8s.io/node-publish-secret-name`
21+
* `csi.storage.k8s.io/node-publish-secret-namespace`
22+
23+
CSI `external-provisioner` v1.2.0+ add support for the following keys in `StorageClass.parameters`:
24+
* `csi.storage.k8s.io/controller-expand-secret-name`
25+
* `csi.storage.k8s.io/controller-expand-secret-namespace`
26+
27+
Cluster admins can populate the secret fields for the operations listed above with data from Kubernetes `Secret` objects by specifying these keys in the `StorageClass` object.
28+
29+
## Examples
30+
31+
### Basic Provisioning Secret
32+
33+
In this example, the external-provisioner will fetch Kubernetes `Secret` object `fast-storage-provision-key` in the namespace `pd-ssd-credentials` and pass the credentials to the CSI driver named `csi-driver.team.example.com` in the `CreateVolume` CSI call.
34+
35+
```yaml
36+
kind: StorageClass
37+
apiVersion: storage.k8s.io/v1
38+
metadata:
39+
name: fast-storage
40+
provisioner: csi-driver.team.example.com
41+
parameters:
42+
type: pd-ssd
43+
csi.storage.k8s.io/provisioner-secret-name: fast-storage-provision-key
44+
csi.storage.k8s.io/provisioner-secret-namespace: pd-ssd-credentials
45+
```
46+
47+
All volumes provisioned using this `StorageClass` use the same secret.
48+
49+
### Per Volume Secrets
50+
In this example, the external-provisioner will generate the name of the Kubernetes `Secret` object and namespace for the `NodePublishVolume` CSI call, based on the PVC namespace and annotations, at volume provision time.
51+
52+
```yaml
53+
kind: StorageClass
54+
apiVersion: storage.k8s.io/v1
55+
metadata:
56+
name: fast-storage
57+
provisioner: csi-driver.team.example.com
58+
parameters:
59+
type: pd-ssd
60+
csi.storage.k8s.io/node-publish-secret-name: ${pvc.annotations['team.example.com/key']}
61+
csi.storage.k8s.io/node-publish-secret-namespace: ${pvc.namespace}
62+
```
63+
64+
This StorageClass will result in the creation of a `PersistentVolume` API object referencing a "node publish secret" in the same namespace as the `PersistentVolumeClaim` that triggered the provisioning and with a name specified as an annotation on the `PersistentVolumeClaim`. This could be used to give the creator of the `PersistentVolumeClaim` the ability to specify a secret containing a decryption key they have control over.
65+
66+
### Multiple Operation Secrets
67+
A drivers may support secret keys for multiple operations. In this case, you can provide secrets references for each operation:
68+
69+
```yaml
70+
kind: StorageClass
71+
apiVersion: storage.k8s.io/v1
72+
metadata:
73+
name: fast-storage-all
74+
provisioner: csi-driver.team.example.com
75+
parameters:
76+
type: pd-ssd
77+
csi.storage.k8s.io/provisioner-secret-name: ${pvc.name}
78+
csi.storage.k8s.io/provisioner-secret-namespace: ${pvc.namespace}-fast-storage
79+
csi.storage.k8s.io/node-publish-secret-name: ${pvc.name}-${pvc.annotations['team.example.com/key']}
80+
csi.storage.k8s.io/node-publish-secret-namespace: ${pvc.namespace}-fast-storage
81+
82+
```
83+
84+
## Operations
85+
Details for each secret supported by the external-provisioner can be found below.
86+
87+
### Create/Delete Volume Secret
88+
89+
The CSI `external-provisioner` (v1.0.1+) looks for the following keys in `StorageClass.parameters`.
90+
91+
* `csi.storage.k8s.io/provisioner-secret-name`
92+
* `csi.storage.k8s.io/provisioner-secret-namespace`
93+
94+
The values of both of these parameters, together, refer to the name and namespace of a `Secret` object in the Kubernetes API.
95+
96+
If specified, the CSI `external-provisioner` will attempt to fetch the secret before provisioning and deletion.
97+
98+
If the secret is retrieved successfully, the provisioner passes it to the CSI driver in the `CreateVolumeRequest.secrets` or `DeleteVolumeRequest.secrets` field.
99+
100+
If no such secret exists in the Kubernetes API, or the provisioner is unable to fetch it, the provision operation will fail.
101+
102+
Note, however, that the delete operation will continue even if the secret is not found (because, for example, the entire namespace containing the secret was deleted). In this case, if the driver requires a secret for deletion, then the volume and PV may need to be manually cleaned up.
103+
104+
The values of these parameters may be "templates". The `external-provisioner` will automatically resolve templates at volume provision time, as detailed below:
105+
106+
* `csi.storage.k8s.io/provisioner-secret-name`
107+
* `${pv.name}`
108+
* Replaced with name of the `PersistentVolume` object being provisioned.
109+
* `${pvc.namespace}`
110+
* Replaced with namespace of the `PersistentVolumeClaim` object that triggered provisioning.
111+
* Support added in CSI `external-provisioner` v1.2.0+
112+
* `${pvc.name}`
113+
* Replaced with the name of the `PersistentVolumeClaim` object that triggered provisioning.
114+
* Support added in CSI `external-provisioner` v1.2.0+
115+
* `csi.storage.k8s.io/provisioner-secret-namespace`
116+
* `${pv.name}`
117+
* Replaced with name of the `PersistentVolume` object being provisioned.
118+
* `${pvc.namespace}`
119+
* Replaced with namespace of the `PersistentVolumeClaim` object that triggered provisioning.
120+
121+
### Controller Publish/Unpublish Secret
122+
123+
The CSI `external-provisioner` (v1.0.1+) looks for the following keys in `StorageClass.parameters`:
124+
125+
* `csi.storage.k8s.io/controller-publish-secret-name`
126+
* `csi.storage.k8s.io/controller-publish-secret-namespace`
127+
128+
The values of both of these parameters, together, refer to the name and namespace of a `Secret` object in the Kubernetes API.
129+
130+
If specified, the CSI `external-provisioner` sets the `CSIPersistentVolumeSource.ControllerPublishSecretRef` field in the new `PersistentVolume` object to refer to this secret once provisioning is successful.
131+
132+
The CSI `external-attacher` then attempts to fetch the secret referenced by the `CSIPersistentVolumeSource.ControllerPublishSecretRef`, if specified, before an attach or detach operation.
133+
134+
If no such secret exists in the Kubernetes API, or the `external-attacher` is unable to fetch it, the attach or detach operation fails.
135+
136+
If the secret is retrieved successfully, the `external-attacher` passes it to the CSI driver in the `ControllerPublishVolumeRequest.secrets` or `ControllerUnpublishVolumeRequest.secrets` field.
137+
138+
The values of these parameters may be "templates". The `external-provisioner` will automatically resolve templates at volume provision time, as detailed below:
139+
140+
* `csi.storage.k8s.io/controller-publish-secret-name`
141+
* `${pv.name}`
142+
* Replaced with name of the `PersistentVolume` object being provisioned.
143+
* `${pvc.namespace}`
144+
* Replaced with namespace of the `PersistentVolumeClaim` object that triggered provisioning.
145+
* `${pvc.name}`
146+
* Replaced with the name of the `PersistentVolumeClaim` object that triggered provisioning.
147+
* `${pvc.annotations['<ANNOTATION_KEY>']}` (e.g. `${pvc.annotations['example.com/key']}`)
148+
* Replaced with the value of the specified annotation from the `PersistentVolumeClaim` object that triggered provisioning
149+
* `csi.storage.k8s.io/controller-publish-secret-namespace`
150+
* `${pv.name}`
151+
* Replaced with name of the `PersistentVolume` object being provisioned.
152+
* `${pvc.namespace}`
153+
* Replaced with namespace of the `PersistentVolumeClaim` object that triggered provisioning.
154+
155+
156+
### Node Stage Secret
157+
158+
The CSI `external-provisioner` (v1.0.1+) looks for the following keys in `StorageClass.parameters`:
159+
160+
* `csi.storage.k8s.io/node-stage-secret-name`
161+
* `csi.storage.k8s.io/node-stage-secret-namespace`
162+
163+
The value of both parameters, together, refer to the name and namespace of the `Secret` object in the Kubernetes API.
164+
165+
If specified, the CSI `external-provisioner` sets the `CSIPersistentVolumeSource.NodeStageSecretRef` field in the new `PersistentVolume` object to refer to this secret once provisioning is successful.
166+
167+
The Kubernetes kubelet then attempts to fetch the secret referenced by the `CSIPersistentVolumeSource.NodeStageSecretRef` field, if specified, before a mount device operation.
168+
169+
If no such secret exists in the Kubernetes API, or the kubelet is unable to fetch it, the mount device operation fails.
170+
171+
If the secret is retrieved successfully, the kubelet passes it to the CSI driver in the `NodeStageVolumeRequest.secrets` field.
172+
173+
The values of these parameters may be "templates". The `external-provisioner` will automatically resolve templates at volume provision time, as detailed below:
174+
175+
* `csi.storage.k8s.io/node-stage-secret-name`
176+
* `${pv.name}`
177+
* Replaced with name of the `PersistentVolume` object being provisioned.
178+
* `${pvc.namespace}`
179+
* Replaced with namespace of the `PersistentVolumeClaim` object that triggered provisioning.
180+
* `${pvc.name}`
181+
* Replaced with the name of the `PersistentVolumeClaim` object that triggered provisioning.
182+
* `${pvc.annotations['<ANNOTATION_KEY>']}` (e.g. `${pvc.annotations['example.com/key']}`)
183+
* Replaced with the value of the specified annotation from the `PersistentVolumeClaim` object that triggered provisioning
184+
* `csi.storage.k8s.io/node-stage-secret-namespace`
185+
* `${pv.name}`
186+
* Replaced with name of the `PersistentVolume` object being provisioned.
187+
* `${pvc.namespace}`
188+
* Replaced with namespace of the `PersistentVolumeClaim` object that triggered provisioning.
189+
190+
### Node Publish Secret
191+
192+
The CSI `external-provisioner` (v1.0.1+) looks for the following keys in `StorageClass.parameters`:
193+
194+
* `csi.storage.k8s.io/node-publish-secret-name`
195+
* `csi.storage.k8s.io/node-publish-secret-namespace`
196+
197+
The value of both parameters, together, refer to the name and namespace of the `Secret` object in the Kubernetes API.
198+
199+
If specified, the CSI `external-provisioner` sets the `CSIPersistentVolumeSource.NodePublishSecretRef` field in the new `PersistentVolume` object to refer to this secret once provisioning is successful.
200+
201+
The Kubernetes kubelet, attempts to fetch the secret referenced by the `CSIPersistentVolumeSource.NodePublishSecretRef` field, if specified, before a mount operation.
202+
203+
If no such secret exists in the Kubernetes API, or the kubelet is unable to fetch it, the mount operation fails.
204+
205+
If the secret is retrieved successfully, the kubelet passes it to the CSI driver in the `NodePublishVolumeRequest.secrets` field.
206+
207+
The values of these parameters may be "templates". The `external-provisioner` will automatically resolve templates at volume provision time, as detailed below:
208+
209+
* `csi.storage.k8s.io/node-publish-secret-name`
210+
* `${pv.name}`
211+
* Replaced with name of the `PersistentVolume` object being provisioned.
212+
* `${pvc.namespace}`
213+
* Replaced with namespace of the `PersistentVolumeClaim` object that triggered provisioning.
214+
* `${pvc.name}`
215+
* Replaced with the name of the `PersistentVolumeClaim` object that triggered provisioning.
216+
* `${pvc.annotations['<ANNOTATION_KEY>']}` (e.g. `${pvc.annotations['example.com/key']}`)
217+
* Replaced with the value of the specified annotation from the `PersistentVolumeClaim` object that triggered provisioning
218+
* `csi.storage.k8s.io/node-publish-secret-namespace`
219+
* `${pv.name}`
220+
* Replaced with name of the `PersistentVolume` object being provisioned.
221+
* `${pvc.namespace}`
222+
* Replaced with namespace of the `PersistentVolumeClaim` object that triggered provisioning.
223+
224+
### Volume Resize (Expand) Secret
225+
226+
The CSI `external-provisioner` (v1.2.0+) looks for the following keys in `StorageClass.parameters`:
227+
228+
* `csi.storage.k8s.io/controller-expand-secret-name`
229+
* `csi.storage.k8s.io/controller-expand-secret-namespace`
230+
231+
The value of both parameters, together, refer to the name and namespace of the `Secret` object in the Kubernetes API.
232+
233+
If specified, the CSI `external-provisioner` sets the `CSIPersistentVolumeSource.ControllerExpandSecretRef` field in the new `PersistentVolume` object to refer to this secret once provisioning is successful.
234+
235+
The `external-resizer` (v0.2.0+), attempts to fetch the secret referenced by the `CSIPersistentVolumeSource.ControllerExpandSecretRef` field, if specified, before starting a volume resize (expand) operation.
236+
237+
If no such secret exists in the Kubernetes API, or the `external-resizer` is unable to fetch it, the resize (expand) operation fails.
238+
239+
If the secret is retrieved successfully, the `external-resizer` passes it to the CSI driver in the `ControllerExpandVolumeRequest.secrets` field.
240+
241+
The values of these parameters may be "templates". The `external-provisioner` will automatically resolve templates at volume provision time, as detailed below:
242+
243+
* `csi.storage.k8s.io/controller-expand-secret-name`
244+
* `${pv.name}`
245+
* Replaced with name of the `PersistentVolume` object being provisioned.
246+
* `${pvc.namespace}`
247+
* Replaced with namespace of the `PersistentVolumeClaim` object that triggered provisioning.
248+
* `${pvc.name}`
249+
* Replaced with the name of the `PersistentVolumeClaim` object that triggered provisioning.
250+
* `${pvc.annotations['<ANNOTATION_KEY>']}` (e.g. `${pvc.annotations['example.com/key']}`)
251+
* Replaced with the value of the specified annotation from the `PersistentVolumeClaim` object that triggered provisioning
252+
* `csi.storage.k8s.io/controller-expand-secret-namespace`
253+
* `${pv.name}`
254+
* Replaced with name of the `PersistentVolume` object being provisioned.
255+
* `${pvc.namespace}`
256+
* Replaced with namespace of the `PersistentVolumeClaim` object that triggered provisioning.

‎book/src/secrets-and-credentials-external-snapshotter.md

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
# SnapshotClass Secrets
2+
3+
The CSI [external-snapshotter](external-snapshotter.md) sidecar container facilitates the handling of secrets for the following operations:
4+
* `CreateSnapshotRequest`
5+
* `DeleteSnapshotRequest`
6+
7+
CSI `external-snapshotter` v1.0.1+ support the following keys in `SnapshotClass.parameters`:
8+
9+
* `csi.storage.k8s.io/snapshotter-secret-name`
10+
* `csi.storage.k8s.io/snapshotter-secret-namespace`
11+
12+
Cluster admins can populate the secret fields for the operations listed above with data from Kubernetes `Secret` objects by specifying these keys in the `SnapshotClass` object.
13+
14+
## Operations
15+
Details for each secret supported by the external-snapshotter can be found below.
16+
17+
### Create/Delete VolumeSnapshot Secret
18+
19+
CSI `external-snapshotter` v1.0.1+ support the following keys in `SnapshotClass.parameters`:
20+
21+
* `csi.storage.k8s.io/snapshotter-secret-name`
22+
* `csi.storage.k8s.io/snapshotter-secret-namespace`
23+
24+
The values of both of these parameters, together, refer to the name and namespace of a `Secret` object in the Kubernetes API.
25+
26+
If specified, the CSI `external-snapshotter` will attempt to fetch the secret before creation and deletion.
27+
28+
If the secret is retrieved successfully, the snapshotter passes it to the CSI driver in the `CreateSnapshotRequest.secrets` or `DeleteSnapshotRequest.secrets` field.
29+
30+
If no such secret exists in the Kubernetes API, or the snapshotter is unable to fetch it, the create operation will fail.
31+
32+
Note, however, that the delete operation will continue even if the secret is not found (because, for example, the entire namespace containing the secret was deleted). In this case, if the driver requires a secret for deletion, then the volume and PV may need to be manually cleaned up.
33+
34+
The values of these parameters may be "templates". The `external-snapshotter` will automatically resolve templates at snapshot create time, as detailed below:
35+
36+
* `csi.storage.k8s.io/snapshotter-secret-name`
37+
* `${volumesnapshotcontent.name}`
38+
* Replaced with name of the `VolumeSnapshotContent` object being created.
39+
* `${volumesnapshot.namespace}`
40+
* Replaced with namespace of the `VolumeSnapshot` object that triggered creation.
41+
* `${volumesnapshot.name}`
42+
* Replaced with the name of the `VolumeSnapshot` object that triggered creation.
43+
* `csi.storage.k8s.io/snapshotter-secret-namespace`
44+
* `${volumesnapshotcontent.name}`
45+
* Replaced with name of the `VolumeSnapshotContent` object being created.
46+
* `${volumesnapshot.namespace}`
47+
* Replaced with namespace of the `VolumeSnapshot` object that triggered creation.

0 commit comments

Comments
 (0)