From 344119f42a10a5158704680885e7d4ebfec21a9f Mon Sep 17 00:00:00 2001 From: Adam Harrison Date: Thu, 18 Jun 2015 12:01:32 +0100 Subject: [PATCH 1/7] Update README examples to use proxy --- README.md | 55 ++++++++++++++++++++++++++++--------------------------- 1 file changed, 28 insertions(+), 27 deletions(-) diff --git a/README.md b/README.md index b14f0f68..81c056d8 100644 --- a/README.md +++ b/README.md @@ -52,36 +52,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 @@ -98,21 +92,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 --- @@ -125,8 +123,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) From 81d5a8f4f5fa47076d3c69018fcc1f90b5e0987d Mon Sep 17 00:00:00 2001 From: Adam Harrison Date: Thu, 18 Jun 2015 12:23:31 +0100 Subject: [PATCH 2/7] Update features docs to use proxy --- site/features.md | 93 ++++++++++++++++++++++-------------------------- 1 file changed, 43 insertions(+), 50 deletions(-) diff --git a/site/features.md b/site/features.md index 478968e0..0abcc392 100644 --- a/site/features.md +++ b/site/features.md @@ -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) ### 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. ### 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. ### 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. -### Automatic IP Address Management +### 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: -### 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). - -### 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) From 4d54af39b0d56b7f20323eeb575d5a22b15def51 Mon Sep 17 00:00:00 2001 From: Adam Harrison Date: Thu, 18 Jun 2015 18:08:55 +0100 Subject: [PATCH 3/7] Update weaveDNS docs to use proxy --- site/weavedns.md | 183 +++++++++++++++-------------------------------- 1 file changed, 57 insertions(+), 126 deletions(-) diff --git a/site/weavedns.md b/site/weavedns.md index e2fb4a6d..0720ab77 100644 --- a/site/weavedns.md +++ b/site/weavedns.md @@ -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`. ## 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 `. 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 ``` ## 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). -## 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`. - ## 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 From f15ad71354187911873b4607d9791f380d416cdc Mon Sep 17 00:00:00 2001 From: Adam Harrison Date: Fri, 19 Jun 2015 10:49:00 +0100 Subject: [PATCH 4/7] Update IPAM docs to use proxy --- site/ipam.md | 22 +++++++++++++--------- 1 file changed, 13 insertions(+), 9 deletions(-) diff --git a/site/ipam.md b/site/ipam.md index f4eeee7c..e1d9c22d 100644 --- a/site/ipam.md +++ b/site/ipam.md @@ -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:`, 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 From 6ddecfc764b23c467478929f039301869a32f47d Mon Sep 17 00:00:00 2001 From: Adam Harrison Date: Fri, 19 Jun 2015 11:19:59 +0100 Subject: [PATCH 5/7] Update proxy docs --- site/proxy.md | 81 ++++++++++++++++++++------------------------------- 1 file changed, 32 insertions(+), 49 deletions(-) diff --git a/site/proxy.md b/site/proxy.md index c8c9c77e..87456cc3 100644 --- a/site/proxy.md +++ b/site/proxy.md @@ -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) ## Setup @@ -90,12 +90,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`). - ## Automatic IP address assignment If [automatic IP address assignment](ipam.html) is enabled in weave, @@ -129,48 +123,10 @@ container with a blank `WEAVE_CIDR`, e.g. ## 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. - -## 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. ## Securing the docker communication with TLS @@ -218,6 +174,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. +## 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. + ## Troubleshooting The command From acd2b9abeba4bd4313337fe38181f181ce9f2252 Mon Sep 17 00:00:00 2001 From: Adam Harrison Date: Fri, 19 Jun 2015 14:56:07 +0100 Subject: [PATCH 6/7] Reword proxy hyperlink text in index --- site/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/site/index.md b/site/index.md index e8c4171a..eb15b0f7 100644 --- a/site/index.md +++ b/site/index.md @@ -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) From 1e638be7ac59fc705b07c1bdf59df244a0bcd387 Mon Sep 17 00:00:00 2001 From: Adam Harrison Date: Fri, 19 Jun 2015 16:14:51 +0100 Subject: [PATCH 7/7] Remove weave run from how it works --- site/how-it-works.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/site/how-it-works.md b/site/how-it-works.md index 711d74b7..815fb60f 100644 --- a/site/how-it-works.md +++ b/site/how-it-works.md @@ -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