kotovalexarian-likes-github
/
moby--moby
mirror of https://github.com/moby/moby.git
1
0
Fork 0
Code Releases Activity

Add a link to the new build instructions 

Signed-off-by: Misty Stanley-Jones <misty@docker.com>
This commit is contained in:
Misty Stanley-Jones 2016-10-12 16:23:01 -07:00
parent 29f08cf49b
commit 3aeaa9f8fd
16 changed files with 1611 additions and 5 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
Makefile
View File

@ -1,4 +1,4 @@
.PHONY: all binary build cross deb docs help init-go-pkg-cache install manpages rpm run shell test test-docker-py test-integration-cli test-unit tgz validate win
.PHONY: all binary build cross deb help init-go-pkg-cache install manpages rpm run shell test test-docker-py test-integration-cli test-unit tgz validate win
# set the graph driver as the current graphdriver if not set
DOCKER_GRAPHDRIVER := $(if $(DOCKER_GRAPHDRIVER),$(DOCKER_GRAPHDRIVER),$(shell docker info 2>&1 | grep "Storage Driver" | sed 's/.*: //'))
@ -56,7 +56,6 @@ DOCKER_MOUNT := $(if $(DOCKER_INCREMENTAL_BINARY),$(DOCKER_MOUNT) $(shell echo $
GIT_BRANCH := $(shell git rev-parse --abbrev-ref HEAD 2>/dev/null)
GIT_BRANCH_CLEAN := $(shell echo $(GIT_BRANCH) | sed -e "s/[^[:alnum:]]/-/g")
DOCKER_IMAGE := docker-dev$(if $(GIT_BRANCH_CLEAN),:$(GIT_BRANCH_CLEAN))
DOCKER_DOCS_IMAGE := docker-docs$(if $(GIT_BRANCH_CLEAN),:$(GIT_BRANCH_CLEAN))
DOCKER_PORT_FORWARD := $(if $(DOCKER_PORT),-p "$(DOCKER_PORT)",)
DOCKER_FLAGS := docker run --rm -i --privileged $(DOCKER_ENVS) $(DOCKER_MOUNT) $(DOCKER_PORT_FORWARD)
@ -93,8 +92,6 @@ cross: build ## cross build the binaries for darwin, freebsd and\nwindows
deb: build ## build the deb packages
$(DOCKER_RUN_DOCKER) hack/make.sh dynbinary build-deb
docs: ## build the docs
$(MAKE) -C docs docs
help: ## this help
@awk 'BEGIN {FS = ":.*?## "} /^[a-zA-Z_-]+:.*?## / {sub("\\\\n",sprintf("\n%22c"," "), $$2);printf "\033[36m%-20s\033[0m %s\n", $$1, $$2}' $(MAKEFILE_LIST)
@ -140,4 +137,3 @@ validate: build ## validate DCO, Seccomp profile generation, gofmt,\n./pkg/ isol
win: build ## cross build the binary for windows
$(DOCKER_RUN_DOCKER) hack/make.sh win

3
docs/README.md
View File

@ -3,6 +3,9 @@
The documentation for Docker Engine has been merged into
[the general documentation repo](https://github.com/docker/docker.github.io).
See the [README](https://github.com/docker/docker.github.io/blob/master/README.md)
for instructions on contributing to and building the documentation.
If you'd like to edit the current published version of the Engine docs,
do it in the master branch here:
https://github.com/docker/docker.github.io/tree/master/engine

216
docs/deprecated.md Normal file
View File

@ -0,0 +1,216 @@
<!--[metadata]>
+++
aliases = ["/engine/misc/deprecated/"]
title = "Deprecated Engine Features"
description = "Deprecated Features."
keywords = ["docker, documentation, about, technology, deprecate"]
[menu.main]
parent = "engine_use"
weight=80
+++
<![end-metadata]-->
# Deprecated Engine Features
The following list of features are deprecated in Engine.
To learn more about Docker Engine's deprecation policy,
see [Feature Deprecation Policy](index.md#feature-deprecation-policy).
### `repository:shortid` image references
**Deprecated In Release: [v1.13](https://github.com/docker/docker/releases/)**
**Target For Removal In Release: v1.16**
`repository:shortid` syntax for referencing images is very little used, collides with with tag references can be confused with digest references.
### `docker daemon` subcommand
**Deprecated In Release: [v1.13](https://github.com/docker/docker/releases/)**
**Target For Removal In Release: v1.16**
The daemon is moved to a separate binary (`dockerd`), and should be used instead.
### Three argument form in `docker import`
**Deprecated In Release: [v0.6.7](https://github.com/docker/docker/releases/tag/v0.6.7)**
**Removed In Release: [v1.12.0](https://github.com/docker/docker/releases/tag/v1.12.0)**
The `docker import` command format 'file|URL|- [REPOSITORY [TAG]]' is deprecated since November 2013. It's no more supported.
### `-h` shorthand for `--help`
**Deprecated In Release: [v1.12.0](https://github.com/docker/docker/releases/tag/v1.12.0)**
**Target For Removal In Release: v1.15**
The shorthand (`-h`) is less common than `--help` on Linux and cannot be used
on all subcommands (due to it conflicting with, e.g. `-h` / `--hostname` on
`docker create`). For this reason, the `-h` shorthand was not printed in the
"usage" output of subcommands, nor documented, and is now marked "deprecated".
### `-e` and `--email` flags on `docker login`
**Deprecated In Release: [v1.11.0](https://github.com/docker/docker/releases/tag/v1.11.0)**
**Target For Removal In Release: v1.14**
The docker login command is removing the ability to automatically register for an account with the target registry if the given username doesn't exist. Due to this change, the email flag is no longer required, and will be deprecated.
### Separator (`:`) of `--security-opt` flag on `docker run`
**Deprecated In Release: [v1.11.0](https://github.com/docker/docker/releases/tag/v1.11.0)**
**Target For Removal In Release: v1.14**
The flag `--security-opt` doesn't use the colon separator(`:`) anymore to divide keys and values, it uses the equal symbol(`=`) for consistency with other similar flags, like `--storage-opt`.
### `/containers/(id or name)/copy` endpoint
**Deprecated In Release: [v1.8.0](https://github.com/docker/docker/releases/tag/v1.8.0)**
**Removed In Release: [v1.12.0](https://github.com/docker/docker/releases/tag/v1.12.0)**
The endpoint `/containers/(id or name)/copy` is deprecated in favor of `/containers/(id or name)/archive`.
### Ambiguous event fields in API
**Deprecated In Release: [v1.10.0](https://github.com/docker/docker/releases/tag/v1.10.0)**
The fields `ID`, `Status` and `From` in the events API have been deprecated in favor of a more rich structure.
See the events API documentation for the new format.
### `-f` flag on `docker tag`
**Deprecated In Release: [v1.10.0](https://github.com/docker/docker/releases/tag/v1.10.0)**
**Removed In Release: [v1.12.0](https://github.com/docker/docker/releases/tag/v1.12.0)**
To make tagging consistent across the various `docker` commands, the `-f` flag on the `docker tag` command is deprecated. It is not longer necessary to specify `-f` to move a tag from one image to another. Nor will `docker` generate an error if the `-f` flag is missing and the specified tag is already in use.
### HostConfig at API container start
**Deprecated In Release: [v1.10.0](https://github.com/docker/docker/releases/tag/v1.10.0)**
**Removed In Release: [v1.12.0](https://github.com/docker/docker/releases/tag/v1.12.0)**
Passing an `HostConfig` to `POST /containers/{name}/start` is deprecated in favor of
defining it at container creation (`POST /containers/create`).
### Docker ps 'before' and 'since' options
**Deprecated In Release: [v1.10.0](https://github.com/docker/docker/releases/tag/v1.10.0)**
**Removed In Release: [v1.12.0](https://github.com/docker/docker/releases/tag/v1.12.0)**
The `docker ps --before` and `docker ps --since` options are deprecated.
Use `docker ps --filter=before=...` and `docker ps --filter=since=...` instead.
### Docker search 'automated' and 'stars' options
**Deprecated in Release: [v1.12.0](https://github.com/docker/docker/releases/tag/v1.12.0)**
**Target For Removal In Release: v1.15**
The `docker search --automated` and `docker search --stars` options are deprecated.
Use `docker search --filter=is-automated=...` and `docker search --filter=stars=...` instead.
### Driver Specific Log Tags
**Deprecated In Release: [v1.9.0](https://github.com/docker/docker/releases/tag/v1.9.0)**
**Removed In Release: [v1.12.0](https://github.com/docker/docker/releases/tag/v1.12.0)**
Log tags are now generated in a standard way across different logging drivers.
Because of which, the driver specific log tag options `syslog-tag`, `gelf-tag` and
`fluentd-tag` have been deprecated in favor of the generic `tag` option.
docker --log-driver=syslog --log-opt tag="{{.ImageName}}/{{.Name}}/{{.ID}}"
### LXC built-in exec driver
**Deprecated In Release: [v1.8.0](https://github.com/docker/docker/releases/tag/v1.8.0)**
**Removed In Release: [v1.10.0](https://github.com/docker/docker/releases/tag/v1.10.0)**
The built-in LXC execution driver, the lxc-conf flag, and API fields have been removed.
### Old Command Line Options
**Deprecated In Release: [v1.8.0](https://github.com/docker/docker/releases/tag/v1.8.0)**
**Removed In Release: [v1.10.0](https://github.com/docker/docker/releases/tag/v1.10.0)**
The flags `-d` and `--daemon` are deprecated in favor of the `daemon` subcommand:
docker daemon -H ...
The following single-dash (`-opt`) variant of certain command line options
are deprecated and replaced with double-dash options (`--opt`):
docker attach -nostdin
docker attach -sig-proxy
docker build -no-cache
docker build -rm
docker commit -author
docker commit -run
docker events -since
docker history -notrunc
docker images -notrunc
docker inspect -format
docker ps -beforeId
docker ps -notrunc
docker ps -sinceId
docker rm -link
docker run -cidfile
docker run -dns
docker run -entrypoint
docker run -expose
docker run -link
docker run -lxc-conf
docker run -n
docker run -privileged
docker run -volumes-from
docker search -notrunc
docker search -stars
docker search -t
docker search -trusted
docker tag -force
The following double-dash options are deprecated and have no replacement:
docker run --cpuset
docker run --networking
docker ps --since-id
docker ps --before-id
docker search --trusted
**Deprecated In Release: [v1.5.0](https://github.com/docker/docker/releases/tag/v1.5.0)**
**Removed In Release: [v1.12.0](https://github.com/docker/docker/releases/tag/v1.12.0)**
The single-dash (`-help`) was removed, in favor of the double-dash `--help`
docker -help
docker [COMMAND] -help
### `--run` flag on docker commit
**Deprecated In Release: [v0.10.0](https://github.com/docker/docker/releases/tag/v0.10.0)**
**Removed In Release: [v1.13.0](https://github.com/docker/docker/releases/)**
The flag `--run` of the docker commit (and its short version `-run`) were deprecated in favor
of the `--changes` flag that allows to pass `Dockerfile` commands.
### Interacting with V1 registries
Version 1.9 adds a flag (`--disable-legacy-registry=false`) which prevents the docker daemon from `pull`, `push`, and `login` operations against v1 registries. Though disabled by default, this signals the intent to deprecate the v1 protocol.
### Docker Content Trust ENV passphrase variables name change
**Deprecated In Release: [v1.9.0](https://github.com/docker/docker/releases/tag/v1.9.0)**
**Removed In Release: [v1.12.0](https://github.com/docker/docker/releases/tag/v1.12.0)**
Since 1.9, Docker Content Trust Offline key has been renamed to Root key and the Tagging key has been renamed to Repository key. Due to this renaming, we're also changing the corresponding environment variables
- DOCKER_CONTENT_TRUST_OFFLINE_PASSPHRASE is now named DOCKER_CONTENT_TRUST_ROOT_PASSPHRASE
- DOCKER_CONTENT_TRUST_TAGGING_PASSPHRASE is now named DOCKER_CONTENT_TRUST_REPOSITORY_PASSPHRASE
### `MAINTAINER` in Dockerfile
**Deprecated In Release: v1.13.0**
`MAINTAINER` was an early very limited form of `LABEL` which should be used instead.

BIN
docs/extend/images/authz_additional_info.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 45 KiB

BIN
docs/extend/images/authz_allow.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 33 KiB

BIN
docs/extend/images/authz_chunked.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 32 KiB

BIN
docs/extend/images/authz_connection_hijack.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 38 KiB

BIN
docs/extend/images/authz_deny.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 26 KiB

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

@ -0,0 +1,272 @@
<!--[metadata]>
+++
aliases = [
"/engine/extend/"
]
title = "Managed plugin system"
description = "How develop and use a plugin with the managed plugin system"
keywords = ["API, Usage, plugins, documentation, developer"]
advisory = "experimental"
[menu.main]
parent = "engine_extend"
weight=1
+++
<![end-metadata]-->
# Docker Engine managed 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 created 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](../reference/commandline/index.md) 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",
"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 https://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. [See the Plugins Manifest reference](manifest.md). For example:
```bash
# cat manifest.json
{
"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"]
}
```
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.

93
docs/extend/legacy_plugins.md Normal file
View File

@ -0,0 +1,93 @@
<!--[metadata]>
+++
aliases = "/engine/extend/plugins/"
title = "Use Docker Engine plugins"
description = "How to add additional functionality to Docker with plugins extensions"
keywords = ["Examples, Usage, plugins, docker, documentation, user guide"]
[menu.main]
parent = "engine_extend"
weight=3
+++
<![end-metadata]-->
# Use Docker Engine plugins
This document describes the Docker Engine plugins generally available in Docker
Engine. To view information on plugins managed by Docker Engine currently in
experimental status, refer to [Docker Engine plugin system](index.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
volume and network plugins for Docker.
## Types of plugins
Plugins extend Docker's functionality. They come in specific types. For
example, a [volume plugin](plugins_volume.md) might enable Docker
volumes to persist across multiple Docker hosts and a
[network plugin](plugins_network.md) might provide network plumbing.
Currently Docker supports authorization, volume and network driver plugins. In the future it
will support additional plugin types.
## Installing a plugin
Follow the instructions in the plugin's documentation.
## Finding a plugin
The sections below provide an inexhaustive overview of available plugins.
<style>
#DocumentationText tr td:first-child { white-space: nowrap;}
</style>
### Network plugins
Plugin | Description
----------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
[Contiv Networking](https://github.com/contiv/netplugin) | An open source network plugin to provide infrastructure and security policies for a multi-tenant micro services deployment, while providing an integration to physical network for non-container workload. Contiv Networking implements the remote driver and IPAM APIs available in Docker 1.9 onwards.
[Kuryr Network Plugin](https://github.com/openstack/kuryr) | A network plugin is developed as part of the OpenStack Kuryr project and implements the Docker networking (libnetwork) remote driver API by utilizing Neutron, the OpenStack networking service. It includes an IPAM driver as well.
[Weave Network Plugin](https://www.weave.works/docs/net/latest/introducing-weave/) | A network plugin that creates a virtual network that connects your Docker containers - across multiple hosts or clouds and enables automatic discovery of applications. Weave networks are resilient, partition tolerant, secure and work in partially connected networks, and other adverse environments - all configured with delightful simplicity.
### Volume plugins
Plugin | Description
----------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
[Azure File Storage plugin](https://github.com/Azure/azurefile-dockervolumedriver) | Lets you mount Microsoft [Azure File Storage](https://azure.microsoft.com/blog/azure-file-storage-now-generally-available/) shares to Docker containers as volumes using the SMB 3.0 protocol. [Learn more](https://azure.microsoft.com/blog/persistent-docker-volumes-with-azure-file-storage/).
[Blockbridge plugin](https://github.com/blockbridge/blockbridge-docker-volume) | A volume plugin that provides access to an extensible set of container-based persistent storage options. It supports single and multi-host Docker environments with features that include tenant isolation, automated provisioning, encryption, secure deletion, snapshots and QoS.
[Contiv Volume Plugin](https://github.com/contiv/volplugin) | An open source volume plugin that provides multi-tenant, persistent, distributed storage with intent based consumption. It has support for Ceph and NFS.
[Convoy plugin](https://github.com/rancher/convoy) | A volume plugin for a variety of storage back-ends including device mapper and NFS. It's a simple standalone executable written in Go and provides the framework to support vendor-specific extensions such as snapshots, backups and restore.
[DRBD plugin](https://www.drbd.org/en/supported-projects/docker) | A volume plugin that provides highly available storage replicated by [DRBD](https://www.drbd.org). Data written to the docker volume is replicated in a cluster of DRBD nodes.
[Flocker plugin](https://clusterhq.com/docker-plugin/) | A volume plugin that provides multi-host portable volumes for Docker, enabling you to run databases and other stateful containers and move them around across a cluster of machines.
[gce-docker plugin](https://github.com/mcuadros/gce-docker) | A volume plugin able to attach, format and mount Google Compute [persistent-disks](https://cloud.google.com/compute/docs/disks/persistent-disks).
[GlusterFS plugin](https://github.com/calavera/docker-volume-glusterfs) | A volume plugin that provides multi-host volumes management for Docker using GlusterFS.
[Horcrux Volume Plugin](https://github.com/muthu-r/horcrux) | A volume plugin that allows on-demand, version controlled access to your data. Horcrux is an open-source plugin, written in Go, and supports SCP, [Minio](https://www.minio.io) and Amazon S3.
[HPE 3Par Volume Plugin](https://github.com/hpe-storage/python-hpedockerplugin/) | A volume plugin that supports HPE 3Par and StoreVirtual iSCSI storage arrays.
[IPFS Volume Plugin](http://github.com/vdemeester/docker-volume-ipfs) | An open source volume plugin that allows using an [ipfs](https://ipfs.io/) filesystem as a volume.
[Keywhiz plugin](https://github.com/calavera/docker-volume-keywhiz) | A plugin that provides credentials and secret management using Keywhiz as a central repository.
[Local Persist Plugin](https://github.com/CWSpear/local-persist) | A volume plugin that extends the default `local` driver's functionality by allowing you specify a mountpoint anywhere on the host, which enables the files to *always persist*, even if the volume is removed via `docker volume rm`.
[NetApp Plugin](https://github.com/NetApp/netappdvp) (nDVP) | A volume plugin that provides direct integration with the Docker ecosystem for the NetApp storage portfolio. The nDVP package supports the provisioning and management of storage resources from the storage platform to Docker hosts, with a robust framework for adding additional platforms in the future.
[Netshare plugin](https://github.com/ContainX/docker-volume-netshare) | A volume plugin that provides volume management for NFS 3/4, AWS EFS and CIFS file systems.
[OpenStorage Plugin](https://github.com/libopenstorage/openstorage) | A cluster-aware volume plugin that provides volume management for file and block storage solutions. It implements a vendor neutral specification for implementing extensions such as CoS, encryption, and snapshots. It has example drivers based on FUSE, NFS, NBD and EBS to name a few.
[Portworx Volume Plugin](https://github.com/portworx/px-dev) | A volume plugin that turns any server into a scale-out converged compute/storage node, providing container granular storage and highly available volumes across any node, using a shared-nothing storage backend that works with any docker scheduler.
[Quobyte Volume Plugin](https://github.com/quobyte/docker-volume) | A volume plugin that connects Docker to [Quobyte](http://www.quobyte.com/containers)'s data center file system, a general-purpose scalable and fault-tolerant storage platform.
[REX-Ray plugin](https://github.com/emccode/rexray) | A volume plugin which is written in Go and provides advanced storage functionality for many platforms including VirtualBox, EC2, Google Compute Engine, OpenStack, and EMC.
[Virtuozzo Storage and Ploop plugin](https://github.com/virtuozzo/docker-volume-ploop) | A volume plugin with support for Virtuozzo Storage distributed cloud file system as well as ploop devices.
[VMware vSphere Storage Plugin](https://github.com/vmware/docker-volume-vsphere) | Docker Volume Driver for vSphere enables customers to address persistent storage requirements for Docker containers in vSphere environments.
### Authorization plugins
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).
## Troubleshooting a plugin
If you are having problems with Docker after loading a plugin, ask the authors
of the plugin for help. The Docker team may not be able to assist you.
## Writing a plugin
If you are interested in writing a plugin for Docker, or seeing how they work
under the hood, see the [docker plugins reference](plugin_api.md).

222
docs/extend/manifest.md Normal file
View File

@ -0,0 +1,222 @@
<!--[metadata]>
+++
aliases = [
"/engine/extend/"
]
title = "Plugin manifest"
description = "How develop and use a plugin with the managed plugin system"
keywords = ["API, Usage, plugins, documentation, developer"]
advisory = "experimental"
[menu.main]
parent = "engine_extend"
weight=1
+++
<![end-metadata]-->
# 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"
}
]
}
```

15
docs/extend/menu.md Normal file
View File

@ -0,0 +1,15 @@
<!--[metadata]>
+++
title = "Implement plugins"
description = "Develop plugins and use existing plugins for Docker Engine"
keywords = ["extend, plugins, docker, documentation, developer"]
type="menu"
[menu.main]
identifier = "engine_extend"
parent="engine_use"
weight = 0
+++
<![end-metadata]-->
<!--menu page not rendered-->

192
docs/extend/plugin_api.md Normal file
View File

@ -0,0 +1,192 @@
<!--[metadata]>
+++
title = "Plugins API"
description = "How to write Docker plugins extensions "
keywords = ["API, Usage, plugins, documentation, developer"]
[menu.main]
parent = "engine_extend"
weight=7
+++
<![end-metadata]-->
# Docker Plugin API
Docker plugins are out-of-process extensions which add capabilities to the
Docker Engine.
This document describes the Docker Engine plugin API. To view information on
plugins managed by Docker Engine currently in experimental status, refer to
[Docker Engine plugin system](index.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](legacy_plugins.md).
## What plugins are
A plugin is a process running on the same or a different host as the docker daemon,
which registers itself by placing a file on the same docker host in one of the plugin
directories described in [Plugin discovery](#plugin-discovery).
Plugins have human-readable names, which are short, lowercase strings. For
example, `flocker` or `weave`.
Plugins can run inside or outside containers. Currently running them outside
containers is recommended.
## Plugin discovery
Docker discovers plugins by looking for them in the plugin directory whenever a
user or container tries to use one by name.
There are three types of files which can be put in the plugin directory.
* `.sock` files are UNIX domain sockets.
* `.spec` files are text files containing a URL, such as `unix:///other.sock` or `tcp://localhost:8080`.
* `.json` files are text files containing a full json specification for the plugin.
Plugins with UNIX domain socket files must run on the same docker host, whereas
plugins with spec or json files can run on a different host if a remote URL is specified.
UNIX domain socket files must be located under `/run/docker/plugins`, whereas
spec files can be located either under `/etc/docker/plugins` or `/usr/lib/docker/plugins`.
The name of the file (excluding the extension) determines the plugin name.
For example, the `flocker` plugin might create a UNIX socket at
`/run/docker/plugins/flocker.sock`.
You can define each plugin into a separated subdirectory if you want to isolate definitions from each other.
For example, you can create the `flocker` socket under `/run/docker/plugins/flocker/flocker.sock` and only
mount `/run/docker/plugins/flocker` inside the `flocker` container.
Docker always searches for unix sockets in `/run/docker/plugins` first. It checks for spec or json files under
`/etc/docker/plugins` and `/usr/lib/docker/plugins` if the socket doesn't exist. The directory scan stops as
soon as it finds the first plugin definition with the given name.
### JSON specification
This is the JSON format for a plugin:
```json
{
"Name": "plugin-example",
"Addr": "https://example.com/docker/plugin",
"TLSConfig": {
"InsecureSkipVerify": false,
"CAFile": "/usr/shared/docker/certs/example-ca.pem",
"CertFile": "/usr/shared/docker/certs/example-cert.pem",
"KeyFile": "/usr/shared/docker/certs/example-key.pem",
}
}
```
The `TLSConfig` field is optional and TLS will only be verified if this configuration is present.
## Plugin lifecycle
Plugins should be started before Docker, and stopped after Docker. For
example, when packaging a plugin for a platform which supports `systemd`, you
might use [`systemd` dependencies](
http://www.freedesktop.org/software/systemd/man/systemd.unit.html#Before=) to
manage startup and shutdown order.
When upgrading a plugin, you should first stop the Docker daemon, upgrade the
plugin, then start Docker again.
## Plugin activation
When a plugin is first referred to -- either by a user referring to it by name
(e.g. `docker run --volume-driver=foo`) or a container already configured to
use a plugin being started -- Docker looks for the named plugin in the plugin
directory and activates it with a handshake. See Handshake API below.
Plugins are *not* activated automatically at Docker daemon startup. Rather,
they are activated only lazily, or on-demand, when they are needed.
## Systemd socket activation
Plugins may also be socket activated by `systemd`. The official [Plugins helpers](https://github.com/docker/go-plugins-helpers)
natively supports socket activation. In order for a plugin to be socket activated it needs
a `service` file and a `socket` file.
The `service` file (for example `/lib/systemd/system/your-plugin.service`):
```
[Unit]
Description=Your plugin
Before=docker.service
After=network.target your-plugin.socket
Requires=your-plugin.socket docker.service
[Service]
ExecStart=/usr/lib/docker/your-plugin
[Install]
WantedBy=multi-user.target
```
The `socket` file (for example `/lib/systemd/system/your-plugin.socket`):
```
[Unit]
Description=Your plugin
[Socket]
ListenStream=/run/docker/plugins/your-plugin.sock
[Install]
WantedBy=sockets.target
```
This will allow plugins to be actually started when the Docker daemon connects to
the sockets they're listening on (for instance the first time the daemon uses them
or if one of the plugin goes down accidentally).
## API design
The Plugin API is RPC-style JSON over HTTP, much like webhooks.
Requests flow *from* the Docker daemon *to* the plugin. So the plugin needs to
implement an HTTP server and bind this to the UNIX socket mentioned in the
"plugin discovery" section.
All requests are HTTP `POST` requests.
The API is versioned via an Accept header, which currently is always set to
`application/vnd.docker.plugins.v1+json`.
## Handshake API
Plugins are activated via the following "handshake" API call.
### /Plugin.Activate
**Request:** empty body
**Response:**
```
{
"Implements": ["VolumeDriver"]
}
```
Responds with a list of Docker subsystems which this plugin implements.
After activation, the plugin will then be sent events from this subsystem.
Possible values are:
* [`authz`](plugins_authorization.md)
* [`NetworkDriver`](plugins_network.md)
* [`VolumeDriver`](plugins_volume.md)
## Plugin retries
Attempts to call a method on a plugin are retried with an exponential backoff
for up to 30 seconds. This may help when packaging plugins as containers, since
it gives plugin containers a chance to start up before failing any user
containers which depend on them.
## Plugins helpers
To ease plugins development, we're providing an `sdk` for each kind of plugins
currently supported by Docker at [docker/go-plugins-helpers](https://github.com/docker/go-plugins-helpers).

256
docs/extend/plugins_authorization.md Normal file
View File

@ -0,0 +1,256 @@
<!--[metadata]>
+++
title = "Access authorization plugin"
description = "How to create authorization plugins to manage access control to your Docker daemon."
keywords = ["security, authorization, authentication, docker, documentation, plugin, extend"]
aliases = ["/engine/extend/authorization/"]
[menu.main]
parent = "engine_extend"
weight = 4
+++
<![end-metadata]-->
# Create an authorization plugin
This document describes the Docker Engine plugins generally available in Docker
Engine. To view information on plugins managed by Docker Engine currently in
experimental status, refer to [Docker Engine plugin system](index.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
require greater access control, you can create authorization plugins and add
them to your Docker daemon configuration. Using an authorization plugin, a
Docker administrator can configure granular access policies for managing access
to Docker daemon.
Anyone with the appropriate skills can develop an authorization plugin. These
skills, at their most basic, are knowledge of Docker, understanding of REST, and
sound programming knowledge. This document describes the architecture, state,
and methods information available to an authorization plugin developer.
## Basic principles
Docker's [plugin infrastructure](plugin_api.md) enables
extending Docker by loading, removing and communicating with
third-party components using a generic API. The access authorization subsystem
was built using this mechanism.
Using this subsystem, you don't need to rebuild the Docker daemon to add an
authorization plugin. You can add a plugin to an installed Docker daemon. You do
need to restart the Docker daemon to add a new plugin.
An authorization plugin approves or denies requests to the Docker daemon based
on both the current authentication context and the command context. The
authentication context contains all user details and the authentication method.
The command context contains all the relevant request data.
Authorization plugins must follow the rules described in [Docker Plugin API](plugin_api.md).
Each plugin must reside within directories described under the
[Plugin discovery](plugin_api.md#plugin-discovery) section.
**Note**: the abbreviations `AuthZ` and `AuthN` mean authorization and authentication
respectively.
## Default user authorization mechanism
If TLS is enabled in the [Docker daemon](../security/https.md), the default user authorization flow extracts the user details from the certificate subject name.
That is, the `User` field is set to the client certificate subject common name, and the `AuthenticationMethod` field is set to `TLS`.
## Basic architecture
You are responsible for registering your plugin as part of the Docker daemon
startup. You can install multiple plugins and chain them together. This chain
can be ordered. Each request to the daemon passes in order through the chain.
Only when all the plugins grant access to the resource, is the access granted.
When an HTTP request is made to the Docker daemon through the CLI or via the
remote API, the authentication subsystem passes the request to the installed
authentication plugin(s). The request contains the user (caller) and command
context. The plugin is responsible for deciding whether to allow or deny the
request.
The sequence diagrams below depict an allow and deny authorization flow:
![Authorization Allow flow](images/authz_allow.png)
![Authorization Deny flow](images/authz_deny.png)
Each request sent to the plugin includes the authenticated user, the HTTP
headers, and the request/response body. Only the user name and the
authentication method used are passed to the plugin. Most importantly, no user
credentials or tokens are passed. Finally, not all request/response bodies
are sent to the authorization plugin. Only those request/response bodies where
the `Content-Type` is either `text/*` or `application/json` are sent.
For commands that can potentially hijack the HTTP connection (`HTTP
Upgrade`), such as `exec`, the authorization plugin is only called for the
initial HTTP requests. Once the plugin approves the command, authorization is
not applied to the rest of the flow. Specifically, the streaming data is not
passed to the authorization plugins. For commands that return chunked HTTP
response, such as `logs` and `events`, only the HTTP request is sent to the
authorization plugins.
During request/response processing, some authorization flows might
need to do additional queries to the Docker daemon. To complete such flows,
plugins can call the daemon API similar to a regular user. To enable these
additional queries, the plugin must provide the means for an administrator to
configure proper authentication and security policies.
## Docker client flows
To enable and configure the authorization plugin, the plugin developer must
support the Docker client interactions detailed in this section.
### Setting up Docker daemon
Enable the authorization plugin with a dedicated command line flag in the
`--authorization-plugin=PLUGIN_ID` format. The flag supplies a `PLUGIN_ID`
value. This value can be the plugin’s socket or a path to a specification file.
Authorization plugins can be loaded without restarting the daemon. Refer
to the [`dockerd` documentation](../reference/commandline/dockerd.md#configuration-reloading) for more information.
```bash
$ dockerd --authorization-plugin=plugin1 --authorization-plugin=plugin2,...
```
Docker's authorization subsystem supports multiple `--authorization-plugin` parameters.
### Calling authorized command (allow)
```bash
$ docker pull centos
...
f1b10cd84249: Pull complete
...
```
### Calling unauthorized command (deny)
```bash
$ docker pull centos
...
docker: Error response from daemon: authorization denied by plugin PLUGIN_NAME: volumes are not allowed.
```
### Error from plugins
```bash
$ docker pull centos
...
docker: Error response from daemon: plugin PLUGIN_NAME failed with error: AuthZPlugin.AuthZReq: Cannot connect to the Docker daemon. Is the docker daemon running on this host?.
```
## API schema and implementation
In addition to Docker's standard plugin registration method, each plugin
should implement the following two methods:
* `/AuthZPlugin.AuthZReq` This authorize request method is called before the Docker daemon processes the client request.
* `/AuthZPlugin.AuthZRes` This authorize response method is called before the response is returned from Docker daemon to the client.
#### /AuthZPlugin.AuthZReq
**Request**:
```json
{
"User": "The user identification",
"UserAuthNMethod": "The authentication method used",
"RequestMethod": "The HTTP method",
"RequestURI": "The HTTP request URI",
"RequestBody": "Byte array containing the raw HTTP request body",
"RequestHeader": "Byte array containing the raw HTTP request header as a map[string][]string "
}
```
**Response**:
```json
{
"Allow": "Determined whether the user is allowed or not",
"Msg": "The authorization message",
"Err": "The error message if things go wrong"
}
```
#### /AuthZPlugin.AuthZRes
**Request**:
```json
{
"User": "The user identification",
"UserAuthNMethod": "The authentication method used",
"RequestMethod": "The HTTP method",
"RequestURI": "The HTTP request URI",
"RequestBody": "Byte array containing the raw HTTP request body",
"RequestHeader": "Byte array containing the raw HTTP request header as a map[string][]string",
"ResponseBody": "Byte array containing the raw HTTP response body",
"ResponseHeader": "Byte array containing the raw HTTP response header as a map[string][]string",
"ResponseStatusCode":"Response status code"
}
```
**Response**:
```json
{
"Allow": "Determined whether the user is allowed or not",
"Msg": "The authorization message",
"Err": "The error message if things go wrong"
}
```
### Request authorization
Each plugin must support two request authorization messages formats, one from the daemon to the plugin and then from the plugin to the daemon. The tables below detail the content expected in each message.
#### Daemon -> Plugin
Name | Type | Description
-----------------------|-------------------|-------------------------------------------------------
User | string | The user identification
Authentication method | string | The authentication method used
Request method | enum | The HTTP method (GET/DELETE/POST)
Request URI | string | The HTTP request URI including API version (e.g., v.1.17/containers/json)
Request headers | map[string]string | Request headers as key value pairs (without the authorization header)
Request body | []byte | Raw request body
#### Plugin -> Daemon
Name | Type | Description
--------|--------|----------------------------------------------------------------------------------
Allow | bool | Boolean value indicating whether the request is allowed or denied
Msg | string | Authorization message (will be returned to the client in case the access is denied)
Err | string | Error message (will be returned to the client in case the plugin encounter an error. The string value supplied may appear in logs, so should not include confidential information)
### Response authorization
The plugin must support two authorization messages formats, one from the daemon to the plugin and then from the plugin to the daemon. The tables below detail the content expected in each message.
#### Daemon -> Plugin
Name | Type | Description
----------------------- |------------------ |----------------------------------------------------
User | string | The user identification
Authentication method | string | The authentication method used
Request method | string | The HTTP method (GET/DELETE/POST)
Request URI | string | The HTTP request URI including API version (e.g., v.1.17/containers/json)
Request headers | map[string]string | Request headers as key value pairs (without the authorization header)
Request body | []byte | Raw request body
Response status code | int | Status code from the docker daemon
Response headers | map[string]string | Response headers as key value pairs
Response body | []byte | Raw docker daemon response body
#### Plugin -> Daemon
Name | Type | Description
--------|--------|----------------------------------------------------------------------------------
Allow | bool | Boolean value indicating whether the response is allowed or denied
Msg | string | Authorization message (will be returned to the client in case the access is denied)
Err | string | Error message (will be returned to the client in case the plugin encounter an error. The string value supplied may appear in logs, so should not include confidential information)

73
docs/extend/plugins_network.md Normal file
View File

@ -0,0 +1,73 @@
<!--[metadata]>
+++
title = "Docker network driver plugins"
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. To view information on plugins
managed by Docker Engine, refer to [Docker Engine plugin system](index.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
LibNetwork project. Each plugin is implemented as a "remote driver" for
LibNetwork, which shares plugin infrastructure with Engine. Effectively, network
driver plugins are activated in the same way as other plugins, and use the same
kind of protocol.
## Network driver plugins and swarm mode
Docker 1.12 adds support for cluster management and orchestration called
[swarm mode](../swarm/index.md). Docker Engine running in swarm mode currently
only supports the built-in overlay driver for networking. Therefore existing
networking plugins will not work in swarm mode.
When you run Docker Engine outside of swarm mode, all networking plugins that
worked in Docker 1.11 will continue to function normally. They do not require
any modification.
## Using network driver plugins
The means of installing and running a network driver plugin depend on the
particular plugin. So, be sure to install your plugin according to the
instructions obtained from the plugin developer.
Once running however, network driver plugins are used just like the built-in
network drivers: by being mentioned as a driver in network-oriented Docker
commands. For example,
$ docker network create --driver weave mynet
Some network driver plugins are listed in [plugins](legacy_plugins.md)
The `mynet` network is now owned by `weave`, so subsequent commands
referring to that network will be sent to the plugin,
$ docker run --network=mynet busybox top
## Write a network plugin
Network plugins implement the [Docker plugin
API](https://docs.docker.com/extend/plugin_api/) and the network plugin protocol
## Network plugin protocol
The network driver protocol, in addition to the plugin activation call, is
documented as part of libnetwork:
[https://github.com/docker/libnetwork/blob/master/docs/remote.md](https://github.com/docker/libnetwork/blob/master/docs/remote.md).
# Related Information
To interact with the Docker maintainers and other interested users, see the IRC channel `#docker-network`.
- [Docker networks feature overview](../userguide/networking/index.md)
- The [LibNetwork](https://github.com/docker/libnetwork) project

268
docs/extend/plugins_volume.md Normal file
View File

@ -0,0 +1,268 @@
<!--[metadata]>
+++
title = "Volume plugins"
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
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 documentation](legacy_plugins.md) for more information.
## Changelog
### 1.12.0
- Add `Status` field to `VolumeDriver.Get` response ([#21006](https://github.com/docker/docker/pull/21006#))
- Add `VolumeDriver.Capabilities` to get capabilities of the volume driver([#22077](https://github.com/docker/docker/pull/22077))
### 1.10.0
- Add `VolumeDriver.Get` which gets the details about the volume ([#16534](https://github.com/docker/docker/pull/16534))
- Add `VolumeDriver.List` which lists all volumes owned by the driver ([#16534](https://github.com/docker/docker/pull/16534))
### 1.8.0
- Initial support for volume driver plugins ([#14659](https://github.com/docker/docker/pull/14659))
## Command-line changes
A volume plugin makes use of the `-v`and `--volume-driver` flag on the `docker run` command. The `-v` flag accepts a volume name and the `--volume-driver` flag a driver type, for example:
$ docker run -ti -v volumename:/data --volume-driver=flocker busybox sh
This command passes the `volumename` through to the volume plugin as a
user-given name for the volume. The `volumename` must not begin with a `/`.
By having the user specify a `volumename`, a plugin can associate the volume
with an external volume beyond the lifetime of a single container or container
host. This can be used, for example, to move a stateful container from one
server to another.
By specifying a `volumedriver` in conjunction with a `volumename`, users can use plugins such as [Flocker](https://clusterhq.com/docker-plugin/) to manage volumes external to a single host, such as those on EBS.
## Create a VolumeDriver
The container creation endpoint (`/containers/create`) accepts a `VolumeDriver`
field of type `string` allowing to specify the name of the driver. It's default
value of `"local"` (the default driver for local volumes).
## Volume plugin protocol
If a plugin registers itself as a `VolumeDriver` when activated, then it is
expected to provide writeable paths on the host filesystem for the Docker
daemon to provide to containers to consume.
The Docker daemon handles bind-mounting the provided paths into user
containers.
> **Note**: Volume plugins should *not* write data to the `/var/lib/docker/`
> directory, including `/var/lib/docker/volumes`. The `/var/lib/docker/`
> directory is reserved for Docker.
### /VolumeDriver.Create
**Request**:
```json
{
"Name": "volume_name",
"Opts": {}
}
```
Instruct the plugin that the user wants to create a volume, given a user
specified volume name. The plugin does not need to actually manifest the
volume on the filesystem yet (until Mount is called).
Opts is a map of driver specific options passed through from the user request.
**Response**:
```json
{
"Err": ""
}
```
Respond with a string error if an error occurred.
### /VolumeDriver.Remove
**Request**:
```json
{
"Name": "volume_name"
}
```
Delete the specified volume from disk. This request is issued when a user invokes `docker rm -v` to remove volumes associated with a container.
**Response**:
```json
{
"Err": ""
}
```
Respond with a string error if an error occurred.
### /VolumeDriver.Mount
**Request**:
```json
{
"Name": "volume_name",
"ID": "b87d7442095999a92b65b3d9691e697b61713829cc0ffd1bb72e4ccd51aa4d6c"
}
```
Docker requires the plugin to provide a volume, given a user specified volume
name. This is called once per container start. If the same volume_name is requested
more than once, the plugin may need to keep track of each new mount request and provision
at the first mount request and deprovision at the last corresponding unmount request.
`ID` is a unique ID for the caller that is requesting the mount.
**Response**:
```json
{
"Mountpoint": "/path/to/directory/on/host",
"Err": ""
}
```
Respond with the path on the host filesystem where the volume has been made
available, and/or a string error if an error occurred.
### /VolumeDriver.Path
**Request**:
```json
{
"Name": "volume_name"
}
```
Docker needs reminding of the path to the volume on the host.
**Response**:
```json
{
"Mountpoint": "/path/to/directory/on/host",
"Err": ""
}
```
Respond with the path on the host filesystem where the volume has been made
available, and/or a string error if an error occurred. `Mountpoint` is optional,
however the plugin may be queried again later if one is not provided.
### /VolumeDriver.Unmount
**Request**:
```json
{
"Name": "volume_name",
"ID": "b87d7442095999a92b65b3d9691e697b61713829cc0ffd1bb72e4ccd51aa4d6c"
}
```
Indication that Docker no longer is using the named volume. This is called once
per container stop. Plugin may deduce that it is safe to deprovision it at
this point.
`ID` is a unique ID for the caller that is requesting the mount.
**Response**:
```json
{
"Err": ""
}
```
Respond with a string error if an error occurred.
### /VolumeDriver.Get
**Request**:
```json
{
"Name": "volume_name"
}
```
Get the volume info.
**Response**:
```json
{
"Volume": {
"Name": "volume_name",
"Mountpoint": "/path/to/directory/on/host",
"Status": {}
},
"Err": ""
}
```
Respond with a string error if an error occurred. `Mountpoint` and `Status` are
optional.
### /VolumeDriver.List
**Request**:
```json
{}
```
Get the list of volumes registered with the plugin.
**Response**:
```json
{
"Volumes": [
{
"Name": "volume_name",
"Mountpoint": "/path/to/directory/on/host"
}
],
"Err": ""
}
```
Respond with a string error if an error occurred. `Mountpoint` is optional.
### /VolumeDriver.Capabilities
**Request**:
```json
{}
```
Get the list of capabilities the driver supports.
The driver is not required to implement this endpoint, however in such cases
the default values will be taken.
**Response**:
```json
{
"Capabilities": {
"Scope": "global"
}
}
```
Supported scopes are `global` and `local`. Any other value in `Scope` will be
ignored and assumed to be `local`. Scope allows cluster managers to handle the
volume differently, for instance with a scope of `global`, the cluster manager
knows it only needs to create the volume once instead of on every engine. More
capabilities may be added in the future.