From 646ac3c74d7d023eae0e2fcdc3ed72f02dbb8c37 Mon Sep 17 00:00:00 2001 From: Martynas Pumputis Date: Fri, 12 May 2017 11:56:00 +0300 Subject: [PATCH 1/4] 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. From a1ddb336c192d7cb4a0e12902c503dc70e5e8f82 Mon Sep 17 00:00:00 2001 From: Bryan Boreham Date: Mon, 22 May 2017 12:15:40 +0000 Subject: [PATCH 2/4] Make it clear that only one of the two plugins works without a cluster store --- site/features.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/site/features.md b/site/features.md index a135b945..03187e3a 100644 --- a/site/features.md +++ b/site/features.md @@ -83,11 +83,10 @@ named `weave` is created by `weave launch`, which is used as follows: Using the Weave plugin enables you to take advantage of [Docker's network functionality](https://docs.docker.com/engine/extend/plugins_network/). -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. - -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. +There are two plugin implementations for Weave Net: the +["Legacy"](/site/plugin.md) plugin which doesn't require an external +cluster store, and the ["V2"](/site/plugin-v2.md) plugin which +supports Docker swarm mode. ### Weave Network CNI Plugin From 3ae505d6c6dc8281cbcf3549a3599919ca93cc74 Mon Sep 17 00:00:00 2001 From: Bryan Boreham Date: Mon, 22 May 2017 12:18:54 +0000 Subject: [PATCH 3/4] More accessible reference for v2 plugins --- site/plugin-v2.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/site/plugin-v2.md b/site/plugin-v2.md index 8722dd52..33688c38 100644 --- a/site/plugin-v2.md +++ b/site/plugin-v2.md @@ -8,7 +8,7 @@ search_type: Documentation * [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). +Docker Engine version 1.12 introduced [a new plugin system (V2)](https://docs.docker.com/engine/extend/). 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 From d021e61dfaab1c625a3f93ade08ddc47b493e697 Mon Sep 17 00:00:00 2001 From: Bryan Boreham Date: Mon, 22 May 2017 12:19:46 +0000 Subject: [PATCH 4/4] Update troubleshooting page to match code --- site/troubleshooting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/site/troubleshooting.md b/site/troubleshooting.md index 3e84a25f..d849c272 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 (v1) + Service: plugin (legacy) DriverName: weave ```