From 646ac3c74d7d023eae0e2fcdc3ed72f02dbb8c37 Mon Sep 17 00:00:00 2001 From: Martynas Pumputis Date: Fri, 12 May 2017 11:56:00 +0300 Subject: [PATCH] Add plugin-v2 (net-plugin) docs --- site/building.md | 4 +- site/features.md | 4 +- site/ipam.md | 2 +- site/plugin-v2.md | 77 ++++++++++++++++++++++++++++++ site/plugin.md | 27 ++--------- site/plugin/plugin-how-it-works.md | 19 ++++++-- site/troubleshooting.md | 2 +- site/using-weave.md | 3 +- site/using-weave/weave-cloud.md | 3 +- site/weave-docker-api.md | 3 +- 10 files changed, 110 insertions(+), 34 deletions(-) create mode 100644 site/plugin-v2.md diff --git a/site/building.md b/site/building.md index 8bd479c8..50aac708 100644 --- a/site/building.md +++ b/site/building.md @@ -42,8 +42,8 @@ On a fresh repository, the Makefile will do the following: - assemble the build container - download specific versions of all the dependencies - build the weave components in the build container -- package them into three Docker images (`weaveworks/weave`, -`weaveworks/weaveexec`, and `weaveworks/plugin`) +- package them into two Docker images (`weaveworks/weave`, +`weaveworks/weaveexec`) - Exported these images as `weave.tar.gz` The first two steps may take a while - don't worry, they are diff --git a/site/features.md b/site/features.md index d69257a7..a135b945 100644 --- a/site/features.md +++ b/site/features.md @@ -86,8 +86,8 @@ Using the Weave plugin enables you to take advantage of [Docker's network functi Also, Weave’s Docker Network plugin doesn't require an external cluster store and you can start and stop containers even when there are network connectivity problems. -See [Integrating Docker via the Network Plugin](/site/plugin.md) for more details. - +There are two plugin implementations for Weave Net. See [Integrating Docker via the Network Plugin (Legacy)](/site/plugin.md) +and [Integrating Docker via the Network Plugin (V2)](/site/plugin-v2.md) for more details. ### Weave Network CNI Plugin diff --git a/site/ipam.md b/site/ipam.md index 9a9df29a..ca014269 100644 --- a/site/ipam.md +++ b/site/ipam.md @@ -203,4 +203,4 @@ named `weavedb` is used to store this data. **See Also** * [Automatic Allocation Across Multiple Subnets](/site/ipam/allocation-multi-ipam.md) - * [Integrating Docker via the Network Plugin](/site/plugin.md) + * [Integrating Docker via the Network Plugin (Legacy)](/site/plugin.md) diff --git a/site/plugin-v2.md b/site/plugin-v2.md new file mode 100644 index 00000000..8722dd52 --- /dev/null +++ b/site/plugin-v2.md @@ -0,0 +1,77 @@ +--- +title: Integrating Docker via the Network Plugin (V2) +menu_order: 65 +search_type: Documentation +--- + + * [Installation](#installation) + * [Configuring the Plugin](#configuring) + * [Running Services or Containers Using the Plugin](#usage) + +Docker Engine version 1.12 introduced [a new plugin system (V2)](https://github.com/moby/moby/commit/f37117045c5398fd3dca8016ea8ca0cb47e7312b). +This document describes how to use [the Network Plugin V2 of Weave Net](https://store.docker.com/plugins/weave-net-plugin). + +Before using the plugin, please keep in mind the plugin works only in Swarm +mode and requires Docker version 1.13 or later. + +### Installation + +To install the plugin run the following command on _each_ host already +participating in a Swarm cluster, i.e. on all master and worker nodes: + + $ docker plugin install store/weaveworks/net-plugin:latest_release + +Docker will pull the plugin from Docker Store, and it will ask to grant +privileges before installing the plugin. Afterwards, it will start `weaver` +process which will try to connect to Swarm masters running Weave Net. + +### Configuring the Plugin + +There are several configuration parameters which can be set with: + + $ docker plugin set store/weaveworks/net-plugin:latest_release PARAM=VALUE + +The parameters include: + +* `WEAVE_PASSWORD` - if non empty, it will instruct Weave Net to encrypt + traffic - see [here](/site/using-weave/security-untrusted-networks.md) for + more details. +* `WEAVE_MULTICAST` - set to 1 on each host running the plugin to enable + multicast traffic on any Weave Net network. +* `WEAVE_MTU` - Weave Net defaults to 1376 bytes, but you can set a + smaller size if your underlying network has a tighter limit, or set + a larger size for better performance if your network supports jumbo + frames - see [here](/site/using-weave/fastdp.md#mtu) for more + details. + +Before setting any parameter, the plugin has to be disabled with: + + $ docker plugin disable store/weaveworks/net-plugin:latest_release + +To re-enable the plugin run the following command: + + $ docker plugin enable store/weaveworks/net-plugin:latest_release + +### Running Services or Containers Using the Plugin + +After you have launched the plugin, you can create a network for Docker Swarm +services by running the following command on any Docker Swarm master node: + + $ docker create network --driver=store/weaveworks/net-plugin:latest_release mynetwork + +Or you can create a network for any Docker container with: + + $ docker create network --driver=store/weaveworks/net-plugin:latest_release --attachable mynetwork + +To start a service attached to the network run, for example: + + $ docker service create --network=mynetwork ... + +Or to start a container: + + $ docker run --network=mynetwork ... + +**See Also** + + * [Integrating Docker via the Network Plugin (Legacy)](/site/plugin.md) + * [How the Weave Network Plugins Work](/site/plugin/plugin-how-it-works.md) diff --git a/site/plugin.md b/site/plugin.md index 6225f734..fc359807 100644 --- a/site/plugin.md +++ b/site/plugin.md @@ -1,5 +1,5 @@ --- -title: Integrating Docker via the Network Plugin +title: Integrating Docker via the Network Plugin (Legacy) menu_order: 60 search_type: Documentation --- @@ -62,26 +62,9 @@ different sets of containers to each network. However, coordinating this between hosts requires that you run Docker in ["swarm mode"](https://docs.docker.com/engine/swarm/swarm-mode/) or configure a ["key-value store"](https://docs.docker.com/engine/userguide/networking/get-started-overlay/#/set-up-a-key-value-store). -Docker swarm mode requires Docker version 1.13 or later to work with -plugins such as Weave Net. - -To create a new network for services in swarm mode, run: - - $ docker network create --driver=weaveworks/net-plugin:2.0.0 mynetwork - -then use it to create a service: - - $ docker service create --network=mynetwork --name myservice ... - - -To create a new network to attach containers in swarm mode, run: - - $ docker network create --driver=weave --attachable mynetwork - -then use it to connect a container: - - $ docker run --net=mynetwork ... - +To operate in swarm mode, you are required to use the plugin v2 of Weave Net. +See [Integrating Docker via the Network Plugin (V2)](/site/plugin-v2.md) for +more details. If your Docker installation has a key-value store, create a network based on Weave Net as follows: @@ -113,4 +96,4 @@ If you are using `systemd` with Docker 1.9, it is advised that you modify the Do **See Also** - * [How the Weave Network Plugin Works](/site/plugin/plugin-how-it-works.md) + * [How the Weave Network Plugins Work](/site/plugin/plugin-how-it-works.md) diff --git a/site/plugin/plugin-how-it-works.md b/site/plugin/plugin-how-it-works.md index effc900b..b3dc6166 100644 --- a/site/plugin/plugin-how-it-works.md +++ b/site/plugin/plugin-how-it-works.md @@ -1,11 +1,15 @@ --- -title: How the Weave Net Docker Network Plugin Works +title: How the Weave Net Docker Network Plugins Work menu_order: 20 search_type: Documentation --- -The Weave Net plugin actually provides *two* network drivers to Docker - one named `weavemesh` that can operate without a cluster store and another one named `weave` that can only work with one (like Docker's overlay driver). +The Weave Net legacy plugin actually provides *two* network drivers to Docker - +one named `weavemesh` that can operate without a cluster store and another one +named `weave` that can only work with one (like Docker's overlay driver), while +the V2 plugin provides *one* - `store/weaveworks/net-plugin:latest_release` +operating only in swarm mode. ### `weavemesh` driver @@ -37,7 +41,16 @@ The plugin accepts the following options via `docker network create ... --opt`: network created when the plugin is first launched has the multicast option turned on, but for any networks you create it defaults to off. +### `store/weaveworks/net-plugin:latest_release` driver + +* The driver runs within the plugin V2. +* Requires Docker to run in [swarm mode](https://docs.docker.com/engine/swarm/swarm-mode/). +* Supports multiple networks. +* Used with Docker's IPAM. + + **See Also** - * [Integrating Docker via the Network Plugin](/site/plugin.md) + * [Integrating Docker via the Network Plugin (Legacy)](/site/plugin.md) + * [Integrating Docker via the Network Plugin (V2)](/site/plugin-v2.md) diff --git a/site/troubleshooting.md b/site/troubleshooting.md index 0f108359..3e84a25f 100644 --- a/site/troubleshooting.md +++ b/site/troubleshooting.md @@ -74,7 +74,7 @@ $ weave status Service: proxy Address: tcp://127.0.0.1:12375 - Service: plugin + Service: plugin (v1) DriverName: weave ``` diff --git a/site/using-weave.md b/site/using-weave.md index 8c7ea87d..89a4d4c9 100644 --- a/site/using-weave.md +++ b/site/using-weave.md @@ -138,4 +138,5 @@ Weave Net supports *any* protocol, and it doesn't have to be over TCP/IP. For ex * [Installing Weave Net](/site/installing-weave.md) * [Using Weave Cloud to get started with Weave Net](/site/using-weave/weave-cloud.md) * [Using Fastdp With Weave Net](/site/using-weave/fastdp.md) - * [Using the Weave Net Docker Network Plugin](/site/plugin.md) + * [Integrating Docker via the Network Plugin (Legacy)](/site/plugin.md) + * [Integrating Docker via the Network Plugin (V2)](/site/plugin-v2.md) diff --git a/site/using-weave/weave-cloud.md b/site/using-weave/weave-cloud.md index 291a4023..785a95aa 100644 --- a/site/using-weave/weave-cloud.md +++ b/site/using-weave/weave-cloud.md @@ -124,4 +124,5 @@ connect to it. * [Installing Weave Net](/site/installing-weave.md) * [Using Weave Net](/site/using-weave.md) * [Using Fastdp With Weave Net](/site/using-weave/fastdp.md) - * [Using the Weave Net Docker Network Plugin](/site/plugin.md) + * [Integrating Docker via the Network Plugin (Legacy)](/site/plugin.md) + * [Integrating Docker via the Network Plugin (V2)](/site/plugin-v2.md) diff --git a/site/weave-docker-api.md b/site/weave-docker-api.md index b0e3318a..14e7b6ad 100644 --- a/site/weave-docker-api.md +++ b/site/weave-docker-api.md @@ -28,7 +28,8 @@ Docker containers are started with the --net flag, for example: Note that if a Docker container is started with the --net flag, then the Weave Docker API Proxy is automatically disabled and is not used to attach containers. -See [Integrating Docker via the Network Plugin](/site/plugin.md). +See [Integrating Docker via the Network Plugin (Legacy)](/site/plugin.md) and +[Integrating Docker via the Network Plugin (V2)](/site/plugin-v2.md). **3.** Containers can also be attached to the Weave network with `weave attach` commands. This method also does not use the Weave Docker API Proxy.