mirror of
https://github.com/moby/moby.git
synced 2022-11-09 12:21:53 -05:00
Merge pull request #13989 from squaremo/netplugin_docs
Mention network driver plugins and point to protocol docs
This commit is contained in:
Sebastiaan van Stijn
commit
f0e90606cd
5 changed files with 175 additions and 122 deletions
|
|
@ -62,7 +62,8 @@ After downloading the appropriate binary, you can follow the instructions
|
|||
## Current experimental features
|
||||
|
||||
* [Support for Docker plugins](plugins.md)
|
||||
* [Volume plugins](plugins_volume.md)
|
||||
* [Volume plugins](plugins_volume.md)
|
||||
* [Network plugins](plugins_network.md)
|
||||
* [Native Multi-host networking](networking.md)
|
||||
* [Compose, Swarm and networking integration](compose_swarm_networking.md)
|
||||
|
||||
|
|
|
|||
|
|
@ -112,124 +112,6 @@ Plugins are activated via the following "handshake" API call.
|
|||
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
|
||||
|
|
|
|||
|
|
@ -11,8 +11,8 @@ Plugins extend Docker's functionality. They come in specific types. For
|
|||
example, a [volume plugin](/experimental/plugins_volume.md) might enable Docker
|
||||
volumes to persist across multiple Docker hosts.
|
||||
|
||||
Currently Docker supports volume plugins. In the future it will support
|
||||
additional plugin types.
|
||||
Currently Docker supports volume and network driver plugins. In the future it
|
||||
will support additional plugin types.
|
||||
|
||||
## Installing a plugin
|
||||
|
||||
|
|
@ -23,10 +23,17 @@ Follow the instructions in the plugin's documentation.
|
|||
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
|
||||
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.
|
||||
|
||||
* The [Weave plugin](https://github.com/weaveworks/docker-plugin) is a network
|
||||
driver plugin which provides a virtual, multi-host network for containers.
|
||||
|
||||
* 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.
|
||||
|
||||
## Troubleshooting a plugin
|
||||
|
||||
If you are having problems with Docker after loading a plugin, ask the authors
|
||||
|
|
|
|||
45
experimental/plugins_network.md
Normal file
45
experimental/plugins_network.md
Normal file
|
|
@ -0,0 +1,45 @@
|
|||
# Experimental: Docker network driver plugins
|
||||
|
||||
Docker supports network driver plugins via
|
||||
[LibNetwork](https://github.com/docker/libnetwork). Network driver plugins are
|
||||
implemented as "remote drivers" for LibNetwork, which shares plugin
|
||||
infrastructure with Docker. In effect this means that network driver plugins
|
||||
are activated in the same way as other plugins, and use the same kind of
|
||||
protocol.
|
||||
|
||||
## Using network driver plugins
|
||||
|
||||
The means of installing and running a network driver plugin will depend on the
|
||||
particular plugin.
|
||||
|
||||
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 -d weave mynet
|
||||
|
||||
Some network driver plugins are listed in [plugins.md](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.
|
||||
|
||||
## Network driver plugin protocol
|
||||
|
||||
The network driver protocol, additional 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 GitHub PRs and issues
|
||||
|
||||
Please record your feedback in the following issue, on the usual
|
||||
Google Groups, or the IRC channel #docker-network.
|
||||
|
||||
- [#14083](https://github.com/docker/docker/issues/14083) Feedback on
|
||||
experimental networking features
|
||||
|
||||
Other pertinent issues:
|
||||
|
||||
- [#13977](https://github.com/docker/docker/issues/13977) UI for using networks
|
||||
- [#14023](https://github.com/docker/docker/pull/14023) --default-network option
|
||||
- [#14051](https://github.com/docker/docker/pull/14051) --publish-service option
|
||||
- [#13441](https://github.com/docker/docker/pull/13441) (Deprecated) Networks API & UI
|
||||
|
|
@ -34,6 +34,124 @@ 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.
|
||||
|
||||
### /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.
|
||||
|
||||
# Related GitHub PRs and issues
|
||||
|
||||
- [#13161](https://github.com/docker/docker/pull/13161) Volume refactor and external volume plugins
|
||||
|
|
|
|||
Loading…
Reference in a new issue