From 6ddecfc764b23c467478929f039301869a32f47d Mon Sep 17 00:00:00 2001 From: Adam Harrison Date: Fri, 19 Jun 2015 11:19:59 +0100 Subject: [PATCH] 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