weave/site/proxy.md

title, layout

title	layout
Weave Docker API Proxy	default

Weave Docker API Proxy

The Docker API proxy automatically attaches containers to the weave network when they are started using the ordinary Docker command-line interface or remote API, instead of weave run.

• Setup
• Usage
• Automatic IP address assignment
• Automatic discovery
• Securing the docker communication with TLS
• Launching containers without the proxy
• Troubleshooting

Setup

The proxy sits between the Docker client (command line or API) and the Docker daemon, intercepting the communication between the two. You can start it simultaneously with the router and weaveDNS via launch:

host1$ weave launch

or independently via launch-proxy:

host1$ weave launch-router && weave launch-proxy

The first form is more convenient, however you can only pass proxy related configuration arguments to launch-proxy so if you need to modify the default behaviour you will have to use the latter.

By default, the proxy decides where to listen based on how the launching client connects to docker. If the launching client connected over a unix socket, the proxy will listen on /var/run/weave.sock. If the launching client connected over TCP, the proxy will listen on port 12375, on all network interfaces. This can be adjusted with the -H argument, e.g.

host1$ weave launch-proxy -H tcp://127.0.0.1:9999

When launching the proxy via TLS, -H and/or TLS options are required.

Multiple -H arguments can be specified. If you are working with a remote docker daemon, then any firewalls inbetween need to be configured to permit access to the proxy port.

All docker commands can be run via the proxy, so it is safe to adjust your DOCKER_HOST to point at the proxy. Weave provides a convenient command for this:

host1$ eval "$(weave env)"
host1$ docker ps
...

The prior settings can be restored with

host1$ eval "$(weave env --restore)"

Alternatively, the proxy host can be set on a per-command basis with

host1$ docker $(weave config) ps

The proxy can be stopped independently with

host1$ weave stop-proxy

or in conjunction with the router and weaveDNS via stop.

If you set your DOCKER_HOST to point at the proxy, you should revert to the original settings prior to stopping the proxy.

Usage

When containers are created via the weave proxy, their entrypoint will be modified to wait for the weave network interface to become available. When they are started via the weave proxy, containers will be automatically assigned IP addresses and connected to the weave network. We can create and start a container via the weave proxy with

host1$ docker run -ti ubuntu

or, equivalently with

host1$ docker create -ti ubuntu
5ef831df61d50a1a49272357155a976595e7268e590f0a2c75693337b14e1382
host1$ docker start 5ef831df61d50a1a49272357155a976595e7268e590f0a2c75693337b14e1382

Specific IP addresses and networks can be supplied in the WEAVE_CIDR environment variable, e.g.

host1$ docker run -e WEAVE_CIDR=10.2.1.1/24 -ti ubuntu

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".

The docker NetworkSettings (including IP address, MacAddress, and IPPrefixLen), will still be returned by docker inspect. If you want docker inspect to return the weave NetworkSettings instead, then the proxy must be launced with the --rewrite-inspect flag. This will only substitute in the weave network settings when the container has a weave IP. If a container has more than one weave IP, the inspect call will only include one of them.

host1$ weave launch-router && weave launch-proxy --rewrite-inspect

Automatic IP address assignment

If automatic IP address assignment is enabled in weave, which it is by default, then containers started via the proxy will be automatically assigned an IP address, without having to specify any special environment variables or other options.

host1$ docker run -ti ubuntu

To use a specific subnet, we pass a WEAVE_CIDR to the container, e.g.

host1$ docker run -ti -e WEAVE_CIDR=net:10.32.2.0/24 ubuntu

To start a container without connecting it to the weave network, pass WEAVE_CIDR=none, e.g.

host1$ docker run -ti -e WEAVE_CIDR=none ubuntu

If you do not want an IP to be assigned by default, the proxy needs to be passed the --no-default-ipalloc flag, e.g.,

host1$ weave launch-proxy --no-default-ipalloc

In this configuration, containers with no WEAVE_CIDR environment variable will not be connected to the weave network. Containers started with a WEAVE_CIDR environment variable are handled as before. To automatically assign an address in this mode, we start the container with a blank WEAVE_CIDR, e.g.

host1$ docker run -ti -e WEAVE_CIDR="" ubuntu

When launching weave-enabled containers, the proxy will automatically rewrite /etc/hosts to replace the docker IP with the container's weave IP. If you need the docker IP to remain in /etc/hosts, the proxy must be launched with the --no-rewrite-hosts flag.

host1$ weave launch-router && weave launch-proxy --no-rewrite-hosts

Automatic discovery

Containers launched via the proxy will use weaveDNS automatically if it is running at the point when they are started - see the weaveDNS usage section for an in-depth explanation of the behaviour and how to control it.

Typically, the proxy will pass on container names as-is to weaveDNS for registration. However, there are situations in which the final container name is out of the user's control (e.g. when using Docker orchestrators which append control/namespacing identifiers to the original container names).

For those situations, the proxy provides a few flags: --hostname-from-label <labelkey>, --hostname-match <regexp> and --hostname-replacement <replacement>. When launching a container, the hostname is initialized to the value of the container label with key <labelkey>, if <labelkey> wasn't provided, the container name is used. Additionally, the hostname is matched against regular expression <regexp>. Then, based on that match, <replacement> will be used to obtainer the final hostname, which will ultimately be handed over to weaveDNS for registration.

For instance, we can launch the proxy using all three flags

host1$ weave launch-router && weave launch-proxy --hostname-from-label hostname-label --hostname-match '^aws-[0-9]+-(.*)$' --hostname-replacement 'my-app-$1'
host1$ eval "$(weave env)"

Note how regexp substitution groups should be prepended with a dollar sign (e.g. $1). For further details on the regular expression syntax please see Google's re2 documentation.

Then, running a container named aws-12798186823-foo without labels will lead to weaveDNS registering hostname my-app-foo and not aws-12798186823-foo.

host1$ docker run -ti --name=aws-12798186823-foo ubuntu ping my-app-foo
PING my-app-foo.weave.local (10.32.0.2) 56(84) bytes of data.
64 bytes from my-app-foo.weave.local (10.32.0.2): icmp_seq=1 ttl=64 time=0.027 ms
64 bytes from my-app-foo.weave.local (10.32.0.2): icmp_seq=2 ttl=64 time=0.067 ms

Also, running a container named foo with label hostname-label=aws-12798186823-foo leads to the same hostname registration.

host1$ docker run -ti --name=foo --label=hostname-label=aws-12798186823-foo ubuntu ping my-app-foo
PING my-app-foo.weave.local (10.32.0.2) 56(84) bytes of data.
64 bytes from my-app-foo.weave.local (10.32.0.2): icmp_seq=1 ttl=64 time=0.031 ms
64 bytes from my-app-foo.weave.local (10.32.0.2): icmp_seq=2 ttl=64 time=0.042 ms

This is because, as we explained above, when providing --hostname-from-label to the proxy, the specified label has precedence over the container's name.

Securing the docker communication with TLS

If you are connecting to the docker daemon with TLS, you will probably want to do the same when connecting to the proxy. That is accomplished by launching the proxy with the same TLS-related command-line flags as supplied to the docker daemon. For example, if you have generated your certificates and keys into the docker host's /tls directory, we can launch the proxy with:

host1$ weave launch-proxy --tls-verify --tls-cacert=/tls/ca.pem \
         --tls-cert=/tls/server-cert.pem --tls-key=/tls/server-key.pem

The paths to your certificates and key must be provided as absolute paths which exist on the docker host.

Because the proxy connects to the docker daemon at unix:///var/run/docker.sock, you must ensure that the daemon is listening there. To do this, you need to pass the -H unix:///var/run/docker.sock option when starting the docker daemon, in addition to the -H options for configuring the TCP listener. See the Docker documentation for an example.

With the proxy running over TLS, we can configure our regular docker client to use TLS on a per-invocation basis with

$ docker --tls-verify --tls-cacert=ca.pem --tls-cert=cert.pem \
     --tls-key=key.pem -H=tcp://host1:12375 version
...

or, by default, with

$ mkdir -pv ~/.docker
$ cp -v {ca,cert,key}.pem ~/.docker
$ eval "$(weave env)"
$ export DOCKER_TLS_VERIFY=1
$ docker version
...

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 automatically allocated IP. 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

weave status

reports on the current status of various weave components, including the proxy, if it is running:

...
weave proxy is running

Information on the operation of the proxy can be obtained from the weaveproxy container logs with

docker logs weaveproxy