From f23ada12c49e1869b8b18c942e094edfdef71f9d Mon Sep 17 00:00:00 2001 From: David Calavera Date: Fri, 22 May 2015 16:57:05 -0700 Subject: [PATCH] Move Documentation changes out or this PR. The will come in a follow up PR inside the experimental section. Signed-off-by: David Calavera Upstream-commit: ab8a5bcf04243577516207257c7fe5ec8257a9f4 Component: engine --- components/engine/docs/mkdocs.yml | 2 - .../docs/sources/reference/api/README.md | 1 - .../reference/api/docker_remote_api.md | 7 - .../reference/api/docker_remote_api_v1.19.md | 10 +- .../docs/sources/reference/api/plugin_api.md | 223 ------------------ .../docs/sources/reference/commandline/cli.md | 21 +- .../docs/sources/userguide/dockervolumes.md | 8 - .../engine/docs/sources/userguide/index.md | 6 - .../engine/docs/sources/userguide/plugins.md | 51 ---- 9 files changed, 4 insertions(+), 325 deletions(-) delete mode 100644 components/engine/docs/sources/reference/api/plugin_api.md delete mode 100644 components/engine/docs/sources/userguide/plugins.md diff --git a/components/engine/docs/mkdocs.yml b/components/engine/docs/mkdocs.yml index d357983005..b501c9c398 100644 --- a/components/engine/docs/mkdocs.yml +++ b/components/engine/docs/mkdocs.yml @@ -73,7 +73,6 @@ pages: - ['machine/index.md', 'User Guide', 'Docker Machine' ] - ['swarm/index.md', 'User Guide', 'Docker Swarm' ] - ['kitematic/userguide.md', 'User Guide', 'Kitematic'] -- ['userguide/plugins.md', 'User Guide', 'Docker Plugins'] # Docker Hub docs: - ['docker-hub/index.md', 'Docker Hub', 'Docker Hub' ] @@ -186,7 +185,6 @@ pages: - ['reference/api/docker_remote_api_v1.0.md', '**HIDDEN**'] - ['reference/api/remote_api_client_libraries.md', 'Reference', 'Docker Remote API client libraries'] - ['reference/api/docker_io_accounts_api.md', 'Reference', 'Docker Hub accounts API'] -- ['reference/api/plugin_api.md', 'Reference', 'Docker Plugin API'] - ['kitematic/faq.md', 'Reference', 'Kitematic: FAQ'] - ['kitematic/known-issues.md', 'Reference', 'Kitematic: Known issues'] diff --git a/components/engine/docs/sources/reference/api/README.md b/components/engine/docs/sources/reference/api/README.md index 4f72fbfe33..ec1cbcb2c3 100644 --- a/components/engine/docs/sources/reference/api/README.md +++ b/components/engine/docs/sources/reference/api/README.md @@ -7,4 +7,3 @@ This directory holds the authoritative specifications of APIs defined and implem index for images to download * The docker.io OAuth and accounts API which 3rd party services can use to access account information - * The plugin API for Docker Plugins diff --git a/components/engine/docs/sources/reference/api/docker_remote_api.md b/components/engine/docs/sources/reference/api/docker_remote_api.md index 595eeb325d..4c77cab8cf 100644 --- a/components/engine/docs/sources/reference/api/docker_remote_api.md +++ b/components/engine/docs/sources/reference/api/docker_remote_api.md @@ -73,13 +73,6 @@ are now returned as boolean instead of as an int. In addition, the end point now returns the new boolean fields `CpuCfsPeriod`, `CpuCfsQuota`, and `OomKillDisable`. -**New in the Experimental channel!** - -You can now specify a volume plugin in `/v1.19/containers/create`, for example -`"VolumeDriver": "flocker", "HostConfig": {"Binds": ["vol-1:/data"]}` where `flocker` is the name -of the plugin, `vol-1` is the user-facing name of the volume (passed to the -volume plugin) and `/data` is the mountpoint inside the container. - ## v1.18 ### Full documentation diff --git a/components/engine/docs/sources/reference/api/docker_remote_api_v1.19.md b/components/engine/docs/sources/reference/api/docker_remote_api_v1.19.md index 2ea4b42998..dde8ee79a1 100644 --- a/components/engine/docs/sources/reference/api/docker_remote_api_v1.19.md +++ b/components/engine/docs/sources/reference/api/docker_remote_api_v1.19.md @@ -15,8 +15,6 @@ page_keywords: API, Docker, rcli, REST, documentation `STDIN` and `STDERR`. - When the client API version is newer than the daemon's an HTTP `400 Bad Request` error message is returned. - - Options marked as *Experimental* are only available using Docker - from the Experimental channel. # 2. Endpoints @@ -144,7 +142,6 @@ Create a container "ExposedPorts": { "22/tcp": {} }, - VolumeDriver: "local", "HostConfig": { "Binds": ["/tmp:/tmp"], "Links": ["redis3:redis"], @@ -225,15 +222,12 @@ Json Parameters: container - **ExposedPorts** - An object mapping ports to an empty object in the form of: `"ExposedPorts": { "/: {}" }` -- **VolumeDriver** - *(Experimental)* A string value containing the volume driver to use, `local` by default. - **HostConfig** - **Binds** – A list of volume bindings for this container. Each volume binding is a string of the form `container_path` (to create a new volume for the container), `host_path:container_path` (to bind-mount - a host path into the container), `host_path:container_path:ro` - (to make the bind-mount read-only inside the container), or - `volume_name:container_path` (to provision a volume named `volume_name` - from a [volume plugin](/userguide/plugins)). + a host path into the container), or `host_path:container_path:ro` + (to make the bind-mount read-only inside the container). - **Links** - A list of links for the container. Each link entry should be in the form of `container_name:alias`. - **LxcConf** - LXC specific configurations. These configurations will only diff --git a/components/engine/docs/sources/reference/api/plugin_api.md b/components/engine/docs/sources/reference/api/plugin_api.md deleted file mode 100644 index 770f606b4c..0000000000 --- a/components/engine/docs/sources/reference/api/plugin_api.md +++ /dev/null @@ -1,223 +0,0 @@ -page_title: Plugin API documentation -page_description: Documentation for writing a Docker plugin. -page_keywords: docker, plugins, api, extensions - -# 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](/userguide/plugins). - -## What plugins are - -A plugin is a process running on the same docker host as the docker daemon, -which registers itself by placing a file in `/usr/share/docker/plugins` (the -"plugin directory"). - -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 two 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`. - -The name of the file (excluding the extension) determines the plugin name. - -For example, the `flocker` plugin might create a UNIX socket at -`/usr/share/docker/plugins/flocker.sock`. - -Plugins must be run locally on the same machine as the Docker daemon. UNIX -domain sockets are strongly encouraged for security reasons. - -## 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. - -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 -(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. - -## 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. - -## Volume API - -If a plugin registers itself as a `VolumeDriver` (see above) 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. - -### /VolumeDriver.Create - -**Request**: -``` -{ - "Name": "volume_name" -} -``` - -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). - -**Response**: -``` -{ - "Err": null -} -``` - -Respond with a string error if an error occurred. - -### /VolumeDriver.Remove - -**Request**: -``` -{ - "Name": "volume_name" -} -``` - -Create a volume, given a user specified volume name. - -**Response**: -``` -{ - "Err": null -} -``` - -Respond with a string error if an error occurred. - -### /VolumeDriver.Mount - -**Request**: -``` -{ - "Name": "volume_name" -} -``` - -Docker requires the plugin to provide a volume, given a user specified volume -name. This is called once per container start. - -**Response**: -``` -{ - "Mountpoint": "/path/to/directory/on/host", - "Err": null -} -``` - -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**: -``` -{ - "Name": "volume_name" -} -``` - -Docker needs reminding of the path to the volume on the host. - -**Response**: -``` -{ - "Mountpoint": "/path/to/directory/on/host", - "Err": null -} -``` - -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.Unmount - -**Request**: -``` -{ - "Name": "volume_name" -} -``` - -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. - -**Response**: -``` -{ - "Err": null -} -``` - -Respond with a string error if an error occurred. - -## 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. diff --git a/components/engine/docs/sources/reference/commandline/cli.md b/components/engine/docs/sources/reference/commandline/cli.md index b5171b1b34..a4a44fbb54 100644 --- a/components/engine/docs/sources/reference/commandline/cli.md +++ b/components/engine/docs/sources/reference/commandline/cli.md @@ -1000,8 +1000,7 @@ Creates a new container. --security-opt=[] Security options -t, --tty=false Allocate a pseudo-TTY -u, --user="" Username or UID - -v, --volume=[] Bind mount a volume, or specify name for volume plugin - --volume-driver= Optional volume driver (plugin name) for the container (Experimental) + -v, --volume=[] Bind mount a volume --volumes-from=[] Mount volumes from the specified container(s) -w, --workdir="" Working directory inside the container @@ -1971,8 +1970,7 @@ To remove an image using its digest: --sig-proxy=true Proxy received signals to the process -t, --tty=false Allocate a pseudo-TTY -u, --user="" Username or UID (format: [:]) - -v, --volume=[] Bind mount a volume, or specify name for volume plugin - --volume-driver= Optional volume driver (plugin name) for the container (Experimental) + -v, --volume=[] Bind mount a volume --volumes-from=[] Mount volumes from the specified container(s) -w, --workdir="" Working directory inside the container @@ -2273,21 +2271,6 @@ application change: `--rm` option means that when the container exits, the container's layer is removed. - -*Experimental*: - - $ docker run -ti -v volumename:/data --volume-driver=flocker busybox sh - -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. - -The `volumename` must not begin with a `/`. - #### Restart policies Use Docker's `--restart` to specify a container's *restart policy*. A restart diff --git a/components/engine/docs/sources/userguide/dockervolumes.md b/components/engine/docs/sources/userguide/dockervolumes.md index 567d174716..c7126d7c33 100644 --- a/components/engine/docs/sources/userguide/dockervolumes.md +++ b/components/engine/docs/sources/userguide/dockervolumes.md @@ -210,14 +210,6 @@ Then un-tar the backup file in the new container's data volume. You can use the techniques above to automate backup, migration and restore testing using your preferred tools. -## (Experimental) Integrating Docker with external storage systems - -Docker volume plugins such as [Flocker](https://clusterhq.com/docker-plugin/) -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 section of the user -guide](/userguide/plugins) for more information. - # Next steps Now we've learned a bit more about how to use Docker we're going to see how to diff --git a/components/engine/docs/sources/userguide/index.md b/components/engine/docs/sources/userguide/index.md index 8395757919..9cc1c6db30 100644 --- a/components/engine/docs/sources/userguide/index.md +++ b/components/engine/docs/sources/userguide/index.md @@ -105,12 +105,6 @@ works with Docker can now transparently scale up to multiple hosts. Go to [Docker Swarm user guide](/swarm/). -## (Experimental) Docker Plugins - -Docker plugins allow you to extend the capabilities of the Docker Engine. - -Go to [Docker Plugins](/userguide/plugins). - ## Getting help * [Docker homepage](http://www.docker.com/) diff --git a/components/engine/docs/sources/userguide/plugins.md b/components/engine/docs/sources/userguide/plugins.md deleted file mode 100644 index 5fc7864010..0000000000 --- a/components/engine/docs/sources/userguide/plugins.md +++ /dev/null @@ -1,51 +0,0 @@ -page_title: Docker Plugins -page_description: Learn what Docker Plugins are and how to use them. -page_keywords: plugins, extensions, extensibility - -# Understanding Docker Plugins - -You can extend the capabilities of the Docker Engine by loading third-party -plugins. - -## Types of plugins - -Plugins extend Docker's functionality. They come in specific types. For -example, a **volume plugin** might enable Docker volumes to persist across -multiple Docker hosts. - -Currently Docker supports **volume 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 following plugins exist: - -* The [Flocker plugin](https://clusterhq.com/docker-plugin/) is a volume plugin - which 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. - -## Using a plugin - -Depending on the plugin type, there are additional arguments to `docker` CLI -commands. - -* For example `docker run` has a [`--volume-driver` argument]( - /reference/commandline/cli/#run). - -You can also use plugins via the [Docker Remote API]( -/reference/api/docker_remote_api/). - -## 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](/reference/api/plugin_api).