From 44a16acff15b5da3103fd002ad5064cb7b375106 Mon Sep 17 00:00:00 2001 From: Victor Vieux Date: Wed, 7 Sep 2016 02:34:57 -0700 Subject: [PATCH] add some plugin manifest reference doc Signed-off-by: Victor Vieux --- docs/extend/index.md | 16 +-- docs/extend/manifest.md | 222 ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 230 insertions(+), 8 deletions(-) create mode 100644 docs/extend/manifest.md diff --git a/docs/extend/index.md b/docs/extend/index.md index 4e77c698e6..4ce1eac1c5 100644 --- a/docs/extend/index.md +++ b/docs/extend/index.md @@ -151,7 +151,7 @@ drwxr-xr-x 3 root root 4096 Aug 8 17:56 cd851ce43a403 "Capabilities": [ "CAP_SYS_ADMIN" ], - "ManifestVersion": "v0.1", + "ManifestVersion": "v0", "Description": "sshFS plugin for Docker", "Documentation": "https://docs.docker.com/engine/extend/plugins/", "Interface": { @@ -212,23 +212,23 @@ $ docker rmi rootfs ``` `manifest.json` describes the plugin and `plugin-config.json` contains some -runtime parameters. For example: +runtime parameters. [See the Plugins Manifest reference](manifest.md). For example: ```bash # cat manifest.json { - "manifestVersion": "v0.1", + "manifestVersion": "v0", "description": "sshFS plugin for Docker", "documentation": "https://docs.docker.com/engine/extend/plugins/", "entrypoint": ["/go/bin/docker-volume-sshfs"], "network": { "type": "host" }, - "interface" : { - "types": ["docker.volumedriver/1.0"], - "socket": "sshfs.sock" - }, - "capabilities": ["CAP_SYS_ADMIN"] + "interface" : { + "types": ["docker.volumedriver/1.0"], + "socket": "sshfs.sock" + }, + "capabilities": ["CAP_SYS_ADMIN"] } ``` diff --git a/docs/extend/manifest.md b/docs/extend/manifest.md new file mode 100644 index 0000000000..d47efce8e8 --- /dev/null +++ b/docs/extend/manifest.md @@ -0,0 +1,222 @@ + + +# Plugin Manifest Version 0 of Plugin V2 + +This document outlines the format of the V0 plugin manifest. The plugin +manifest described herein was introduced in the Docker daemon (experimental version) in the [v1.12.0 +release](https://github.com/docker/docker/commit/f37117045c5398fd3dca8016ea8ca0cb47e7312b). + +Plugin manifests describe the various constituents of a docker plugin. Plugin +manifests can be serialized to JSON format with the following media types: + +Manifest Type | Media Type +------------- | ------------- +manifest | "application/vnd.docker.plugin.v0+json" + + +## *Manifest* Field Descriptions + +Manifest provides the base accessible fields for working with V0 plugin format + in the registry. + +- **`manifestVersion`** *string* + + version of the plugin manifest (This version uses V0) + +- **`description`** *string* + + description of the plugin + +- **`documentation`** *string* + + link to the documentation about the plugin + +- **`interface`** *PluginInterface* + + interface implemented by the plugins, struct consisting of the following fields + + - **`types`** *string array* + + types indicate what interface(s) the plugin currently implements. + + currently supported: + + - **docker.volumedriver/1.0** + + - **`socket`** *string* + + socket is the name of the socket the engine should use to communicate with the plugins. + the socket will be created in `/run/docker/plugins`. + + +- **`entrypoint`** *string array* + + entrypoint of the plugin, see [`ENTRYPOINT`](../reference/builder.md#entrypoint) + +- **`workdir`** *string* + + workdir of the plugin, see [`WORKDIR`](../reference/builder.md#workdir) + +- **`network`** *PluginNetwork* + + network of the plugin, struct consisting of the following fields + + - **`type`** *string* + + network type. + + currently supported: + + - **bridge** + - **host** + - **none** + +- **`capabilities`** *array* + + capabilities of the plugin (*Linux only*), see list [`here`](https://github.com/opencontainers/runc/blob/master/libcontainer/SPEC.md#security) + +- **`mounts`** *PluginMount array* + + mount of the plugin, struct consisting of the following fields, see [`MOUNTS`](https://github.com/opencontainers/runtime-spec/blob/master/config.md#mounts) + + - **`name`** *string* + + name of the mount. + + - **`description`** *string* + + description of the mount. + + - **`source`** *string* + + source of the mount. + + - **`destination`** *string* + + destination of the mount. + + - **`type`** *string* + + mount type. + + - **`options`** *string array* + + options of the mount. + +- **`devices`** *PluginDevice array* + + device of the plugin, (*Linux only*), struct consisting of the following fields, see [`DEVICES`](https://github.com/opencontainers/runtime-spec/blob/master/config-linux.md#devices) + + - **`name`** *string* + + name of the device. + + - **`description`** *string* + + description of the device. + + - **`path`** *string* + + path of the device. + +- **`env`** *PluginEnv array* + + env of the plugin, struct consisting of the following fields + + - **`name`** *string* + + name of the env. + + - **`description`** *string* + + description of the env. + + - **`value`** *string* + + value of the env. + +- **`args`** *PluginArgs* + + args of the plugin, struct consisting of the following fields + + - **`name`** *string* + + name of the env. + + - **`description`** *string* + + description of the env. + + - **`value`** *string array* + + values of the args. + + +## Example Manifest + +*Example showing the 'tiborvass/no-remove' plugin manifest.* + +``` +{ + "manifestVersion": "v0", + "description": "A test plugin for Docker", + "documentation": "https://docs.docker.com/engine/extend/plugins/", + "entrypoint": ["plugin-no-remove", "/data"], + "interface" : { + "types": ["docker.volumedriver/1.0"], + "socket": "plugins.sock" + }, + "network": { + "type": "host" + }, + + "mounts": [ + { + "source": "/data", + "destination": "/data", + "type": "bind", + "options": ["shared", "rbind"] + }, + { + "destination": "/foobar", + "type": "tmpfs" + } + ], + + "args": { + "name": "args", + "description": "command line arguments", + "value": [] + }, + + "env": [ + { + "name": "DEBUG", + "description": "If set, prints debug messages", + "value": "1" + } + ], + + "devices": [ + { + "name": "device", + "description": "a host device to mount", + "path": "/dev/cpu_dma_latency" + } + ] +} + +```