Skip to content

Commit d318286

Browse files
mynktlmynktl
authored
doc(hook): tutorial on how to use hooks with nfs-provisioner (#119)
 Signed-off-by: mayank <mayank.patel@mayadata.io>
1 parent f2baa53 commit d318286

File tree

2 files changed

+309
-0
lines changed

2 files changed

+309
-0
lines changed

‎README.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -41,6 +41,7 @@ Please refer to our [Quickstart](https://github.com/openebs/dynamic-nfs-provisio
4141

4242
[Monitoring NFS Provisioner](https://github.com/openebs/dynamic-nfs-provisioner/blob/develop/docs/metrics.md)
4343

44+
[Configuring Hook for NFS Provisioner](https://github.com/openebs/dynamic-nfs-provisioner/blob/develop/docs/tutorial/nfs-hook.md)
4445

4546
## Troubleshooting
4647
If you encounter any issue while using OpenEBS Dynamic NFS Provisioner, review the [troubleshooting guide](https://github.com/openebs/dynamic-nfs-provisioner/blob/develop/docs/troubleshooting.md). You can also [file an issue](https://github.com/openebs/dynamic-nfs-provisioner/issues) or talk to us on [#openebs channel](https://kubernetes.slack.com/messages/openebs) in the [Kubernetes Slack](https://kubernetes.slack.com).

‎docs/tutorial/nfs-hook.md

Lines changed: 308 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,308 @@
1+
# Using Hook in NFS Provisioner
2+
3+
OpenEBS Dynamic NFS Provisioner exposes Kubernetes PV using NFS server and enables it for ReadWriteMany(RWX) mode. To make this possible, NFS Provisioner creates few Kubernetes resources which are mapped to the generated NFS PV resources. Using hook, admin/user can enable the NFS Provisioner to add annotations and finalizers to NFS Resources. This tutorial explains, how to configure hook on NFS Provisioner.
4+
5+
If you haven't installed the NFS Provisioner, refer [QuickStart guide on How to install OpenEBS NFS Provisioner](https://github.com/openebs/dynamic-nfs-provisioner/blob/develop/docs/intro.md#quickstart).
6+
7+
## Create Hook Configmap
8+
First we need to create a Configmap resource in NFS Provisioner's namespace(i.e *openebs*).
9+
10+
Sample Configmap YAML is as below:
11+
12+
```yaml
13+
apiVersion: v1
14+
kind: ConfigMap
15+
metadata:
16+
name: hook-config
17+
namespace: openebs
18+
data:
19+
hook-config: |
20+
hooks:
21+
addOrUpdateEntriesOnCreateVolumeEvent:
22+
backendPV:
23+
annotations:
24+
example.io/track: "true"
25+
example.io/owner: teamA
26+
example.io/tracking-create-time: $current-time
27+
finalizers:
28+
- example.io/tracking-protection
29+
backendPVC:
30+
annotations:
31+
example.io/track: "true"
32+
example.io/owner: teamA
33+
finalizers:
34+
- example.io/tracking-protection
35+
name: createHook
36+
nfsDeployment:
37+
annotations:
38+
example.io/track: "true"
39+
example.io/owner: teamA
40+
finalizers:
41+
- example.io/tracking-protection
42+
nfsPV:
43+
annotations:
44+
example.io/track: "true"
45+
example.io/owner: teamA
46+
finalizers:
47+
- example.io/tracking-protection
48+
nfsService:
49+
annotations:
50+
example.io/track: "true"
51+
example.io/owner: teamA
52+
finalizers:
53+
- example.io/tracking-protection
54+
removeEntriesOnDeleteVolumeEvent:
55+
backendPV:
56+
finalizers:
57+
- example.io/tracking-protection
58+
backendPVC:
59+
finalizers:
60+
- example.io/tracking-protection
61+
name: deleteHook
62+
nfsDeployment:
63+
finalizers:
64+
- example.io/tracking-protection
65+
nfsPV:
66+
finalizers:
67+
- example.io/tracking-protection
68+
nfsService:
69+
finalizers:
70+
- example.io/tracking-protection
71+
version: 1.0.0
72+
```
73+
74+
Above hook config will add annotations and finalizers to NFS resources while creating NFS PV, and remove the finalizer from NFS resources while deleting NFS PV.
75+
76+
Hook configuration is having below structure:
77+
78+
```yaml
79+
hooks:
80+
actionWithEventType:
81+
backendPV:
82+
annotations:
83+
finalizers:
84+
backendPVC:
85+
annotations:
86+
finalizers:
87+
name: <HOOK_NAME>
88+
nfsDeployment:
89+
annotations:
90+
finalizers:
91+
nfsPV:
92+
annotations:
93+
finalizers:
94+
nfsService:
95+
annotations:
96+
finalizers:
97+
version: 1.0.0
98+
```
99+
100+
Supported *actionWithEventType* are as below:
101+
- addOrUpdateEntriesOnCreateVolumeEvent
102+
- This action will modify the resources, which are being created as part of the volume creation operation, by adding the provided configuration. If provided configuration exists in the resources spec then it will be updated with the given configuration.
103+
- removeEntriesOnCreateVolumeEvent
104+
- This action will modify the resources, which are being created as part of the volume creation operation, by removing the provided configuration from resource's spec. If provided configuration doesn't exists in the resource spec then it will skip those configuration.
105+
- addOrUpdateEntriesOnDeleteVolumeEvent
106+
- This action will modify the resources of a NFS volume when it gets deleted, by adding the provided configuration. If provided configuration exists in the resource spec then it will be updated with the given config.
107+
- removeEntriesOnDeleteVolumeEvent
108+
- This action will modify the resources of a NFS volume when it gets deleted, by removing the provided configuration from resource's spec. If provided configuration exists in the resource spec then it will be updated with the given config.
109+
110+
*Note:*
111+
- *Duplicate **actionWithEventType** are not allowed.*
112+
- *If hook is configured to add finalizers on NFS resources then you need to remove those finalizers through hook(by using **removeEntriesOnDeleteVolumeEvent**) or manually(to delete the NFS Volume).*
113+
114+
Above four *actionWithEventType* supports following resources:
115+
- backendPV
116+
- supported fields
117+
- annotations
118+
- finalizers
119+
- backendPVC
120+
- supported fields
121+
- annotations
122+
- finalizers
123+
- nfsDeployment
124+
- supported fields
125+
- annotations
126+
- finalizers
127+
- nfsService
128+
- supported fields
129+
- annotations
130+
- finalizers
131+
- nfsPV
132+
- supported fields
133+
- annotations
134+
- finalizers
135+
136+
## Updating NFS Provisioner
137+
Once Hook Configmap is created, update the NFS Provisioner Deployment to mount above Configmap as volume using *mountPath* set to */etc/nfs-provisioner*.
138+
139+
You can use below patch data to patch the NFS Provisioner Deployment.
140+
```json
141+
{
142+
"spec": {
143+
"template": {
144+
"spec": {
145+
"containers": [{
146+
"name": "openebs-provisioner-nfs",
147+
"volumeMounts": [{
148+
"mountPath": "/etc/nfs-provisioner",
149+
"name": "hook-config-volume"
150+
}]
151+
}],
152+
"volumes": [{
153+
"name": "hook-config-volume",
154+
"configMap": {
155+
"name": "hook-config"
156+
}
157+
}]
158+
}
159+
}
160+
}
161+
}
162+
```
163+
In above json,
164+
- *hook-config* is the Configmap we created in [Create Hook Configmap](#create-hook-configmap)
165+
- *openebs-provisioner-nfs* is container name for NFS Provisioner. If you have installed NFS Provisioner through Helm, you need to update it accordingly.
166+
167+
168+
Save above json to file named *nfs-hook-deployment.patch* and run below command to patch NFS Provisioner Deployment:
169+
```bash
170+
kubectl patch deploy -n openebs openebs-nfs-provisioner --patch "$(cat nfs-hook-deployment.patch)"
171+
```
172+
In above command, *openebs-nfs-provisioner* is deployment name for NFS Provisioner. If you have installed NFS Provisioner using Helm, you need to change it accordingly.
173+
174+
175+
After applying the patch, you can check the deployment spec to verify the volumeMounts.
176+
177+
<details>
178+
<summary>Click to check sample yaml of nfs-provisioner with above env.</summary>
179+
180+
```yaml
181+
apiVersion: apps/v1
182+
kind: Deployment
183+
metadata:
184+
annotations:
185+
deployment.kubernetes.io/revision: "2"
186+
kubectl.kubernetes.io/last-applied-configuration: |
187+
{"apiVersion":"apps/v1","kind":"Deployment","metadata":{"annotations":{},"labels":{"name":"openebs-nfs-provisioner","openebs.io/component-name":"openebs-nfs-provisioner","openebs.io/version":"dev"},"name":"openebs-nfs-provisioner","namespace":"openebs"},"spec":{"replicas":1,"selector":{"matchLabels":{"name":"openebs-nfs-provisioner","openebs.io/component-name":"openebs-nfs-provisioner"}},"strategy":{"type":"Recreate"},"template":{"metadata":{"labels":{"name":"openebs-nfs-provisioner","openebs.io/component-name":"openebs-nfs-provisioner","openebs.io/version":"dev"}},"spec":{"containers":[{"env":[{"name":"NODE_NAME","valueFrom":{"fieldRef":{"fieldPath":"spec.nodeName"}}},{"name":"OPENEBS_NAMESPACE","valueFrom":{"fieldRef":{"fieldPath":"metadata.namespace"}}},{"name":"OPENEBS_SERVICE_ACCOUNT","valueFrom":{"fieldRef":{"fieldPath":"spec.serviceAccountName"}}},{"name":"OPENEBS_IO_ENABLE_ANALYTICS","value":"false"},{"name":"OPENEBS_IO_NFS_SERVER_USE_CLUSTERIP","value":"true"},{"name":"OPENEBS_IO_INSTALLER_TYPE","value":"openebs-operator-nfs"},{"name":"OPENEBS_IO_NFS_SERVER_IMG","value":"openebs/nfs-server-alpine:ci"}],"image":"openebs/provisioner-nfs:ci","imagePullPolicy":"IfNotPresent","livenessProbe":{"exec":{"command":["sh","-c","test `pgrep \"^provisioner-nfs.*\"` = 1"]},"initialDelaySeconds":30,"periodSeconds":60},"name":"openebs-provisioner-nfs","resources":{"limits":{"cpu":"200m","memory":"200M"},"requests":{"cpu":"50m","memory":"50M"}}}],"serviceAccountName":"openebs-maya-operator"}}}}
188+
creationTimestamp: "2021-11-03T11:35:07Z"
189+
generation: 2
190+
labels:
191+
name: openebs-nfs-provisioner
192+
openebs.io/component-name: openebs-nfs-provisioner
193+
openebs.io/version: dev
194+
name: openebs-nfs-provisioner
195+
namespace: openebs
196+
resourceVersion: "201799"
197+
uid: f812eab5-cb92-43ac-9ea5-e5a06c146d9a
198+
spec:
199+
progressDeadlineSeconds: 600
200+
replicas: 1
201+
revisionHistoryLimit: 10
202+
selector:
203+
matchLabels:
204+
name: openebs-nfs-provisioner
205+
openebs.io/component-name: openebs-nfs-provisioner
206+
strategy:
207+
type: Recreate
208+
template:
209+
metadata:
210+
creationTimestamp: null
211+
labels:
212+
name: openebs-nfs-provisioner
213+
openebs.io/component-name: openebs-nfs-provisioner
214+
openebs.io/version: dev
215+
spec:
216+
containers:
217+
- env:
218+
- name: NODE_NAME
219+
valueFrom:
220+
fieldRef:
221+
apiVersion: v1
222+
fieldPath: spec.nodeName
223+
- name: OPENEBS_NAMESPACE
224+
valueFrom:
225+
fieldRef:
226+
apiVersion: v1
227+
fieldPath: metadata.namespace
228+
- name: OPENEBS_SERVICE_ACCOUNT
229+
valueFrom:
230+
fieldRef:
231+
apiVersion: v1
232+
fieldPath: spec.serviceAccountName
233+
- name: OPENEBS_IO_ENABLE_ANALYTICS
234+
value: "true"
235+
- name: OPENEBS_IO_NFS_SERVER_USE_CLUSTERIP
236+
value: "true"
237+
- name: OPENEBS_IO_INSTALLER_TYPE
238+
value: openebs-operator-nfs
239+
- name: OPENEBS_IO_NFS_SERVER_IMG
240+
value: openebs/nfs-server-alpine:ci
241+
image: openebs/provisioner-nfs:ci
242+
imagePullPolicy: IfNotPresent
243+
livenessProbe:
244+
exec:
245+
command:
246+
- sh
247+
- -c
248+
- test `pgrep "^provisioner-nfs.*"` = 1
249+
failureThreshold: 3
250+
initialDelaySeconds: 30
251+
periodSeconds: 60
252+
successThreshold: 1
253+
timeoutSeconds: 1
254+
name: openebs-provisioner-nfs
255+
resources:
256+
limits:
257+
cpu: 200m
258+
memory: 200M
259+
requests:
260+
cpu: 50m
261+
memory: 50M
262+
terminationMessagePath: /dev/termination-log
263+
terminationMessagePolicy: File
264+
volumeMounts:
265+
- mountPath: /etc/nfs-provisioner
266+
name: hook-config-volume
267+
dnsPolicy: ClusterFirst
268+
restartPolicy: Always
269+
schedulerName: default-scheduler
270+
securityContext: {}
271+
serviceAccount: openebs-maya-operator
272+
serviceAccountName: openebs-maya-operator
273+
terminationGracePeriodSeconds: 30
274+
volumes:
275+
- configMap:
276+
defaultMode: 420
277+
name: hook-config
278+
name: hook-config-volume
279+
status:
280+
availableReplicas: 1
281+
conditions:
282+
- lastTransitionTime: "2021-11-03T11:36:48Z"
283+
lastUpdateTime: "2021-11-03T11:36:48Z"
284+
message: Deployment has minimum availability.
285+
reason: MinimumReplicasAvailable
286+
status: "True"
287+
type: Available
288+
- lastTransitionTime: "2021-11-03T11:35:07Z"
289+
lastUpdateTime: "2021-11-03T11:36:48Z"
290+
message: ReplicaSet "openebs-nfs-provisioner-8b657b65" has successfully progressed.
291+
reason: NewReplicaSetAvailable
292+
status: "True"
293+
type: Progressing
294+
observedGeneration: 2
295+
readyReplicas: 1
296+
replicas: 1
297+
updatedReplicas: 1
298+
```
299+
300+
</details>
301+
302+
## Creating NFS Volumes
303+
304+
Once NFS Provisioner is updated with volumeMounts, you can start deploying NFS Volumes. NFS resources generated for the volumes will have the annotations and finalizers as mentioned in the hook Configmap.
305+
306+
If you need information on creating NFS Volume, visit [How to create NFS Volume](https://github.com/openebs/dynamic-nfs-provisioner/blob/develop/docs/intro.md#provision-nfs-volume)
307+
308+

0 commit comments

Comments
 (0)