Add plugin-v2 (net-plugin) docs

2017-05-22 14:52:29 +01:00
1 parent d383a29e00
commit 646ac3c74d
@@ -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
@@ -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.

 ### <a name="cniplugin"></a>Weave Network CNI Plugin

@@ -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)
@@ -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.
+
+### <a name="installation"></a>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.
+
+### <a name="configuring"></a>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
+
+### <a name="usage"></a>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)
@@ -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)
@@ -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)

@@ -74,7 +74,7 @@ $ weave status
        Service: proxy
        Address: tcp://127.0.0.1:12375

-       Service: plugin
+       Service: plugin (v1)
    DriverName: weave
 ```

@@ -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)
@@ -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)
@@ -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.