Browse code
plugins: add example docs for a rexray plugin
Signed-off-by: Tibor Vass <tibor@docker.com>
(cherry picked from commit 5f713cecc5f65ea61db5b5362f26f96de9427eb0)
Signed-off-by: Victor Vieux <vieux@docker.com>
Tibor Vass authored on 2017/01/20 05:25:16Showing 2 changed files
| 1 | 1 |
new file mode 100644 |
| ... | ... |
@@ -0,0 +1,164 @@ |
| 0 |
+--- |
|
| 1 |
+description: Volume plugin for Amazon EBS |
|
| 2 |
+keywords: "API, Usage, plugins, documentation, developer, amazon, ebs, rexray, volume" |
|
| 3 |
+title: Volume plugin for Amazon EBS |
|
| 4 |
+--- |
|
| 5 |
+ |
|
| 6 |
+<!-- This file is maintained within the docker/docker Github |
|
| 7 |
+ repository at https://github.com/docker/docker/. Make all |
|
| 8 |
+ pull requests against that repo. If you see this file in |
|
| 9 |
+ another repository, consider it read-only there, as it will |
|
| 10 |
+ periodically be overwritten by the definitive file. Pull |
|
| 11 |
+ requests which include edits to this file in other repositories |
|
| 12 |
+ will be rejected. |
|
| 13 |
+--> |
|
| 14 |
+ |
|
| 15 |
+# A proof-of-concept Rexray plugin |
|
| 16 |
+ |
|
| 17 |
+In this example, a simple Rexray plugin will be created for the purposes of using |
|
| 18 |
+it on an Amazon EC2 instance with EBS. It is not meant to be a complete Rexray plugin. |
|
| 19 |
+ |
|
| 20 |
+The example source is available at [https://github.com/tiborvass/rexray-plugin](https://github.com/tiborvass/rexray-plugin). |
|
| 21 |
+ |
|
| 22 |
+To learn more about Rexray: [https://github.com/codedellemc/rexray](https://github.com/codedellemc/rexray) |
|
| 23 |
+ |
|
| 24 |
+## 1. Make a Docker image |
|
| 25 |
+ |
|
| 26 |
+The following is the Dockerfile used to containerize rexray. |
|
| 27 |
+ |
|
| 28 |
+```Dockerfile |
|
| 29 |
+FROM debian:jessie |
|
| 30 |
+RUN apt-get update && apt-get install -y --no-install-recommends wget ca-certificates |
|
| 31 |
+RUN wget https://dl.bintray.com/emccode/rexray/stable/0.6.4/rexray-Linux-x86_64-0.6.4.tar.gz -O rexray.tar.gz && tar -xvzf rexray.tar.gz -C /usr/bin && rm rexray.tar.gz |
|
| 32 |
+RUN mkdir -p /run/docker/plugins /var/lib/libstorage/volumes |
|
| 33 |
+ENTRYPOINT ["rexray"] |
|
| 34 |
+CMD ["--help"] |
|
| 35 |
+``` |
|
| 36 |
+ |
|
| 37 |
+To build it you can run `image=$(cat Dockerfile | docker build -q -)` and `$image` |
|
| 38 |
+will reference the containerized rexray image. |
|
| 39 |
+ |
|
| 40 |
+## 2. Extract rootfs |
|
| 41 |
+ |
|
| 42 |
+```sh |
|
| 43 |
+$ TMPDIR=/tmp/rexray # for the purpose of this example |
|
| 44 |
+$ # create container without running it, to extract the rootfs from image |
|
| 45 |
+$ docker create --name rexray "$image" |
|
| 46 |
+$ # save the rootfs to a tar archive |
|
| 47 |
+$ docker export -o $TMPDIR/rexray.tar rexray |
|
| 48 |
+$ # extract rootfs from tar archive to a rootfs folder |
|
| 49 |
+$ ( mkdir -p $TMPDIR/rootfs; cd $TMPDIR/rootfs; tar xf ../rexray.tar ) |
|
| 50 |
+``` |
|
| 51 |
+ |
|
| 52 |
+## 3. Add plugin configuration |
|
| 53 |
+ |
|
| 54 |
+We have to put the following JSON to `$TMPDIR/config.json`: |
|
| 55 |
+ |
|
| 56 |
+```json |
|
| 57 |
+{
|
|
| 58 |
+ "Args": {
|
|
| 59 |
+ "Description": "", |
|
| 60 |
+ "Name": "", |
|
| 61 |
+ "Settable": null, |
|
| 62 |
+ "Value": null |
|
| 63 |
+ }, |
|
| 64 |
+ "Description": "A proof-of-concept EBS plugin (using rexray) for Docker", |
|
| 65 |
+ "Documentation": "https://github.com/tiborvass/rexray-plugin", |
|
| 66 |
+ "Entrypoint": [ |
|
| 67 |
+ "/usr/bin/rexray", "service", "start", "-f" |
|
| 68 |
+ ], |
|
| 69 |
+ "Env": [ |
|
| 70 |
+ {
|
|
| 71 |
+ "Description": "", |
|
| 72 |
+ "Name": "REXRAY_SERVICE", |
|
| 73 |
+ "Settable": [ |
|
| 74 |
+ "value" |
|
| 75 |
+ ], |
|
| 76 |
+ "Value": "ebs" |
|
| 77 |
+ }, |
|
| 78 |
+ {
|
|
| 79 |
+ "Description": "", |
|
| 80 |
+ "Name": "EBS_ACCESSKEY", |
|
| 81 |
+ "Settable": [ |
|
| 82 |
+ "value" |
|
| 83 |
+ ], |
|
| 84 |
+ "Value": "" |
|
| 85 |
+ }, |
|
| 86 |
+ {
|
|
| 87 |
+ "Description": "", |
|
| 88 |
+ "Name": "EBS_SECRETKEY", |
|
| 89 |
+ "Settable": [ |
|
| 90 |
+ "value" |
|
| 91 |
+ ], |
|
| 92 |
+ "Value": "" |
|
| 93 |
+ } |
|
| 94 |
+ ], |
|
| 95 |
+ "Interface": {
|
|
| 96 |
+ "Socket": "rexray.sock", |
|
| 97 |
+ "Types": [ |
|
| 98 |
+ "docker.volumedriver/1.0" |
|
| 99 |
+ ] |
|
| 100 |
+ }, |
|
| 101 |
+ "Linux": {
|
|
| 102 |
+ "AllowAllDevices": true, |
|
| 103 |
+ "Capabilities": ["CAP_SYS_ADMIN"], |
|
| 104 |
+ "Devices": null |
|
| 105 |
+ }, |
|
| 106 |
+ "Mounts": [ |
|
| 107 |
+ {
|
|
| 108 |
+ "Source": "/dev", |
|
| 109 |
+ "Destination": "/dev", |
|
| 110 |
+ "Type": "bind", |
|
| 111 |
+ "Options": ["rbind"] |
|
| 112 |
+ } |
|
| 113 |
+ ], |
|
| 114 |
+ "Network": {
|
|
| 115 |
+ "Type": "host" |
|
| 116 |
+ }, |
|
| 117 |
+ "PropagatedMount": "/var/lib/libstorage/volumes", |
|
| 118 |
+ "User": {},
|
|
| 119 |
+ "WorkDir": "" |
|
| 120 |
+} |
|
| 121 |
+``` |
|
| 122 |
+ |
|
| 123 |
+Please note a couple of points: |
|
| 124 |
+- `PropagatedMount` is needed so that the docker daemon can see mounts done by the |
|
| 125 |
+rexray plugin from within the container, otherwise the docker daemon is not able |
|
| 126 |
+to mount a docker volume. |
|
| 127 |
+- The rexray plugin needs dynamic access to host devices. For that reason, we |
|
| 128 |
+have to give it access to all devices under `/dev` and set `AllowAllDevices` to |
|
| 129 |
+true for proper access. |
|
| 130 |
+- The user of this simple plugin can change only 3 settings: `REXRAY_SERVICE`, |
|
| 131 |
+`EBS_ACCESSKEY` and `EBS_SECRETKEY`. This is because of the reduced scope of this |
|
| 132 |
+plugin. Ideally other rexray parameters could also be set. |
|
| 133 |
+ |
|
| 134 |
+## 4. Create plugin |
|
| 135 |
+ |
|
| 136 |
+`docker plugin create tiborvass/rexray-plugin "$TMPDIR"` will create the plugin. |
|
| 137 |
+ |
|
| 138 |
+```sh |
|
| 139 |
+$ docker plugin ls |
|
| 140 |
+ID NAME DESCRIPTION ENABLED |
|
| 141 |
+2475a4bd0ca5 tiborvass/rexray-plugin:latest A rexray volume plugin for Docker false |
|
| 142 |
+``` |
|
| 143 |
+ |
|
| 144 |
+## 5. Test plugin |
|
| 145 |
+ |
|
| 146 |
+```sh |
|
| 147 |
+$ docker plugin set tiborvass/rexray-plugin EBS_ACCESSKEY=$AWS_ACCESSKEY EBS_SECRETKEY=$AWS_SECRETKEY` |
|
| 148 |
+$ docker plugin enable tiborvass/rexray-plugin |
|
| 149 |
+$ docker volume create -d tiborvass/rexray-plugin my-ebs-volume |
|
| 150 |
+$ docker volume ls |
|
| 151 |
+DRIVER VOLUME NAME |
|
| 152 |
+tiborvass/rexray-plugin:latest my-ebs-volume |
|
| 153 |
+$ docker run --rm -v my-ebs-volume:/volume busybox sh -c 'echo bye > /volume/hi' |
|
| 154 |
+$ docker run --rm -v my-ebs-volume:/volume busybox cat /volume/hi |
|
| 155 |
+bye |
|
| 156 |
+``` |
|
| 157 |
+ |
|
| 158 |
+## 6. Push plugin |
|
| 159 |
+ |
|
| 160 |
+First, ensure you are logged in with `docker login`. Then you can run: |
|
| 161 |
+`docker plugin push tiborvass/rexray-plugin` to push it like a regular docker |
|
| 162 |
+image to a registry, to make it available for others to install via |
|
| 163 |
+`docker plugin install tiborvass/rexray-plugin EBS_ACCESSKEY=$AWS_ACCESSKEY EBS_SECRETKEY=$AWS_SECRETKEY`. |
| ... | ... |
@@ -154,7 +154,7 @@ This plugin is a volume driver. It requires a `host` network and the |
| 154 | 154 |
entrypoint and uses the `/run/docker/plugins/sshfs.sock` socket to communicate |
| 155 | 155 |
with Docker Engine. This plugin has no runtime parameters. |
| 156 | 156 |
|
| 157 |
-### Creating the plugin |
|
| 157 |
+#### Creating the plugin |
|
| 158 | 158 |
|
| 159 | 159 |
A new plugin can be created by running |
| 160 | 160 |
`docker plugin create <plugin-name> ./path/to/plugin/data` where the plugin |
| ... | ... |
@@ -163,4 +163,4 @@ in subdirectory `rootfs`. |
| 163 | 163 |
|
| 164 | 164 |
After that the plugin `<plugin-name>` will show up in `docker plugin ls`. |
| 165 | 165 |
Plugins can be pushed to remote registries with |
| 166 |
-`docker plugin push <plugin-name>`. |
|
| 167 | 166 |
\ No newline at end of file |
| 167 |
+`docker plugin push <plugin-name>`. |