Guest24897
/
DockerCLI
mirror of https://github.com/docker/cli.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

edit plugin system doc, fix menu system 

Signed-off-by: Charles Smith <charles.smith@docker.com>
This commit is contained in:
Charles Smith 2016-08-16 11:53:36 -07:00 committed by Tibor Vass
parent 4755904cc3
commit 16de3a25f4
10 changed files with 305 additions and 279 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

20
docs/extend/index.md
View File

@ -1,20 +0,0 @@
<!--[metadata]>
+++
title = "Extend Engine"
description = "How to extend Docker Engine with plugins"
keywords = ["extend, plugins, docker, documentation, developer"]
[menu.main]
identifier = "engine_extend"
parent = "engine_use"
weight = 6
+++
<![end-metadata]-->
## Extending Docker Engine
Currently, you can extend Docker Engine by adding a plugin. This section contains the following topics:
* [New Docker Plugin System](new/index.md)
* [Legacy Docker Plugins](legacy/index.md)

22
docs/extend/legacy/index.md
View File

@ -1,22 +0,0 @@
<!--[metadata]>
+++
title = "Legacy Docker Plugins"
description = "How to extend Docker Engine with plugins"
keywords = ["extend, plugins, docker, documentation, developer"]
[menu.main]
identifier = "extend_legacy"
parent = "engine_extend"
weight = 7
+++
<![end-metadata]-->
## Legacy Docker Plugins
Currently, you can extend Docker Engine by adding a plugin. This section contains the following topics:
* [Understand Docker plugins](plugins.md)
* [Write a volume plugin](plugins_volume.md)
* [Write a network plugin](plugins_network.md)
* [Write an authorization plugin](plugins_authorization.md)
* [Docker plugin API](plugin_api.md)

10
docs/extend/legacy/plugins.md → docs/extend/legacy_plugins.md
View File

@ -5,11 +5,15 @@ description = "How to add additional functionality to Docker with plugins extens
keywords = ["Examples, Usage, plugins, docker, documentation, user guide"]
[menu.main]
parent = "engine_extend"
weight=-1
weight=3
+++
<![end-metadata]-->
# Understand Engine plugins
# Understand legacy Docker Engine plugins
This document describes the Docker Engine plugins generally available in Docker
Engine 1.12 and earlier. To view information on plugins managed by Docker
Engine, refer to [Docker Engine plugin system](plugins.md).
You can extend the capabilities of the Docker Engine by loading third-party
plugins. This page explains the types of plugins and provides links to several
@ -72,7 +76,7 @@ Plugin
### Authorization plugins
Plugin | Description
Plugin | Description
------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
[Twistlock AuthZ Broker](https://github.com/twistlock/authz) | A basic extendable authorization plugin that runs directly on the host or inside a container. This plugin allows you to define user policies that it evaluates during authorization. Basic authorization is provided if Docker daemon is started with the --tlsverify flag (username is extracted from the certificate common name).

9
docs/extend/new/index.md → docs/extend/menu.md
View File

@ -1,12 +1,13 @@
<!--[metadata]>
+++
title = "New Docker Plugin System"
title = "Extend Docker"
description = "How to extend Docker Engine with plugins"
keywords = ["extend, plugins, docker, documentation, developer"]
type="menu"
[menu.main]
identifier = "extend_new"
parent = "engine_extend"
weight = 7
identifier = "engine_extend"
parent="engine_use"
weight = 0
+++
<![end-metadata]-->

227
docs/extend/new/plugins.md
View File

@ -1,227 +0,0 @@
<!--[metadata]>
+++
title = "New Plugin System"
description = "How to operate and create a plugin with the new system"
keywords = ["API, Usage, plugins, documentation, developer"]
advisory = "experimental"
[menu.main]
parent = "engine_extend"
weight=1
+++
<![end-metadata]-->
# New Plugin System
The goal of this document is to describe the current state of the new plugin system available today in the **experimental build** of Docker 1.12.
The main difference, compared to legacy plugins, is that plugins are now managed by Docker: plugins are installed, started, stopped and removed by docker.
Only volume drivers are currently supported but more types will be added in the next release.
This document is split in two parts, the user perspective, “how to operate a plugin” and the developer perspective “how to create a plugin”
## How to operate a plugin
Plugins are distributed as docker images, so they can be hosted on the Docker Hub or on a private registry.
Installing a plugin is very easy, it’s a simple command: `docker plugin install`
This command is going to pull the plugin from the Docker Hub / Private registry, ask the operator to accept privileges (for example, plugin requires access to a device on the host system), if necessary and enable it.
You can then check the status of the plugin with the docker plugin ls command, the plugin will be marked as ENABLED if it was started without issue.
Then, the plugin behavior is the same as legacy plugins, here is a full example using a sshfs plugin:
### install the plugin
```bash
$ docker plugin install vieux/sshfs
Plugin "vieux/sshfs" is requesting the following privileges:
- network: [host]
- capabilities: [CAP_SYS_ADMIN]
Do you grant the above permissions? [y/N] y
vieux/sshfs
```
Here the plugin requests 2 privileges, the `CAP_SYS_ADMIN` capability to be able to do mount inside the plugin and `host networking`.
### verify that the plugin has correctly started
##### by looking at the ENABLED column. (The value should be true)
```bash
$ docker plugin ls
NAME TAG ENABLED
vieux/sshfs latest true
```
### create a volume using the plugin installed above
```bash
$ docker volume create -d vieux/sshfs --name sshvolume -o sshcmd=user@1.2.3.4:/remote
sshvolume
```
### use the volume created above
```bash
$ docker run -v sshvolume:/data busybox ls /data
<content of /remote on machine 1.2.3.4>
```
### verify that the plugin was created successfully
```bash
$ docker volume ls
DRIVER NAME
vieux/sshfs sshvolume
```
It’s also possible to stop a plugin with the `docker plugin disable` command and to remove a plugin with `docker plugin remove`.
See the [command line reference](../engine/reference/commandline/) for more information.
## How to create a plugin
The creation of plugin is currently a manual process, in the future release, a command such as `docker plugin build` will be added to automate the process. So here we are going to describe the format of an existing enabled plugin, to create a plugin you have to manually craft all those files by hand.
Plugins are stored in `/var/lib/docker/plugins`. See this example:
```bash
# ls -la /var/lib/docker/plugins
total 20
drwx------ 4 root root 4096 Aug 8 18:03 .
drwx--x--x 12 root root 4096 Aug 8 17:53 ..
drwxr-xr-x 3 root root 4096 Aug 8 17:56 cd851ce43a403
-rw------- 1 root root 2107 Aug 8 18:03 plugins.json
```
The file `plugins.json` is an inventory of all installed plugins, see an example of the content:
```bash
# cat plugins.json
{
"cd851ce43a403": {
"plugin": {
"Manifest": {
"Args": {
"Value": null,
"Settable": null,
"Description": "",
"Name": ""
},
"Env": null,
"Devices": null,
"Mounts": null,
"Capabilities": [
"CAP_SYS_ADMIN"
],
"ManifestVersion": "v0.1",
"Description": "sshFS plugin for Docker",
"Documentation": "https://docs.docker.com/engine/extend/plugins/",
"Interface": {
"Socket": "sshfs.sock",
"Types": [
"docker.volumedriver/1.0"
]
},
"Entrypoint": [
"/go/bin/docker-volume-sshfs"
],
"Workdir": "",
"User": {},
"Network": {
"Type": "host"
}
},
"Config": {
"Devices": null,
"Args": null,
"Env": [],
"Mounts": []
},
"Active": true,
"Tag": "latest",
"Name": "vieux/sshfs",
"Id": "cd851ce43a403"
}
}
}
```
Each folder represents a plugin, for example:
```bash
# ls -la /var/lib/docker/plugins/cd851ce43a403
total 12
drwx------ 19 root root 4096 Aug 8 17:56 rootfs
-rw-r--r-- 1 root root 50 Aug 8 17:56 plugin-config.json
-rw------- 1 root root 347 Aug 8 17:56 manifest.json
```
rootfs represents the root filesystem of the plugin, in this example, it was created from this Dockerfile as follows:
_Note: `/run/docker/plugins` is mandatory for docker to communicate with the plugin._
```bash
$ git clone github.com/vieux/docker-volume-sshfs
$ cd docker-volume-sshfs
$ docker build -t rootfs .
$ id=$(docker create rootfs true) # id was cd851ce43a403 when the image was created
$ mkdir -p /var/lib/docker/plugins/$id/rootfs
$ docker export "$id" | tar -x -C /var/lib/docker/plugins/$id/rootfs
$ docker rm -vf "$id"
$ docker rmi rootfs
```
`manifest.json` describe the plugin and `plugin-config.json` contains some runtime parameters, see for example:
```bash
# cat manifest.json
{
"manifestVersion": "v0.1",
"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"]
}
```
In this example, you can see the plugin is a volume driver, requires the `CAP_SYS_ADMIN` capability, `host networking`, `/go/bin/docker-volume-sshfs` as entrypoint and is going to use `/run/docker/plugins/sshfs.sock` to communicate with the docker engine.
```bash
# cat plugin-config.json
{
"Devices": null,
"Args": null,
"Env": [],
"Mounts": []
}
```
No runtime parameters are needed for this plugin.
Both `manifest.json` and `plugin-config.json` are part of the `plugins.json`.
`manifest.json` is read-only and `plugin-config.json` is read-write.
To sum up, here are the steps required to create a plugin today:
0. choose the name of the plugins, same format as images, for example `<repo_name>/<name>`
1. create a rootfs as showed above in `/var/lib/docker/plugins/$id/rootfs`
2. create manifest.json file in `/var/lib/docker/plugins/$id/` as shown above
3. create a `plugin-config.json` if needed, as shown above.
4. create or add a section to `/var/lib/docker/plugins/plugins.json` as shown above, use
`<user>/<name>` as “Name” and `$id` as “Id”
5. restart docker
6. `docker plugin ls`
a. if your plugin is listed as `ENABLED=true`, go to 7.
b. if the plugins is not listed or listed as `ENABLED=false` something went wrong, look at the daemon logs.
7. if not logged in already, use `docker login` to authenticate against a registry.
8. push the plugin with `docker plugin push <repo_name>/<name>`

8
docs/extend/legacy/plugin_api.md → docs/extend/plugin_api.md
View File

@ -5,7 +5,7 @@ description = "How to write Docker plugins extensions "
keywords = ["API, Usage, plugins, documentation, developer"]
[menu.main]
parent = "engine_extend"
weight=1
weight=7
+++
<![end-metadata]-->
@ -14,9 +14,13 @@ weight=1
Docker plugins are out-of-process extensions which add capabilities to the
Docker Engine.
This document describes the Docker Engine plugin API generally available in
Docker Engine 1.12 and earlier. To view information on plugins managed by Docker
Engine, refer to [Docker Engine plugin system](plugins.md).
This page is intended for people who want to develop their own Docker plugin.
If you just want to learn about or use Docker plugins, look
[here](plugins.md).
[here](legacy_plugins.md).
## What plugins are

272
docs/extend/plugins.md Normal file
View File

@ -0,0 +1,272 @@
<!--[metadata]>
+++
aliases = [
"/engine/extend/"
]
title = "New Plugin System"
description = "How to operate and create a plugin with the new system"
keywords = ["API, Usage, plugins, documentation, developer"]
advisory = "experimental"
[menu.main]
parent = "engine_extend"
weight=1
+++
<![end-metadata]-->
# Docker Engine plugin system
This document describes the plugin system available today in the **experimental
build** of Docker 1.12:
* [How to operate an existing plugin](#how-to-operate-a-plugin)
* [How to develop a plugin](#how-to-develop-a-plugin)
Unlike the legacy plugin system, you now manage plugins using Docker Engine:
* install plugins
* start plugins
* stop plugins
* remove plugins
The current Docker Engine plugin system only supports volume drivers. We are
adding more plugin driver types in the future releases.
For information on Docker Engine plugins generally available in Docker Engine
1.12 and earlier, refer to [Understand legacy Docker Engine plugins](legacy_plugins.md).
## How to operate a plugin
Plugins are distributed as Docker images, so develpers can host them on Docker
Hub or on a private registry.
You install the plugin using a single command: `docker plugin install <PLUGIN>`.
The `plugin install` command pulls the plugin from the Docker Hub or private
registry. If necessary the CLI prompts you to accept any privilige requriements.
For example the plugin may require access to a device on the host system.
Finally it enables the plugin.
Run `docker plugin ls` to check the status of installed plugins. The Engine
markes plugins that are started without issues as `ENABLED`.
After you install a plugin, the plugin behavior is the same as legacy plugins.
The following example demonstrates how to install the `sshfs` plugin and use it
to create a volume.
1. Install the `sshfs` plugin.
```bash
$ docker plugin install vieux/sshfs
Plugin "vieux/sshfs" is requesting the following privileges:
- network: [host]
- capabilities: [CAP_SYS_ADMIN]
Do you grant the above permissions? [y/N] y
vieux/sshfs
```
The plugin requests 2 privileges, the `CAP_SYS_ADMIN` capability to be able
to do mount inside the plugin and `host networking`.
2. Check for a value of `true` the `ENABLED` column to verify the plugin
started without error.
```bash
$ docker plugin ls
NAME TAG ENABLED
vieux/sshfs latest true
```
3. Create a volume using the plugin.
```bash
$ docker volume create \
-d vieux/sshfs \
--name sshvolume \
-o sshcmd=user@1.2.3.4:/remote
sshvolume
```
4. Use the volume `sshvolume`.
```bash
$ docker run -v sshvolume:/data busybox ls /data
<content of /remote on machine 1.2.3.4>
```
5. Verify the plugin successfully crated the volume.
```bash
$ docker volume ls
DRIVER NAME
vieux/sshfs sshvolume
```
You can stop a plugin with the `docker plugin disable`
command or remove a plugin with `docker plugin remove`.
See the [command line reference](../engine/reference/commandline/) for more
information.
## How to develop a plugin
Plugin creation is currently a manual process. We plan to add automation in a
future release with a command such as `docker plugin build`.
This section describes the format of an existing enabled plugin. You have to
create and format the plugin files by hand.
Plugins are stored in `/var/lib/docker/plugins`. For instance:
```bash
# ls -la /var/lib/docker/plugins
total 20
drwx------ 4 root root 4096 Aug 8 18:03 .
drwx--x--x 12 root root 4096 Aug 8 17:53 ..
drwxr-xr-x 3 root root 4096 Aug 8 17:56 cd851ce43a403
-rw------- 1 root root 2107 Aug 8 18:03 plugins.json
```
`plugins.json` is an inventory of all installed plugins. For example:
```bash
# cat plugins.json
{
"cd851ce43a403": {
"plugin": {
"Manifest": {
"Args": {
"Value": null,
"Settable": null,
"Description": "",
"Name": ""
},
"Env": null,
"Devices": null,
"Mounts": null,
"Capabilities": [
"CAP_SYS_ADMIN"
],
"ManifestVersion": "v0.1",
"Description": "sshFS plugin for Docker",
"Documentation": "https://docs.docker.com/engine/extend/plugins/",
"Interface": {
"Socket": "sshfs.sock",
"Types": [
"docker.volumedriver/1.0"
]
},
"Entrypoint": [
"/go/bin/docker-volume-sshfs"
],
"Workdir": "",
"User": {},
"Network": {
"Type": "host"
}
},
"Config": {
"Devices": null,
"Args": null,
"Env": [],
"Mounts": []
},
"Active": true,
"Tag": "latest",
"Name": "vieux/sshfs",
"Id": "cd851ce43a403"
}
}
}
```
Each folder represents a plugin. For example:
```bash
# ls -la /var/lib/docker/plugins/cd851ce43a403
total 12
drwx------ 19 root root 4096 Aug 8 17:56 rootfs
-rw-r--r-- 1 root root 50 Aug 8 17:56 plugin-config.json
-rw------- 1 root root 347 Aug 8 17:56 manifest.json
```
`rootfs` represents the root filesystem of the plugin. In this example, it was
created from a Dockerfile as follows:
>**Note:** `/run/docker/plugins` is mandatory for docker to communicate with
the plugin._
```bash
$ git clone github.com/vieux/docker-volume-sshfs
$ cd docker-volume-sshfs
$ docker build -t rootfs .
$ id=$(docker create rootfs true) # id was cd851ce43a403 when the image was created
$ mkdir -p /var/lib/docker/plugins/$id/rootfs
$ docker export "$id" | tar -x -C /var/lib/docker/plugins/$id/rootfs
$ docker rm -vf "$id"
$ docker rmi rootfs
```
`manifest.json` describes the plugin and `plugin-config.json` contains some
runtime parameters. For example:
```bash
# cat manifest.json
{
"manifestVersion": "v0.1",
"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"]
}
```
In this example, you can see the plugin is a volume driver, requires the
`CAP_SYS_ADMIN` capability, `host networking`, `/go/bin/docker-volume-sshfs` as
entrypoint and is going to use `/run/docker/plugins/sshfs.sock` to communicate
with the Docker Engine.
```bash
# cat plugin-config.json
{
"Devices": null,
"Args": null,
"Env": [],
"Mounts": []
}
```
This plugin doesn't require runtime parameters.
Both `manifest.json` and `plugin-config.json` are part of the `plugins.json`.
`manifest.json` is read-only and `plugin-config.json` is read-write.
To summarize, follow the steps below to create a plugin:
0. Choose a name for the plugin. Plugin name uses the same format as images,
for example: `<repo_name>/<name>`.
1. Create a rootfs in `/var/lib/docker/plugins/$id/rootfs`.
2. Create manifest.json file in `/var/lib/docker/plugins/$id/`.
3. Create a `plugin-config.json` if needed.
4. Create or add a section to `/var/lib/docker/plugins/plugins.json`. Use
`<user>/<name>` as “Name” and `$id` as “Id”.
5. Restart the Docker Engine.
6. Run `docker plugin ls`.
* If your plugin is listed as `ENABLED=true`, you can push it to the
registry.
* If the plugin is not listed or if `ENABLED=false`, something went wrong.
Check the daemon logs for errors.
7. If you are not already logged in, use `docker login` to authenticate against
a registry.
8. Run `docker plugin push <repo_name>/<name>` to push the plugin.

6
docs/extend/legacy/plugins_authorization.md → docs/extend/plugins_authorization.md
View File

@ -6,13 +6,17 @@ keywords = ["security, authorization, authentication, docker, documentation, plu
aliases = ["/engine/extend/authorization/"]
[menu.main]
parent = "engine_extend"
weight = -1
weight = 4
+++
<![end-metadata]-->
# Create an authorization plugin
This document describes Docker Engine authorization plugins generally
available in Docker Engine 1.12 and earlier. To view information on plugins
managed by Docker Engine, refer to [Docker Engine plugin system](plugins.md).
Docker's out-of-the-box authorization model is all or nothing. Any user with
permission to access the Docker daemon can run any Docker client command. The
same is true for callers using Docker's remote API to contact the daemon. If you

5
docs/extend/legacy/plugins_network.md → docs/extend/plugins_network.md
View File

@ -5,11 +5,16 @@ description = "Network driver plugins."
keywords = ["Examples, Usage, plugins, docker, documentation, user guide"]
[menu.main]
parent = "engine_extend"
weight=5
+++
<![end-metadata]-->
# Engine network driver plugins
This document describes Docker Engine network driver plugins generally
available in Docker Engine 1.12 and earlier. To view information on plugins
managed by Docker Engine, refer to [Docker Engine plugin system](plugins.md).
Docker Engine network plugins enable Engine deployments to be extended to
support a wide range of networking technologies, such as VXLAN, IPVLAN, MACVLAN
or something completely different. Network driver plugins are supported via the

5
docs/extend/legacy/plugins_volume.md → docs/extend/plugins_volume.md
View File

@ -5,11 +5,16 @@ description = "How to manage data with external volume plugins"
keywords = ["Examples, Usage, volume, docker, data, volumes, plugin, api"]
[menu.main]
parent = "engine_extend"
weight=6
+++
<![end-metadata]-->
# Write a volume plugin
This document describes Docker Engine volume plugins generally available in
Docker Engine 1.12 and earlier. To view information on plugins managed by Docker
Engine, refer to [Docker Engine plugin system](plugins.md).
Docker Engine volume plugins enable Engine deployments to be integrated with
external storage systems, such as Amazon EBS, and enable data volumes to persist
beyond the lifetime of a single Engine host. See the [plugin