reweave/weave
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update plugin README and documentation

Browse Source
This commit is contained in:
Bryan Boreham committed 2015-12-15 16:52:37 +00:00
1 parent 791fc9d6b1
commit 41482aff01
5 files changed
+94 -71
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

plugin/README.md
+3 -59
View File
@@ -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 <host1> <host2>
$ weave launch-plugin
## Starting a container:
$ docker run --net=weave -ti ubuntu
## Plugin command-line arguments
* `--socket=<path>`, 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).
site/features.md
+3 -12
View File
@@ -93,21 +93,12 @@ re-attached to the weave network by the weave Docker API proxy.
### <a name="plugin"></a>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).
### <a name="addressing"></a>Address allocation
site/plugin.md
+84
View File
@@ -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=<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
site/troubleshooting.md
+3
View File
@@ -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
weave
+1
View File
@@ -57,6 +57,7 @@ weave launch-proxy [-H <endpoint>] [--with-dns | --without-dns]
weave launch-plugin
weave env [--restore]
weave config
weave dns-args
weave connect [--replace] [<peer> ...]
weave forget <peer> ...
weave status [targets | connections | peers | dns]