mirror of
https://github.com/moby/moby.git
synced 2022-11-09 12:21:53 -05:00
Move Documentation changes out or this PR.
The will come in a follow up PR inside the experimental section. Signed-off-by: David Calavera <david.calavera@gmail.com>
This commit is contained in:
David Calavera
parent
d592778f4a
commit
ab8a5bcf04
9 changed files with 4 additions and 325 deletions
|
|
@ -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']
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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": { "<port>/<tcp|udp>: {}" }`
|
||||
- **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
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
@ -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: <name|uid>[:<group|gid>])
|
||||
-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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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/)
|
||||
|
|
|
|||
|
|
@ -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).
|
||||
Loading…
Add table
Reference in a new issue