Merge documentation from branch '1.0'
This commit is contained in:
Adam Harrison committed
commit
a751237164
7 files changed
+175
-263
No files matched your search
@@ -60,36 +60,30 @@ Say you have docker running on two hosts, accessible to each other as
|
||||
`$HOST1` and `$HOST2`, and want to deploy an application consisting of
|
||||
two containers, one on each host.
|
||||
|
||||
On `$HOST1` run
|
||||
First start weave on $HOST1:
|
||||
|
||||
host1$ weave launch
|
||||
host1$ weave launch-dns
|
||||
host1$ weave run --name a1 -ti ubuntu
|
||||
host1$ weave launch && weave launch-dns && weave launch-proxy
|
||||
|
||||
The first two lines start the weave router and DNS, each inside their
|
||||
own container - this needs to be done once per host. Whilst the
|
||||
required docker images are downloaded automatically, there is also a
|
||||
`weave setup` command for downloading all the images required for
|
||||
weave operation; this is a strictly optional step which is especially
|
||||
useful for automated installation of weave and ensures that any
|
||||
subsequent weave commands do not encounter delays due to image
|
||||
downloading.
|
||||
this runs the weave router, DNS and proxy, each in their own
|
||||
container. Next we configure our `DOCKER_HOST` environment variable to
|
||||
point to the proxy, so that containers launched via the docker command
|
||||
line are automatically attached to the weave network:
|
||||
|
||||
The third line runs our application container, allocating it an IP
|
||||
address on the weave network and registering it in DNS. `weave run`
|
||||
invokes `docker run -d` behind the scenes, so we could be launching
|
||||
any container this way; here we just take a stock ubuntu container and
|
||||
launch a shell in it. There's also a `weave start` command, which
|
||||
invokes `docker start` for starting existing containers.
|
||||
host1$ eval $(weave proxy-env)
|
||||
|
||||
If our application consists of more than one container on this host we
|
||||
simply launch them with a variation on third second line.
|
||||
Finally we run our application container; this happens via the proxy
|
||||
so it is automatically allocated an IP address and registered in DNS:
|
||||
|
||||
host1$ docker run --name a1 -ti ubuntu
|
||||
|
||||
That's it! If our application consists of more than one container on
|
||||
this host we simply launch them with `docker run` as appropriate.
|
||||
|
||||
Next we repeat similar steps on `$HOST2`...
|
||||
|
||||
host2$ weave launch $HOST1
|
||||
host2$ weave launch-dns
|
||||
host2$ weave run --name a2 -ti ubuntu
|
||||
host2$ weave launch $HOST1 && weave launch-dns && weave launch-proxy
|
||||
host2$ eval $(weave proxy-env)
|
||||
host2$ docker run --name a2 -ti ubuntu
|
||||
|
||||
The only difference, apart from the name of the application container,
|
||||
is that we tell our weave that it should peer with the weave on
|
||||
@@ -106,21 +100,25 @@ available. Also, we can tell weave to connect to multiple peers by
|
||||
supplying multiple addresses, separated by spaces. And we can
|
||||
[add peers dynamically](http://docs.weave.works/weave/latest_release/features.html#dynamic-topologies).
|
||||
|
||||
The router, DNS and proxy need to be started once per host. The
|
||||
relevant container images are pulled down on demand, but if you wish
|
||||
you can preload them by running `weave setup` - this is particularly
|
||||
useful for automated deployments, and ensures that there are no delays
|
||||
during later operations.
|
||||
|
||||
Now that we've got everything set up, let's see whether our containers
|
||||
can talk to each other...
|
||||
|
||||
On `$HOST1`...
|
||||
In the container started on `$HOST1`...
|
||||
|
||||
host1$ docker attach a1
|
||||
root@a1:/# ping -c 1 -q a2
|
||||
PING a2.weave.local (10.160.0.2) 56(84) bytes of data.
|
||||
--- a2.weave.local ping statistics ---
|
||||
1 packets transmitted, 1 received, 0% packet loss, time 0ms
|
||||
rtt min/avg/max/mdev = 0.341/0.341/0.341/0.000 ms
|
||||
|
||||
Similarly, on `$HOST2`...
|
||||
Similarly, in the container started on `$HOST2`...
|
||||
|
||||
host2$ docker attach a2
|
||||
root@a2:/# ping -c 1 -q a1
|
||||
PING a1.weave.local (10.128.0.2) 56(84) bytes of data.
|
||||
--- a1.weave.local ping statistics ---
|
||||
@@ -133,8 +131,11 @@ to each other.
|
||||
## Find out more
|
||||
|
||||
* [Documentation homepage](http://docs.weave.works/weave/latest_release/)
|
||||
* [Getting Started Guides](http://weave.works/guides/)
|
||||
* [Features](http://docs.weave.works/weave/latest_release/features.html)
|
||||
* [Automatic IP Address Management](http://docs.weave.works/weave/latest_release/ipam.html)
|
||||
* [Automatic Discovery with WeaveDNS](http://docs.weave.works/weave/latest_release/weavedns.html)
|
||||
* [Configuring the interaction with Docker](http://docs.weave.works/weave/latest_release/proxy.html)
|
||||
* [Troubleshooting](http://docs.weave.works/weave/latest_release/troubleshooting.html)
|
||||
* [Building](http://docs.weave.works/weave/latest_release/building.html)
|
||||
* [How it works](http://docs.weave.works/weave/latest_release/how-it-works.html)
|
||||
|
||||
+43
-50
@@ -23,9 +23,7 @@ example](https://github.com/weaveworks/weave#example):
|
||||
* [Dynamic topologies](#dynamic-topologies)
|
||||
* [Container mobility](#container-mobility)
|
||||
* [Fault tolerance](#fault-tolerance)
|
||||
* [Automatic IP address management](#ipam)
|
||||
* [Automatic discovery with WeaveDNS](#dns)
|
||||
* [Working with the Docker CLI and API](#proxy)
|
||||
* [Further reading](#further-reading)
|
||||
|
||||
### <a name="virtual-ethernet-switch"></a>Virtual Ethernet Switch
|
||||
|
||||
@@ -67,25 +65,25 @@ notation](http://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing#CIDR_notat
|
||||
|
||||
On $HOST1:
|
||||
|
||||
host1$ C=$(weave run 10.2.1.1/24 -ti ubuntu)
|
||||
host1$ docker run -e WEAVE_CIDR=10.2.1.1/24 -ti ubuntu
|
||||
root@7ca0f6ecf59f:/#
|
||||
|
||||
And $HOST2:
|
||||
|
||||
host2$ C=$(weave run 10.2.1.2/24 -ti ubuntu)
|
||||
host2$ docker run -e WEAVE_CIDR=10.2.1.2/24 -ti ubuntu
|
||||
root@04c4831fafd3:/#
|
||||
|
||||
Then on $HOST1...
|
||||
Then in the container on $HOST1...
|
||||
|
||||
host1$ docker attach $C
|
||||
root@28841bd02eff:/# ping -c 1 -q 10.2.1.2
|
||||
root@7ca0f6ecf59f:/# ping -c 1 -q 10.2.1.2
|
||||
PING 10.2.1.2 (10.2.1.2): 48 data bytes
|
||||
--- 10.2.1.2 ping statistics ---
|
||||
1 packets transmitted, 1 packets received, 0% packet loss
|
||||
round-trip min/avg/max/stddev = 1.048/1.048/1.048/0.000 ms
|
||||
|
||||
Similarly, on $HOST2...
|
||||
Similarly, in the container on $HOST2...
|
||||
|
||||
host2$ docker attach $C
|
||||
root@f76829496120:/# ping -c 1 -q 10.2.1.1
|
||||
root@04c4831fafd3:/# ping -c 1 -q 10.2.1.1
|
||||
PING 10.2.1.1 (10.2.1.1): 48 data bytes
|
||||
--- 10.2.1.1 ping statistics ---
|
||||
1 packets transmitted, 1 packets received, 0% packet loss
|
||||
@@ -93,10 +91,10 @@ Similarly, on $HOST2...
|
||||
|
||||
The IP addresses and netmasks can be anything you like, but make sure
|
||||
they don't conflict with any IP ranges in use on the hosts (including
|
||||
those delegated to IPAM) or IP addresses of external services the
|
||||
hosts or containers need to connect to. The same IP range must be used
|
||||
everywhere, and the individual IP addresses must, of course, be
|
||||
unique.
|
||||
those delegated to weave's [automatic IP address allocator](#ipam)) or
|
||||
IP addresses of external services the hosts or containers need to
|
||||
connect to. The same IP range must be used everywhere, and the
|
||||
individual IP addresses must, of course, be unique.
|
||||
|
||||
### <a name="application-isolation"></a>Application isolation
|
||||
|
||||
@@ -109,27 +107,27 @@ Let's begin by configuring weave's allocator to manage multiple
|
||||
subnets:
|
||||
|
||||
host1$ weave launch -iprange 10.2.0.0/16 -ipsubnet 10.2.1.0/24
|
||||
host1$ weave launch-dns
|
||||
host1$ weave launch-dns && weave launch-proxy
|
||||
host1$ eval $(weave proxy-env)
|
||||
host2$ weave launch -iprange 10.2.0.0/16 -ipsubnet 10.2.1.0/24 $HOST1
|
||||
host2$ weave launch-dns
|
||||
host2$ weave launch-dns && weave launch-proxy
|
||||
host2$ eval $(weave proxy-env)
|
||||
|
||||
This delegates the entire 10.2.0.0/16 subnet to weave, and instructs
|
||||
it to allocate from 10.2.1.0/24 within that if no specific subnet is
|
||||
specified. Now we can launch some containers in the default subnet:
|
||||
|
||||
host1$ weave run --name a1 -ti ubuntu
|
||||
host2$ weave run --name a2 -ti ubuntu
|
||||
host1$ docker run --name a1 -ti ubuntu
|
||||
host2$ docker run --name a2 -ti ubuntu
|
||||
|
||||
And some more containers in a different subnet:
|
||||
|
||||
host1$ weave run net:10.2.2.0/24 --name b1 -ti ubuntu
|
||||
host2$ weave run net:10.2.2.0.24 --name b2 -ti ubuntu
|
||||
host1$ docker run -e WEAVE_CIDR=net:10.2.2.0/24 --name b1 -ti ubuntu
|
||||
host2$ docker run -e WEAVE_CIDR=net:10.2.2.0.24 --name b2 -ti ubuntu
|
||||
|
||||
A quick 'ping' test in the containers confirms that they can talk to
|
||||
each other but not the containers of our first application...
|
||||
|
||||
host1:~$ docker attach b1
|
||||
|
||||
root@b1:/# ping -c 1 -q b2
|
||||
PING b2.weave.local (10.2.2.128) 56(84) bytes of data.
|
||||
--- b2.weave.local ping statistics ---
|
||||
@@ -153,7 +151,11 @@ well-known technique from the 'on metal' days to containers.
|
||||
If desired, a container can be attached to multiple subnets when it is
|
||||
started:
|
||||
|
||||
host1$ weave run net:default net:10.2.2.0/24 -ti ubuntu
|
||||
host1$ docker run -e WEAVE_CIDR="net:default net:10.2.2.0/24" -ti ubuntu
|
||||
|
||||
`net:default` is used here to request allocation of an address from
|
||||
the default subnet in addition to one from an explicitly specified
|
||||
range.
|
||||
|
||||
NB: By default docker permits communication between containers on the
|
||||
same host, via their docker-assigned IP addresses. For complete
|
||||
@@ -166,17 +168,19 @@ be accomplished by starting them with the `--cap-drop net_raw` option.
|
||||
|
||||
### <a name="dynamic-network-attachment"></a>Dynamic network attachment
|
||||
|
||||
In some scenarios containers are started independently, e.g. via some
|
||||
existing tool chain, or require more complex startup sequences than
|
||||
provided by `weave run`. And sometimes the decision which application
|
||||
network a container should be part of is made post-startup. For these
|
||||
situations, weave allows an existing, running container to be attached
|
||||
to the weave network. To illustrate, we can achieve the same effect as
|
||||
the first example with
|
||||
Sometimes the application network to which a container should be
|
||||
attached is not known in advance. For these situations, weave allows
|
||||
an existing, running container to be attached to the weave network. To
|
||||
illustrate, we can achieve the same effect as the first example with
|
||||
|
||||
host1$ C=$(docker run -d -t -i ubuntu)
|
||||
host1$ C=$(docker run -e WEAVE_CIDR=none -dti ubuntu)
|
||||
host1$ weave attach $C
|
||||
|
||||
(Note that since we modified `DOCKER_HOST` to point to the proxy
|
||||
earlier, we have to pass `-e WEAVE_CIDR=none` to start a container
|
||||
that _doesn't_ get automatically attached to the weave network for the
|
||||
purposes of this example.)
|
||||
|
||||
There is a matching `weave detach` command:
|
||||
|
||||
host1$ weave detach $C
|
||||
@@ -479,23 +483,12 @@ restarted in that event, and indeed may not even experience a
|
||||
temporary connectivity failure if the weave container is restarted
|
||||
quickly enough.
|
||||
|
||||
### <a name="ipam"></a>Automatic IP Address Management
|
||||
### <a name="further-reading"></a>Further reading
|
||||
|
||||
Weave can automatically assign unique IP addresses to each container
|
||||
across the network. The `run`, `start`, `attach`, `expose` and `hide`
|
||||
commands will then fetch an address automatically if none is
|
||||
specified. See the [IPAM](ipam.html) documentation for details on how
|
||||
to enable and use this feature.
|
||||
We have made use of weave's automatic IP address allocation, DNS
|
||||
server, and proxy throughout the examples. Each of these components
|
||||
offers additional functionality which you can read about here:
|
||||
|
||||
### <a name="dns"></a>Automatic discovery with WeaveDNS
|
||||
|
||||
WeaveDNS is a distributed DNS service for weave networks, enabling
|
||||
containers to address each other by name rather than IP address. Find
|
||||
out more about WeaveDNS from its [documentation](weavedns.html).
|
||||
|
||||
### <a name="proxy"></a>Working with the Docker CLI and API
|
||||
|
||||
Instead of the `weave` command-line utility, you may prefer to use the
|
||||
standard Docker command-line interface, or the Docker remote API, for
|
||||
starting weave-enabled containers. This can be accomplished with the
|
||||
[Weave Proxy](proxy.html).
|
||||
* [Automatic IP address management](ipam.html)
|
||||
* [Automatic discovery with WeaveDNS](weavedns.html)
|
||||
* [Configuring the interaction with Docker](proxy.html)
|
||||
@@ -29,7 +29,7 @@ encrypted, which carry encapsulated network packets. These
|
||||
|
||||
Weave creates a network bridge on the host. Each container is
|
||||
connected to that bridge via a veth pair, the container side of which
|
||||
is given the IP address & netmask supplied in 'weave run'. Also
|
||||
is given the IP address & netmask supplied by the proxy. Also
|
||||
connected to the bridge is the weave router container.
|
||||
|
||||
A weave router captures Ethernet packets from its bridge-connected
|
||||
|
||||
+1
-1
@@ -10,7 +10,7 @@ layout: default
|
||||
* [Features](features.html)
|
||||
* [Automatic IP Address Management](ipam.html)
|
||||
* [Automatic Discovery with WeaveDNS](weavedns.html)
|
||||
* [Working with the Docker CLI and API](proxy.html)
|
||||
* [Configuring the interaction with Docker](proxy.html)
|
||||
* [Troubleshooting](troubleshooting.html)
|
||||
* [Building](building.html)
|
||||
* [How it works](how-it-works.html)
|
||||
|
||||
+13
-9
@@ -21,12 +21,14 @@ across the network.
|
||||
Containers are automatically allocated an IP address when none is
|
||||
specified when the container is started, e.g.
|
||||
|
||||
host1# C=$(weave run -ti ubuntu)
|
||||
host1$ weave launch && weave launch-proxy
|
||||
host1$ eval $(weave proxy-env)
|
||||
host1$ C=$(docker run -ti ubuntu)
|
||||
|
||||
You can see which address was allocated with
|
||||
[`weave ps`](troubleshooting.html#list-attached-containers):
|
||||
|
||||
host1# weave ps $C
|
||||
host1$ weave ps $C
|
||||
a7aff7249393 7a:51:d1:09:21:78 10.128.0.1/10
|
||||
|
||||
Weave detects when a container has exited and releases its
|
||||
@@ -106,7 +108,7 @@ would be safe wrt weave's startup quorum:
|
||||
By default, weave will allocate IP addresses in the 10.128.0.0/10
|
||||
range. This can be overridden with the `-iprange` option, e.g.
|
||||
|
||||
host1# weave launch -iprange 10.2.0.0/16
|
||||
host1$ weave launch -iprange 10.2.0.0/16
|
||||
|
||||
and must be the same on every host.
|
||||
|
||||
@@ -126,7 +128,7 @@ to the rest of the network without any conflicts arising.
|
||||
|
||||
Once you have given a range of addresses to the IP allocator, you must
|
||||
not use any addresses in that range for anything else. If, in our
|
||||
example, you subsequently executed `weave run 10.2.3.1/24 -ti ubuntu`,
|
||||
example, you subsequently executed `docker run -e WEAVE_CIDR=10.2.3.1/24 -ti ubuntu`,
|
||||
you run the risk that the IP allocator will assign the same address to
|
||||
another container, which will make network traffic delivery
|
||||
intermittent or non-existent for the containers that share the same IP
|
||||
@@ -140,20 +142,20 @@ you may wish to request the allocation of an address from a particular
|
||||
subnet. This is done by specifying the subnet with `net:<subnet>`, in
|
||||
CIDR notation, e.g.
|
||||
|
||||
host1# C=$(weave run net:10.2.7.0/24 -ti ubuntu)
|
||||
host1$ docker run -e WEAVE_CIDR=net:10.2.7.0/24 -ti ubuntu
|
||||
|
||||
You can ask for multiple addresses in different subnets and add in
|
||||
manually-assigned addresses (outside the automatic allocation range),
|
||||
for instance:
|
||||
|
||||
host1# C=$(weave run net:10.2.7.0/24 net:10.2.8.0/24 ip:10.3.9.1/24 -ti ubuntu)
|
||||
host1$ docker run -e WEAVE_CIDR="net:10.2.7.0/24 net:10.2.8.0/24 ip:10.3.9.1/24" -ti ubuntu
|
||||
|
||||
When working with multiple subnets in this way, it is usually
|
||||
desirable to constrain the default subnet - i.e. the one chosen by the
|
||||
allocator when no subnet is supplied - so that it does not overlap
|
||||
with others. One can specify that with `-ipsubnet`:
|
||||
|
||||
host1# weave launch -iprange 10.2.0.0/16 -ipsubnet 10.2.3.0/24
|
||||
host1$ weave launch -iprange 10.2.0.0/16 -ipsubnet 10.2.3.0/24
|
||||
|
||||
`-iprange` should cover the entire range that you will ever use for
|
||||
allocation, and `-ipsubnet` is the subnet that will be used when you
|
||||
@@ -170,7 +172,7 @@ have the containers communicate with each other*, you can choose a
|
||||
`-iprange` that is smaller than `-ipsubnet`, For example, if you
|
||||
launch weave with:
|
||||
|
||||
host1# weave launch -iprange 10.9.0.0/17 -ipsubnet 10.9.0.0/16
|
||||
host1$ weave launch -iprange 10.9.0.0/17 -ipsubnet 10.9.0.0/16
|
||||
|
||||
then you can run all containers in the 10.9.0.0/16 subnet, with
|
||||
automatic allocation using the lower half, leaving the upper half free
|
||||
@@ -213,14 +215,16 @@ The command
|
||||
reports on the current status of the weave router and IP allocator:
|
||||
|
||||
````
|
||||
weave router git-8f675f15c0b5
|
||||
...
|
||||
|
||||
Allocator universe 10.2.0.0/16
|
||||
Owned Ranges:
|
||||
10.2.1.1 -> 96:e9:e2:2e:2d:bc (host1) (v3)
|
||||
10.2.1.128 -> ea:84:25:9b:31:2e (host2) (v3)
|
||||
10.2.1.192 -> ea:6c:21:09:cf:f0 (host3) (v9)
|
||||
Allocator default subnet: 10.2.1.0/24
|
||||
|
||||
...
|
||||
````
|
||||
|
||||
The first section covers the router; see the [troubleshooting
|
||||
|
||||
+32
-49
@@ -16,8 +16,8 @@ instead of `weave run`.
|
||||
* [Usage](#usage)
|
||||
* [Automatic IP address assignment](#ipam)
|
||||
* [Automatic discovery](#dns)
|
||||
* [Multi-host example](#multi-host)
|
||||
* [Securing the docker communication with TLS](#tls)
|
||||
* [Launching containers without the proxy](#without-proxy)
|
||||
* [Troubleshooting](#troubleshooting)
|
||||
|
||||
## <a name="setup"></a>Setup
|
||||
@@ -82,12 +82,6 @@ Multiple IP addresses and networks can be supplied in the `WEAVE_CIDR`
|
||||
variable by space-separating them, as in
|
||||
`WEAVE_CIDR="10.2.1.1/24 10.2.2.1/24"`.
|
||||
|
||||
Using the proxy brings some additional benefits over `weave run`. The
|
||||
proxy ensures that the weave network interface is available before
|
||||
starting a container's application process. Furthermore, containers
|
||||
can be started in foreground mode, and can be automatically removed
|
||||
(with the ususal `--rm`).
|
||||
|
||||
## <a name="ipam"></a>Automatic IP address assignment
|
||||
|
||||
If [automatic IP address assignment](ipam.html) is enabled in weave,
|
||||
@@ -121,48 +115,10 @@ container with a blank `WEAVE_CIDR`, e.g.
|
||||
|
||||
## <a name="dns"></a>Automatic discovery
|
||||
|
||||
Containers started via the proxy are automatically registered in
|
||||
[weaveDNS](weavedns.html) if they have a hostname in the weaveDNS
|
||||
domain (usually `.weave.local`). In order for containers to be able to
|
||||
look up such names, their DNS resolver needs to be configured to point
|
||||
at weaveDNS. This will be done automatically by the proxy while
|
||||
weaveDNS is running. To override this behaviour launch the proxy with
|
||||
either `--with-dns` or `--without-dns`, which will force the proxy to
|
||||
always/never set the resolver to weaveDNS. If there is no hostname
|
||||
provided, the container will be registered in weaveDNS using its
|
||||
container name. Otherwise, if there is no container name, and no
|
||||
hostname (or a hostname outside the weaveDNS domain), the container
|
||||
will not be registered in weaveDNS.
|
||||
|
||||
## <a name="multi-host"></a>Multi-host example
|
||||
|
||||
Here's a complete example of using weave proxies configured with
|
||||
[automatic IP address assignment](#ipam) and
|
||||
[automatic discovery](#dns) to start containers on two hosts such that
|
||||
one can reach the other by name.
|
||||
|
||||
First, let us start weave, weaveDNS and the proxy, and set DOCKER_HOST
|
||||
to point at the latter:
|
||||
|
||||
host1$ weave launch
|
||||
host1$ weave launch-dns
|
||||
host1$ weave launch-proxy
|
||||
host1$ eval "$(weave proxy-env)"
|
||||
|
||||
host2$ weave launch host1
|
||||
host2$ weave launch-dns
|
||||
host2$ weave launch-proxy
|
||||
host2$ eval "$(weave proxy-env)"
|
||||
|
||||
Now let us start a named container on one host, and ping it, by name,
|
||||
from a container on the other host.
|
||||
|
||||
host1$ docker run --name=pingme -dti ubuntu
|
||||
|
||||
host2$ docker run -ti ubuntu ping pingme
|
||||
PING pingme.weave.local (10.128.0.2) 56(84) bytes of data.
|
||||
64 bytes from pingme.weave.local (10.128.0.2): icmp_seq=1 ttl=64 time=0.047 ms
|
||||
...
|
||||
Containers launched via the proxy will use [weaveDNS](weavedns.html)
|
||||
automatically if it is running at the point when they are started -
|
||||
see the [weaveDNS usage](weavedns.html#usage) section for an in-depth
|
||||
explanation of the behaviour and how to control it.
|
||||
|
||||
## <a name="tls"></a>Securing the docker communication with TLS
|
||||
|
||||
@@ -210,6 +166,33 @@ which is exactly the same configuration as when connecting to the
|
||||
docker daemon directly, except that the specified port is the weave
|
||||
proxy port.
|
||||
|
||||
## <a name="without-proxy"></a>Launching containers without the proxy
|
||||
|
||||
If you cannot or do not want to use the proxy you can launch
|
||||
containers on the weave network with `weave run`:
|
||||
|
||||
$ weave run -ti ubuntu
|
||||
|
||||
The arguments after `run` are passed through to `docker run` so you
|
||||
can freely specify whichever docker options are appropriate. Once the
|
||||
container is started, `weave run` attaches it to the weave network, in
|
||||
this example with an address allocated by IPAM. If you wish you can
|
||||
specify addresses manually instead:
|
||||
|
||||
$ weave run 10.2.1.1/24 -ti ubuntu
|
||||
|
||||
There are some limitations to starting containers with `weave run`:
|
||||
|
||||
* containers are always started in the background, i.e. the equivalent
|
||||
of always supplying the -d option to docker run
|
||||
* the --rm option to docker run, for automatically removing containers
|
||||
after they stop, is not available
|
||||
* the weave network interface may not be available immediately on
|
||||
container startup.
|
||||
|
||||
Finally, there is a `weave start` command which starts existing
|
||||
containers with `docker start` and attaches them to the weave network.
|
||||
|
||||
## <a name="troubleshooting"></a>Troubleshooting
|
||||
|
||||
The command
|
||||
|
||||
+57
-126
@@ -21,7 +21,6 @@ hosts.
|
||||
* [Configuring a custom TTL](#ttl)
|
||||
* [Configuring the domain search path](#domain-search-path)
|
||||
* [Using a different local domain](#local-domain)
|
||||
* [Using weaveDNS without `weave run`](#without-run)
|
||||
* [Troubleshooting](#troubleshooting)
|
||||
* [Present limitations](#limitations)
|
||||
|
||||
@@ -30,76 +29,53 @@ hosts.
|
||||
WeaveDNS is deployed as a set of containers that communicate with each
|
||||
other over the weave network. One such container needs to be started
|
||||
on every weave host, by invoking the weave script command
|
||||
`launch-dns`.
|
||||
`launch-dns`:
|
||||
|
||||
```bash
|
||||
$ weave launch
|
||||
$ weave launch-dns 10.2.254.1/24
|
||||
host1$ weave launch && weave launch-dns && weave launch-proxy
|
||||
host1$ eval $(weave proxy-env)
|
||||
```
|
||||
|
||||
Containers started while weaveDNS is running are automatically
|
||||
registered in [weaveDNS](weavedns.html) if they have a hostname in the
|
||||
weaveDNS domain (usually `.weave.local`). In order for containers to
|
||||
be able to look up such names, their DNS resolver needs to be
|
||||
configured to point at weaveDNS. This will be done automatically while
|
||||
weaveDNS is running. If there is no hostname provided, the container
|
||||
will be registered in weaveDNS using its container name. Otherwise, if
|
||||
there is no container name, and no hostname (or a hostname outside the
|
||||
weaveDNS domain), the container will not be registered in weaveDNS.
|
||||
For example, to use the container name as the hostname:
|
||||
Application containers will use weaveDNS automatically if it is
|
||||
running at the point when they are started. They will use it for name
|
||||
resolution, and will register themselves if they have either a
|
||||
hostname in the weaveDNS domain (`weave.local` by default) or have
|
||||
been given an explicit container name:
|
||||
|
||||
```bash
|
||||
$ weave run 10.2.1.25/24 -ti --name=pingme ubuntu
|
||||
$ shell1=$(weave run 10.2.1.26/24 -ti --name=ubuntu ubuntu)
|
||||
$ docker attach $shell1
|
||||
|
||||
host1$ docker run -dti --name=pingme ubuntu
|
||||
host1$ docker run -ti --hostname=ubuntu.weave.local ubuntu
|
||||
root@ubuntu:/# ping pingme
|
||||
...
|
||||
```
|
||||
|
||||
If you start an application container sans `--with-dns` you can still register
|
||||
it in weaveDNS simply by giving the container a hostname in the
|
||||
`.weave.local.` domain:
|
||||
|
||||
```
|
||||
$ weave run 10.2.1.25/24 -ti -h pingme.weave.local ubuntu
|
||||
```
|
||||
If both hostname and container name are specified at the same time the
|
||||
hostname takes precedence; in this circumstance if the hostname is not
|
||||
in the weaveDNS domain the container will not be registered, but will
|
||||
still use weaveDNS for resolution.
|
||||
|
||||
It is also possible to force or forbid an application container's use
|
||||
of weaveDNS with the `--with-dns` and `--without-dns` options to
|
||||
`weave run`; these override the runtime detection of the weaveDNS
|
||||
container.
|
||||
`weave run` and `weave launch-proxy`; these override the runtime
|
||||
detection of the weaveDNS container.
|
||||
|
||||
Each weaveDNS container started with `launch-dns` needs to be given
|
||||
its own, unique, IP address, in a subnet that is common to all
|
||||
weaveDNS containers and not in use on any of the hosts.
|
||||
Each weaveDNS container started with `launch-dns` needs its own unique
|
||||
IP address in a subnet that is common to all weaveDNS containers. In
|
||||
the example above we did not specify such an address, so one was
|
||||
allocated automatically by IPAM from the default subnet; you can
|
||||
however specify an address in CIDR format manually. In this case you
|
||||
are responsible for ensuring that the IP addresses specified are
|
||||
uniquely allocated and not in use by any other container.
|
||||
|
||||
In our example the weaveDNS address is in subnet 10.2.254.0/24 and the
|
||||
application containers are in subnet 10.2.1.0/24. So, to launch and
|
||||
use weaveDNS on a second host we would run:
|
||||
|
||||
```bash
|
||||
host2$ weave launch $HOST1
|
||||
host2$ weave launch-dns 10.2.254.2/24
|
||||
host2$ shell2=$(weave run 10.2.1.36/24 -ti --name=ubuntu2 ubuntu)
|
||||
host2$ docker attach $shell2
|
||||
|
||||
root@ubuntu2:/# ping pingme
|
||||
...
|
||||
```
|
||||
|
||||
Notice the different IP address in the 10.2.254.0/24 subnet we gave to
|
||||
`weave launch-dns`, compared to what we supplied on the first host.
|
||||
|
||||
WeaveDNS containers can be stopped with `stop-dns`.
|
||||
Finally, WeaveDNS containers can be stopped with `stop-dns`.
|
||||
|
||||
## <a name="how-it-works"></a>How it works
|
||||
|
||||
The weaveDNS container running on every host acts as the nameserver
|
||||
for containers on that host. It is told about hostnames for local
|
||||
containers by the `weave run` command. If a hostname is in the
|
||||
`.weave.local` domain then weaveDNS records the association of that
|
||||
name with the container's weave IP address(es).
|
||||
for containers on that host. It learns about hostnames for local
|
||||
containers from the proxy and from the `weave run` command. If a
|
||||
hostname is in the `.weave.local` domain then weaveDNS records the
|
||||
association of that name with the container's weave IP address(es).
|
||||
|
||||
When weaveDNS is queried for a name in the `.weave.local` domain, it
|
||||
first checks its own records. If the name is not found there, it asks
|
||||
@@ -116,7 +92,7 @@ different Docker bridge device. To supply a different bridge device,
|
||||
use the environment variable `DOCKER_BRIDGE`, e.g.,
|
||||
|
||||
```bash
|
||||
$ sudo DOCKER_BRIDGE=someother weave launch-dns 10.2.254.1/24
|
||||
$ sudo DOCKER_BRIDGE=someother weave launch-dns
|
||||
```
|
||||
|
||||
In the event that weaveDNS is launched in this way, it's important that
|
||||
@@ -136,20 +112,21 @@ Returning to our earlier example, let us start an additional `pingme`
|
||||
container, this time on the 2nd host, and then run some ping tests...
|
||||
|
||||
```bash
|
||||
host2$ weave run 10.2.1.35/24 -ti --name=pingme ubuntu
|
||||
host2$ docker attach $shell2
|
||||
host2$ weave launch && weave launch-dns && weave launch-proxy
|
||||
host2$ eval $(weave proxy-env)
|
||||
host2$ docker run -dti --name=pingme ubuntu
|
||||
|
||||
root@ubuntu2:/# ping -nq -c 1 pingme
|
||||
PING pingme.weave.local (10.2.1.35) 56(84) bytes of data.
|
||||
root@ubuntu:/# ping -nq -c 1 pingme
|
||||
PING pingme.weave.local (10.128.0.2) 56(84) bytes of data.
|
||||
...
|
||||
root@ubuntu2:/# ping -nq -c 1 pingme
|
||||
PING pingme.weave.local (10.2.1.25) 56(84) bytes of data.
|
||||
root@ubuntu:/# ping -nq -c 1 pingme
|
||||
PING pingme.weave.local (10.160.0.1) 56(84) bytes of data.
|
||||
...
|
||||
root@ubuntu2:/# ping -nq -c 1 pingme
|
||||
PING pingme.weave.local (10.2.1.25) 56(84) bytes of data.
|
||||
root@ubuntu:/# ping -nq -c 1 pingme
|
||||
PING pingme.weave.local (10.160.0.1) 56(84) bytes of data.
|
||||
...
|
||||
root@ubuntu2:/# ping -nq -c 1 pingme
|
||||
PING pingme.weave.local (10.2.1.35) 56(84) bytes of data.
|
||||
root@ubuntu:/# ping -nq -c 1 pingme
|
||||
PING pingme.weave.local (10.128.0.2) 56(84) bytes of data.
|
||||
...
|
||||
```
|
||||
|
||||
@@ -170,8 +147,8 @@ If you want to give the container a name in DNS *other* than its
|
||||
hostname, you can register it using the `dns-add` command. For example:
|
||||
|
||||
```bash
|
||||
$ shell2=(weave run 10.2.1.27/24 -ti ubuntu)
|
||||
$ weave dns-add 10.2.1.28 $shell2 -h pingme2.weave.local
|
||||
$ C=$(docker run -e WEAVE_CIDR=10.2.1.27/24 -ti ubuntu)
|
||||
$ weave dns-add 10.2.1.27 $C -h pingme2.weave.local
|
||||
```
|
||||
|
||||
You can also use `dns-add` to add the container's configured hostname
|
||||
@@ -180,7 +157,7 @@ and domain, simply by omitting `-h <fqdn>`.
|
||||
The inverse operation can be carried out using the `dns-remove` command:
|
||||
|
||||
```bash
|
||||
$ weave dns-remove 10.2.1.27 $shell2
|
||||
$ weave dns-remove 10.2.1.27 $C
|
||||
```
|
||||
|
||||
When queried about a name with multiple IPs, weaveDNS returns a random
|
||||
@@ -202,7 +179,7 @@ containers that die. You can tell it not to, by adding `--watch=false`
|
||||
to the container args:
|
||||
|
||||
```bash
|
||||
$ weave launch-dns 10.2.254.1/24 --watch=false
|
||||
$ weave launch-dns --watch=false
|
||||
```
|
||||
|
||||
## <a name="ttl"></a>Configuring a custom TTL
|
||||
@@ -215,7 +192,7 @@ However, you can force a different TTL value by launching weaveDNS with
|
||||
the `--ttl` argument:
|
||||
|
||||
```bash
|
||||
$ weave launch-dns 10.2.254.1/24 --ttl=10
|
||||
$ weave launch-dns --ttl=10
|
||||
```
|
||||
|
||||
This will shorten the lifespan of answers sent to other peers,
|
||||
@@ -240,7 +217,7 @@ hostnames across all sub-domains plus some external domains, you need
|
||||
behaviour.
|
||||
|
||||
```bash
|
||||
weave run --with-dns 10.2.1.4/24 -ti \
|
||||
docker run -ti \
|
||||
--dns-search=zone1.weave.local --dns-search=zone2.weave.local \
|
||||
--dns-search=corp1.com --dns-search=corp2.com \
|
||||
--dns-search=weave.local ubuntu
|
||||
@@ -254,60 +231,13 @@ can force weaveDNS to use a different domain by launching it
|
||||
with the `--domain` argument. For example,
|
||||
|
||||
```bash
|
||||
$ weave launch-dns 10.2.254.1/24 --domain="mycompany.local."
|
||||
$ weave launch-dns --domain="mycompany.local."
|
||||
```
|
||||
|
||||
The local domain should end with `local.`, since these names are
|
||||
link-local as per [RFC6762](https://tools.ietf.org/html/rfc6762),
|
||||
(though this is not strictly necessary).
|
||||
|
||||
## <a name="without-run"></a>Using weaveDNS without `weave run`
|
||||
|
||||
When weaveDNS is running, both `weave run` and `weave attach` register
|
||||
the hostname of the given container against the given weave network IP
|
||||
address. And if you use the `--with-dns` option, `weave run`
|
||||
automatically supplies the DNS server address to the new container.
|
||||
|
||||
In some circumstances, you may not want to use the `weave run` command
|
||||
to start containers. You can still take advantage of a running
|
||||
weaveDNS, with some extra manual steps.
|
||||
|
||||
### Supplying the DNS server
|
||||
|
||||
If you want to start containers with `docker run` rather than `weave
|
||||
run`, you can supply the docker bridge IP as the `--dns` option to
|
||||
make it use weaveDNS:
|
||||
|
||||
```bash
|
||||
$ docker_ip=$(docker inspect --format='{{ .NetworkSettings.Gateway }}' weavedns)
|
||||
$ shell2=$(docker run --dns=$docker_ip -ti ubuntu)
|
||||
$ weave attach 10.2.1.27/24 $shell2
|
||||
```
|
||||
|
||||
This isn't very useful unless the container is also attached to the
|
||||
weave network (as in the last line above).
|
||||
|
||||
Also note that this means of finding the Docker bridge's IP address
|
||||
requires a running container (any one would do); another way to find
|
||||
it is:
|
||||
|
||||
```bash
|
||||
$ docker_ip=$(ip -4 addr show dev docker0 | grep -o 'inet [0-9.]*' | cut -d ' ' -f 2)
|
||||
```
|
||||
|
||||
### Supplying the domain search path
|
||||
|
||||
By default, Docker provides containers with a `/etc/resolv.conf` that
|
||||
matches that for the host. In some circumstances, this may include a
|
||||
DNS search path, which will break the nice "bare names resolve"
|
||||
property above.
|
||||
|
||||
Therefore, when starting containers with `docker run` instead of
|
||||
`weave run`, you will usually want to supply a domain search path so
|
||||
that you can use unqualified hostnames. Use `--dns-search=.` to make
|
||||
the resolver use the container's domain, or e.g.,
|
||||
`--dns-search=weave.local` to make it look in `weave.local`.
|
||||
|
||||
## <a name="troubleshooting"></a>Troubleshooting
|
||||
|
||||
The command
|
||||
@@ -318,19 +248,20 @@ reports on the current status of various weave components, including
|
||||
DNS:
|
||||
|
||||
````
|
||||
weave router git-8f675f15c0b5
|
||||
...
|
||||
|
||||
weave DNS git-8f675f15c0b5
|
||||
Local domain weave.local.
|
||||
weave DNS 1.0.0
|
||||
Listen address :53
|
||||
mDNS interface &{26 65535 ethwe fa:b6:b1:85:ac:9b up|broadcast|multicast}
|
||||
Fallback DNS config &{[66.28.0.45 8.8.8.8] [] 53 1 5 2}
|
||||
Fallback DNS config &{[10.0.2.3] [] 53 1 5 2}
|
||||
|
||||
Local domain weave.local.
|
||||
Interface &{74 65535 ethwe 82:0c:92:84:0e:88 up|broadcast|multicast}
|
||||
Zone database:
|
||||
710978857a88 10.2.1.26 wiff.weave.local.
|
||||
e8d85b1dcdb1 10.2.1.27 waff.weave.local.
|
||||
26bd05f9a0cb 10.2.1.28 ping.weave.local.
|
||||
1ab0e8b17c39 10.2.1.29 pong.weave.local.
|
||||
144b75a9b873: pingme.weave.local.[10.160.0.1]/OBS:1
|
||||
74a5510a91ad: ubuntu.weave.local.[10.160.0.2]
|
||||
weave:remote: pingme.weave.local.[10.128.0.2]/TTL:30
|
||||
|
||||
...
|
||||
````
|
||||
|
||||
The first section covers the router; see the [troubleshooting
|
||||
|
||||
Reference in new issue
Block a user