From 522cf1876e3edc7b560e8e3b8d3c65cb6ebc95f9 Mon Sep 17 00:00:00 2001 From: Chakravarthy Nelluri Date: Fri, 17 Mar 2017 16:46:46 -0400 Subject: [PATCH 1/3] Update flex volume 1.6 documentation. --- examples/volumes/flexvolume/README.md | 81 ++++++++++++++++++++------- 1 file changed, 62 insertions(+), 19 deletions(-) diff --git a/examples/volumes/flexvolume/README.md b/examples/volumes/flexvolume/README.md index 6c78a9d9f2..dc295030a5 100644 --- a/examples/volumes/flexvolume/README.md +++ b/examples/volumes/flexvolume/README.md @@ -1,54 +1,94 @@ # Flexvolume -Flexvolume enables users to mount vendor volumes into kubernetes. It expects vendor drivers are installed in the volume plugin path on every kubelet node. - -It allows for vendors to develop their own drivers to mount volumes on nodes. +Flexvolume enables users to write their own drivers and add support for their volumes in Kubernetes. Vendor drivers should be installed in the volume plugin path on every Kubelet node and on master node(s) if "-enable-controller-attach-detach" Kubelet option is enabled. *Note: Flexvolume is an alpha feature and is most likely to change in future* ## Prerequisites -Install the vendor driver on all nodes in the kubelet plugin path. Path for installing the plugin: /usr/libexec/kubernetes/kubelet-plugins/volume/exec/\/\ +Install the vendor driver on all nodes (also on master nodes if "-enable-controller-attach-detach" Kubelet option is enabled) in the plugin path. Path for installing the plugin: /usr/libexec/kubernetes/kubelet-plugins/volume/exec/\/\ For example to add a 'cifs' driver, by vendor 'foo' install the driver at: /usr/libexec/kubernetes/kubelet-plugins/volume/exec/\/cifs ## Plugin details - -Driver will be invoked with 'Init' to initialize the driver. It will be invoked with 'attach' to attach the volume and with 'detach' to detach the volume from the kubelet node. It also supports custom mounts using 'mount' and 'unmount' callouts to the driver. +The plugin expects the following call-outs are implemented for the backend drivers. Some call-outs are optional. Call-outs are invoked from the Kubelet & Controller manager nodes. ### Driver invocation model: -Init: +#### Init: +Initializes the driver. ``` init ``` -Attach: +#### Get volume name: +Get a cluster wide unique volume name for the volume. ``` - attach + getvolumename ``` -Detach: +#### Attach: +Attach the volume specified by the given spec on the given host. On success, returns the device path where the device is attached on the node. Nodename param is only valid if "-enable-controller-attach-detach" Kubelet option is enabled. + +This call-out does not pass "secrets" specified in Flexvolume spec. If your driver requires secrets, do not implement this call-out and instead use "mount" call-out and implement attach and mount in that call-out. ``` - detach + attach ``` -Mount: - +#### Detach: +Detach the volume from the Kubelet node. Nodename param is only valid if "-enable-controller-attach-detach" Kubelet option is enabled. ``` - mount + detach ``` -Unmount: +#### Wait for attach: +Wait for the volume to be attached on the remote node. On success, the path to the device is returned. + +``` + waitfordetach +``` + +#### Volume is Attached: +Check the volume is attached on the node. + +``` + isattached +``` + +#### Mount device: +Mount device mounts the device to a global path which individual pods can then bind mount. + +This call-out does not pass "secrets" specified in Flexvolume spec. If your driver requires secrets, do not implement this call-out and instead use "mount" call-out and implement attach and mount in that call-out. + +``` + mountdevice +``` + +#### Unmount device: +Unmounts the global mount for the device. This is called once all bind mounts have been unmounted. + +``` + unmountdevice +``` + +#### Mount: +Mount the volume at the mount dir. This call-out defaults to bind mount for drivers which implement attach & mount-device call-outs. + +``` + mount +``` + +#### Unmount: +Unmount the volume. This call-out defaults to bind mount for drivers which implement attach & mount-device call-outs. ``` unmount ``` -See [lvm](lvm) for a quick example on how to write a simple flexvolume driver. +See [lvm](lvm) & [nfs](nfs) for a quick example on how to write a simple flexvolume driver. ### Driver output: @@ -57,15 +97,18 @@ following format. ``` { - "status": "", + "status": "", "message": "", - "device": "" + "device": "" + "volumeName": "" + "attached": } ``` ### Default Json options In addition to the flags specified by the user in the Options field of the FlexVolumeSource, the following flags are also passed to the executable. +Note: Secrets are passed only to "mount/unmount" call-outs. ``` "kubernetes.io/fsType":"", @@ -77,7 +120,7 @@ In addition to the flags specified by the user in the Options field of the FlexV ### Example of Flexvolume -See [nginx.yaml](nginx.yaml) for a quick example on how to use Flexvolume in a pod. +See [nginx.yaml](nginx.yaml) & [nginx-nfs.yaml](nginx-nfs.yaml) for a quick example on how to use Flexvolume in a pod. [![Analytics](https://kubernetes-site.appspot.com/UA-36037335-10/GitHub/examples/volumes/flexvolume/README.md?pixel)]() From ef35d6a7264299a3efdadb7794a507354cf0cc31 Mon Sep 17 00:00:00 2001 From: Chakravarthy Nelluri Date: Mon, 20 Mar 2017 14:02:39 -0400 Subject: [PATCH 2/3] Address review comments from @saad-ali --- examples/volumes/flexvolume/README.md | 29 ++++++++++++++------------- 1 file changed, 15 insertions(+), 14 deletions(-) diff --git a/examples/volumes/flexvolume/README.md b/examples/volumes/flexvolume/README.md index dc295030a5..65fac617ea 100644 --- a/examples/volumes/flexvolume/README.md +++ b/examples/volumes/flexvolume/README.md @@ -1,36 +1,37 @@ # Flexvolume -Flexvolume enables users to write their own drivers and add support for their volumes in Kubernetes. Vendor drivers should be installed in the volume plugin path on every Kubelet node and on master node(s) if "-enable-controller-attach-detach" Kubelet option is enabled. +Flexvolume enables users to write their own drivers and add support for their volumes in Kubernetes. Vendor drivers should be installed in the volume plugin path on every Kubelet node and on master node(s) if "--enable-controller-attach-detach" Kubelet option is enabled. *Note: Flexvolume is an alpha feature and is most likely to change in future* ## Prerequisites -Install the vendor driver on all nodes (also on master nodes if "-enable-controller-attach-detach" Kubelet option is enabled) in the plugin path. Path for installing the plugin: /usr/libexec/kubernetes/kubelet-plugins/volume/exec/\/\ +Install the vendor driver on all nodes (also on master nodes if "--enable-controller-attach-detach" Kubelet option is enabled) in the plugin path. Path for installing the plugin: /usr/libexec/kubernetes/kubelet-plugins/volume/exec/\/\ For example to add a 'cifs' driver, by vendor 'foo' install the driver at: /usr/libexec/kubernetes/kubelet-plugins/volume/exec/\/cifs ## Plugin details -The plugin expects the following call-outs are implemented for the backend drivers. Some call-outs are optional. Call-outs are invoked from the Kubelet & Controller manager nodes. +The plugin expects the following call-outs are implemented for the backend drivers. Some call-outs are optional. Call-outs are invoked from the Kubelet & the Controller manager nodes. +Call-outs are invoked from Controller-manager only when "--enable-controller-attach-detach" Kubelet option is enabled. ### Driver invocation model: #### Init: -Initializes the driver. +Initializes the driver. Called during Kubelet & Controller manager initialization. ``` init ``` #### Get volume name: -Get a cluster wide unique volume name for the volume. +Get a cluster wide unique volume name for the volume. Called from both Kubelet & Controller manager. ``` getvolumename ``` #### Attach: -Attach the volume specified by the given spec on the given host. On success, returns the device path where the device is attached on the node. Nodename param is only valid if "-enable-controller-attach-detach" Kubelet option is enabled. +Attach the volume specified by the given spec on the given host. On success, returns the device path where the device is attached on the node. Nodename param is only valid/relevant if "--enable-controller-attach-detach" Kubelet option is enabled. Called from both Kubelet & Controller manager. This call-out does not pass "secrets" specified in Flexvolume spec. If your driver requires secrets, do not implement this call-out and instead use "mount" call-out and implement attach and mount in that call-out. @@ -39,27 +40,27 @@ This call-out does not pass "secrets" specified in Flexvolume spec. If your driv ``` #### Detach: -Detach the volume from the Kubelet node. Nodename param is only valid if "-enable-controller-attach-detach" Kubelet option is enabled. +Detach the volume from the Kubelet node. Nodename param is only valid/relevant if "--enable-controller-attach-detach" Kubelet option is enabled. Called from both Kubelet & Controller manager. ``` detach ``` #### Wait for attach: -Wait for the volume to be attached on the remote node. On success, the path to the device is returned. +Wait for the volume to be attached on the remote node. On success, the path to the device is returned. Called from both Kubelet & Controller manager. ``` - waitfordetach + waitforattach ``` #### Volume is Attached: -Check the volume is attached on the node. +Check the volume is attached on the node. Called from both Kubelet & Controller manager. ``` isattached ``` #### Mount device: -Mount device mounts the device to a global path which individual pods can then bind mount. +Mount device mounts the device to a global path which individual pods can then bind mount. Called only from Kubelet. This call-out does not pass "secrets" specified in Flexvolume spec. If your driver requires secrets, do not implement this call-out and instead use "mount" call-out and implement attach and mount in that call-out. @@ -68,21 +69,21 @@ This call-out does not pass "secrets" specified in Flexvolume spec. If your driv ``` #### Unmount device: -Unmounts the global mount for the device. This is called once all bind mounts have been unmounted. +Unmounts the global mount for the device. This is called once all bind mounts have been unmounted. Called only from Kubelet. ``` unmountdevice ``` #### Mount: -Mount the volume at the mount dir. This call-out defaults to bind mount for drivers which implement attach & mount-device call-outs. +Mount the volume at the mount dir. This call-out defaults to bind mount for drivers which implement attach & mount-device call-outs. Called only from Kubelet. ``` mount ``` #### Unmount: -Unmount the volume. This call-out defaults to bind mount for drivers which implement attach & mount-device call-outs. +Unmount the volume. This call-out defaults to bind mount for drivers which implement attach & mount-device call-outs. Called only from Kubelet. ``` unmount From 399fe519a1160c894825677f87d9db31b1587516 Mon Sep 17 00:00:00 2001 From: Chakravarthy Nelluri Date: Wed, 22 Mar 2017 14:55:40 -0400 Subject: [PATCH 3/3] Move documentation to community 1.6 --- examples/volumes/flexvolume/README.md | 129 +------------------------- 1 file changed, 1 insertion(+), 128 deletions(-) diff --git a/examples/volumes/flexvolume/README.md b/examples/volumes/flexvolume/README.md index 65fac617ea..8f88b690cf 100644 --- a/examples/volumes/flexvolume/README.md +++ b/examples/volumes/flexvolume/README.md @@ -1,128 +1 @@ -# Flexvolume - -Flexvolume enables users to write their own drivers and add support for their volumes in Kubernetes. Vendor drivers should be installed in the volume plugin path on every Kubelet node and on master node(s) if "--enable-controller-attach-detach" Kubelet option is enabled. - -*Note: Flexvolume is an alpha feature and is most likely to change in future* - -## Prerequisites - -Install the vendor driver on all nodes (also on master nodes if "--enable-controller-attach-detach" Kubelet option is enabled) in the plugin path. Path for installing the plugin: /usr/libexec/kubernetes/kubelet-plugins/volume/exec/\/\ - -For example to add a 'cifs' driver, by vendor 'foo' install the driver at: /usr/libexec/kubernetes/kubelet-plugins/volume/exec/\/cifs - -## Plugin details -The plugin expects the following call-outs are implemented for the backend drivers. Some call-outs are optional. Call-outs are invoked from the Kubelet & the Controller manager nodes. -Call-outs are invoked from Controller-manager only when "--enable-controller-attach-detach" Kubelet option is enabled. - -### Driver invocation model: - -#### Init: -Initializes the driver. Called during Kubelet & Controller manager initialization. - -``` - init -``` - -#### Get volume name: -Get a cluster wide unique volume name for the volume. Called from both Kubelet & Controller manager. - -``` - getvolumename -``` - -#### Attach: -Attach the volume specified by the given spec on the given host. On success, returns the device path where the device is attached on the node. Nodename param is only valid/relevant if "--enable-controller-attach-detach" Kubelet option is enabled. Called from both Kubelet & Controller manager. - -This call-out does not pass "secrets" specified in Flexvolume spec. If your driver requires secrets, do not implement this call-out and instead use "mount" call-out and implement attach and mount in that call-out. - -``` - attach -``` - -#### Detach: -Detach the volume from the Kubelet node. Nodename param is only valid/relevant if "--enable-controller-attach-detach" Kubelet option is enabled. Called from both Kubelet & Controller manager. -``` - detach -``` - -#### Wait for attach: -Wait for the volume to be attached on the remote node. On success, the path to the device is returned. Called from both Kubelet & Controller manager. - -``` - waitforattach -``` - -#### Volume is Attached: -Check the volume is attached on the node. Called from both Kubelet & Controller manager. - -``` - isattached -``` - -#### Mount device: -Mount device mounts the device to a global path which individual pods can then bind mount. Called only from Kubelet. - -This call-out does not pass "secrets" specified in Flexvolume spec. If your driver requires secrets, do not implement this call-out and instead use "mount" call-out and implement attach and mount in that call-out. - -``` - mountdevice -``` - -#### Unmount device: -Unmounts the global mount for the device. This is called once all bind mounts have been unmounted. Called only from Kubelet. - -``` - unmountdevice -``` - -#### Mount: -Mount the volume at the mount dir. This call-out defaults to bind mount for drivers which implement attach & mount-device call-outs. Called only from Kubelet. - -``` - mount -``` - -#### Unmount: -Unmount the volume. This call-out defaults to bind mount for drivers which implement attach & mount-device call-outs. Called only from Kubelet. - -``` - unmount -``` - -See [lvm](lvm) & [nfs](nfs) for a quick example on how to write a simple flexvolume driver. - -### Driver output: - -Flexvolume expects the driver to reply with the status of the operation in the -following format. - -``` -{ - "status": "", - "message": "", - "device": "" - "volumeName": "" - "attached": -} -``` - -### Default Json options - -In addition to the flags specified by the user in the Options field of the FlexVolumeSource, the following flags are also passed to the executable. -Note: Secrets are passed only to "mount/unmount" call-outs. - -``` -"kubernetes.io/fsType":"", -"kubernetes.io/readwrite":"", -"kubernetes.io/secret/key1":"" -... -"kubernetes.io/secret/keyN":"" -``` - -### Example of Flexvolume - -See [nginx.yaml](nginx.yaml) & [nginx-nfs.yaml](nginx-nfs.yaml) for a quick example on how to use Flexvolume in a pod. - - -[![Analytics](https://kubernetes-site.appspot.com/UA-36037335-10/GitHub/examples/volumes/flexvolume/README.md?pixel)]() - +Please refer to https://github.com/kubernetes/community/tree/master/contributors/devel/flexvolume.md for documentation. \ No newline at end of file