diff --git a/plugin/README.md b/plugin/README.md index 4af2efc7..1e246c1c 100644 --- a/plugin/README.md +++ b/plugin/README.md @@ -3,63 +3,7 @@ A [plugin](http://docs.docker.com/engine/extend/plugin_api/) to integrate [weave Net](http://weave.works/net/) with Docker. -## Setup: +The plugin runs automatically when you `weave launch`, provided your +Docker daemon is version 1.9 or newer. -Before you can use this plugin, you must [install weave](https://github.com/weaveworks/weave#installation) and [configure docker with a "cluster store"](https://docs.docker.com/engine/userguide/networking/get-started-overlay/#step-1-set-up-a-key-value-store). - - $ weave launch - $ weave launch-plugin - $ docker network create --driver=weave weave - -When you start subsequent weave peers you have to tell them about other peers, e.g. - - $ weave launch - $ weave launch-plugin - -## Starting a container: - - $ docker run --net=weave -ti ubuntu - -## Plugin command-line arguments - - * `--socket=`, which is the socket on which to listen for the - [plugin protocol](http://docs.docker.com/engine/extend/plugin_api/). - This defaults to what Docker expects, that is - `"/run/docker/plugins/weave.sock"`, but you may wish to - change it, for instance if you're running more than one instance of - the driver for some reason. - - * `--log-level=debug|info|warning|error`, which tells the plugin - how much information to emit for debugging. - -## Points to note - -Network plugins require Docker version 1.9 or later. - -### Docker needs a "cluster store" - -Weave operates as a "globally scoped" libnetwork driver, which means -libnetwork will assume all networks and endpoints are commonly known -to all hosts. It does this by using a shared database which you must -provide. - -As a consequence, you need to supply Docker with the address of a "cluster -store" when you start it; for example, an etcd installation. - -There's no specific documentation for using a cluster store, but the -first part of [this guide](https://github.com/docker/docker/blob/master/docs/userguide/networking/get-started-overlay.md) may help. - -### WeaveDNS not supported - -Weave's built-in service discovery mechanism is not currently -supported by the plugin. However, Docker provides a rudimentary -discovery mechanism by writing all user-provided container names and -hostnames into every container's `/etc/hosts`. - -### Restarting - -We start the plugin with a restart policy of 'always', because -Docker attempts to recreate networks on startup which means the plugin -container has to be started. If it isn't started automatically by Docker -with a restart policy, it's not possible to start it manually because -Docker is blocked. +More detail [here](http://docs.weave.works/weave/latest_release/plugin.html). diff --git a/site/features.md b/site/features.md index e7e949a1..f69393b7 100644 --- a/site/features.md +++ b/site/features.md @@ -93,21 +93,12 @@ re-attached to the weave network by the weave Docker API proxy. ### Docker network plugin -Alternatively, you can use weave as a Docker plugin. First you must -configure the Docker daemon to use a cluster store as documented -[here](https://docs.docker.com/engine/userguide/networking/dockernetworks/#an-overlay-network); -you can then launch weave and create a network: - - $ weave launch - $ weave launch-plugin - $ docker network create --driver=weave weave - -and then start a container: +Alternatively, you can use weave as a Docker plugin. A Docker network +named `weave` is created by `weave launch`, which you can use like this: $ docker run --net=weave -ti ubuntu -For more details see the -[plugin README](https://github.com/weaveworks/docker-plugin). +For more details see the [plugin documentation](plugin.html). ### Address allocation diff --git a/site/plugin.md b/site/plugin.md new file mode 100644 index 00000000..eb4489b1 --- /dev/null +++ b/site/plugin.md @@ -0,0 +1,84 @@ +--- +title: Using Weave Net via Docker Networking +layout: default +--- + +New in Docker version 1.9 is a plugin mechanism to add different +network providers. + +To install, download the `weave` script as per the [readme][]. + +The Weave Net plugin runs automatically when you `weave launch`. You +must still tell the weave peers to connect to one another, either via +`weave launch` or `weave connect`. + +## Starting a container: + + $ docker run --net=weave -ti ubuntu + +## Using WeaveDNS for Service Discovery: + +You need to pass the additional arguments `--dns` and `-dns-search`, +for which we provide a helper in the weave script: + + $ docker run --net=weave -h foo.weave.local $(weave dns-args) -tdi ubuntu + $ docker run --net=weave -h bar.weave.local $(weave dns-args) -ti ubuntu + # ping foo + +For more details see the [Weave Service Discovery documentation][service-discovery]. + +## Under the hood + +The Weave Net plugin actually provides *two* network drivers to Docker +- one named `weavemesh` that can operate without a [cluster +store](#cluster-store) (like Docker's overlay driver) and one named +`weave` that can only work with one. + +### `weavemesh` driver + +* Weave handles all co-ordination between hosts (referred to by Docker as a "local scope" driver) +* Supports only a single network (we create one named `weave` for you automatically) +* Uses Weave's partition tolerant IPAM + +### `weave` driver + +* This runs in what Docker call "global scope"; requires a cluster store +* Supports multiple networks (these must be created with `docker network create --driver weave ...`) +* Used with Docker's cluster store based IPAM + +There's no specific documentation from Docker on using a cluster +store, but the first part of [Getting Started with Docker Multi-host Networking][docker-net] +should point the way. + +Note that in the case of multiple docker networks, all containers are +on the same virtual network but Docker allocates their addresses on +different subnets so they cannot talk to each other directly. + +## Plugin command-line arguments + +If you want to give some arguments to the plugin independently, don't +use `weave launch`; instead run: + + $ weave launch-router [other peers] + $ weave launch-plugin [plugin arguments] + +The plugin command-line arguments are: + + * `--log-level=debug|info|warning|error`, which tells the plugin + how much information to emit for debugging. + * `--mesh-network-name=`: set it to blank to disable creation + of a default network, or a name of your own choice. + +## Restarting + +We start the plugin with a restart policy, because Docker attempts to +recreate networks on startup. If it isn't started automatically by +Docker with a restart policy, it's not possible to start it manually +because Docker is blocked. + +Specifically, we use the policy `on-failure:3`, so Docker will give up +after three attempts if something just isn't working. + +[readme]: https://github.com/weaveworks/weave/blob/master/README.md#installation +[service-discovery]: weavedns.html +[docker-net]: https://github.com/docker/docker/blob/master/docs/userguide/networking/get-started-overlay.md diff --git a/site/troubleshooting.md b/site/troubleshooting.md index 22b81758..154ce539 100644 --- a/site/troubleshooting.md +++ b/site/troubleshooting.md @@ -93,6 +93,9 @@ $ weave status Service: proxy Address: tcp://127.0.0.1:12375 + Service: plugin + DriverName: weave + ```` The terms used here are explained further at diff --git a/weave b/weave index ce795ca9..31316d39 100755 --- a/weave +++ b/weave @@ -57,6 +57,7 @@ weave launch-proxy [-H ] [--with-dns | --without-dns] weave launch-plugin weave env [--restore] weave config +weave dns-args weave connect [--replace] [ ...] weave forget ... weave status [targets | connections | peers | dns]