diff --git a/docs/extend/index.md b/docs/extend/index.md new file mode 100644 index 0000000000..61f8689de5 --- /dev/null +++ b/docs/extend/index.md @@ -0,0 +1,22 @@ + + + +## Extending Docker + +Currently, you can extend Docker by adding a plugin. This section contains the following topics: + +* [Understand Docker plugins](plugins.md) +* [Write a volume plugin](plugins_volumes.md) +* [Docker plugin API](plugin_api.md) + + \ No newline at end of file diff --git a/experimental/plugin_api.md b/docs/extend/plugin_api.md similarity index 90% rename from experimental/plugin_api.md rename to docs/extend/plugin_api.md index 8820c15708..8e2862f6cb 100644 --- a/experimental/plugin_api.md +++ b/docs/extend/plugin_api.md @@ -1,13 +1,22 @@ -# Experimental: Docker Plugin API + + +# Docker Plugin API Docker plugins are out-of-process extensions which add capabilities to the Docker Engine. 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](/experimental/plugins.md). - -This is an experimental feature. For information on installing and using experimental features, see [the experimental feature overview](README.md). +[here](plugins.md). ## What plugins are @@ -77,10 +86,6 @@ manage startup and shutdown order. When upgrading a plugin, you should first stop the Docker daemon, upgrade the plugin, then start Docker again. -If a plugin is packaged as a container, this may cause issues. Plugins as -containers are currently considered experimental due to these shutdown/startup -ordering issues. These issues are mitigated by plugin retries (see below). - ## Plugin activation When a plugin is first referred to -- either by a user referring to it by name diff --git a/experimental/plugins.md b/docs/extend/plugins.md similarity index 50% rename from experimental/plugins.md rename to docs/extend/plugins.md index 15de7b767d..1578579b1c 100644 --- a/experimental/plugins.md +++ b/docs/extend/plugins.md @@ -1,14 +1,23 @@ -# Experimental: Extend Docker with a plugin + + +# Understand Docker plugins You can extend the capabilities of the Docker Engine by loading third-party -plugins. - -This is an experimental feature. For information on installing and using experimental features, see [the experimental feature overview](README.md). +plugins. ## Types of plugins Plugins extend Docker's functionality. They come in specific types. For -example, a [volume plugin](/experimental/plugins_volume.md) might enable Docker +example, a [volume plugin](plugins_volume.md) might enable Docker volumes to persist across multiple Docker hosts. Currently Docker supports volume and network driver plugins. In the future it @@ -27,12 +36,13 @@ The following plugins exist: databases and other stateful containers and move them around across a cluster of machines. -* The [Weave plugin](https://github.com/weaveworks/docker-plugin) is a network - driver plugin which provides a virtual, multi-host network for containers. +* The [GlusterFS plugin](https://github.com/calavera/docker-volume-glusterfs) is + another volume plugin that provides multi-host volumes management for Docker + using GlusterFS. -* The [Calico plugin](https://github.com/metaswitch/calico-docker) is a network - driver plugin which provides a multi-host network for containers with routes - distributed by BGP. +* The [Keywhiz plugin](https://github.com/calavera/docker-volume-keywhiz) is + a plugin that provides credentials and secret management using Keywhiz as + a central repository. ## Troubleshooting a plugin @@ -42,11 +52,4 @@ 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](/experimental/plugin_api.md). - -# Related GitHub PRs and issues - -- [#13222](https://github.com/docker/docker/pull/13222) Plugins plumbing - -Send us feedback and comments on [#13419](https://github.com/docker/docker/issues/13419), -or on the usual Google Groups (docker-user, docker-dev) and IRC channels. +under the hood, see the [docker plugins reference](plugin_api.md). diff --git a/experimental/plugins_volume.md b/docs/extend/plugins_volume.md similarity index 65% rename from experimental/plugins_volume.md rename to docs/extend/plugins_volume.md index ebc5491a8c..e9dc1ebaa2 100644 --- a/experimental/plugins_volume.md +++ b/docs/extend/plugins_volume.md @@ -1,34 +1,38 @@ -# Experimental: Docker volume plugins + + +# Write a volume plugin Docker volume plugins enable Docker deployments to be integrated with external storage systems, such as Amazon EBS, and enable data volumes to persist beyond -the lifetime of a single Docker host. See the [plugin documentation](/experimental/plugins.md) +the lifetime of a single Docker host. See the [plugin documentation](plugins.md) for more information. -This is an experimental feature. For information on installing and using experimental features, see [the experimental feature overview](README.md). - # Command-line changes -This experimental feature introduces two changes to the `docker run` command: +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: -- The `--volume-driver` flag is introduced. -- The `-v` syntax is changed to accept a volume name a first component. + $ docker run -ti -v volumename:/data --volume-driver=flocker busybox sh -Example: +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 `/`. - $ docker run -ti -v volumename:/data --volume-driver=flocker busybox sh +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 volume name in conjunction with a volume driver, volume plugins -such as [Flocker](https://clusterhq.com/docker-plugin/), once installed, can be -used to manage volumes external to a single host, such as those on EBS. In this -example, "volumename" is passed through to the volume plugin as a user-given -name for the volume which allows the plugin to associate it 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. -The `volumename` must not begin with a `/`. -# API changes +# 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 @@ -152,9 +156,3 @@ this point. Respond with a string error if an error occurred. -# Related GitHub PRs and issues - -- [#13161](https://github.com/docker/docker/pull/13161) Volume refactor and external volume plugins - -Send us feedback and comments on [#13420](https://github.com/docker/docker/issues/13420), -or on the usual Google Groups (docker-user, docker-dev) and IRC channels. diff --git a/experimental/plugins_network.md b/experimental/plugins_network.md index 755537ef80..0902bee475 100644 --- a/experimental/plugins_network.md +++ b/experimental/plugins_network.md @@ -18,7 +18,7 @@ commands. For example, docker network create -d weave mynet -Some network driver plugins are listed in [plugins.md](plugins.md) +Some network driver plugins are listed in [plugins.md](/docs/extend/plugins.md) The network thus created is owned by the plugin, so subsequent commands referring to that network will also be run through the plugin.