From 6ddea783ef8067b0c739785b6afd10d58255b4c9 Mon Sep 17 00:00:00 2001 From: Sven Dowideit Date: Wed, 4 Dec 2013 16:47:45 +1000 Subject: [PATCH] initial stab at writing a use/ambassador-pattern howto (Issue #2485) --- .../use/ambassador_pattern_linking.rst | 182 ++++++++++++++++++ docs/sources/use/index.rst | 1 + 2 files changed, 183 insertions(+) create mode 100644 docs/sources/use/ambassador_pattern_linking.rst diff --git a/docs/sources/use/ambassador_pattern_linking.rst b/docs/sources/use/ambassador_pattern_linking.rst new file mode 100644 index 0000000000..98eb009d81 --- /dev/null +++ b/docs/sources/use/ambassador_pattern_linking.rst @@ -0,0 +1,182 @@ +:title: Ambassador pattern linking +:description: Using the Ambassador pattern to abstract (network) services +:keywords: Examples, Usage, links, docker, documentation, examples, names, name, container naming + +.. _ambassador_pattern_linking: + +Ambassador pattern linking +========================== + +Rather than hardcoding network links between a service consumer and provider, Docker +encourages service portability. + +eg, instead of + +.. code-block:: bash + + (consumer) --> (redis) + +requiring you to restart the ``consumer`` to attach it to a different ``redis`` service, +you can add ambassadors + +.. code-block:: bash + + (consumer) --> (redis-ambassador) --> (redis) + + or + + (consumer) --> (redis-ambassador) ---network---> (redis-ambassador) --> (redis) + +When you need to rewire your consumer to talk to a different resdis server, you +can just restart the ``redis-ambassador`` container that the consumer is connected to. + +This pattern also allows you to transparently move the redis server to a different +docker host from the consumer. + +Using the ``svendowideit/ambassador`` container, the link wiring is controlled entirely +from the ``docker run`` parameters. + +Two host Example +---------------- + +Start actual redis server on one Docker host + +.. code-block:: bash + + big-server $ docker run -d -name redis crosbymichael/redis + +Then add an ambassador linked to the redis server, mapping a port to the outside world + +.. code-block:: bash + + big-server $ docker run -d -link redis:redis -name redis_ambassador -p 6379:6379 svendowideit/ambassador + +On the other host, you can set up another ambassador setting environment variables for each remote port we want to proxy to the ``big-server`` + +.. code-block:: bash + + client-server $ docker run -d -name redis_ambassador -expose 6379 -e REDIS_PORT_6379_TCP=tcp://192.168.1.52:6379 svendowideit/ambassador + +Then on the ``client-server`` host, you can use a redis client container to talk +to the remote redis server, just by linking to the local redis ambassador. + +.. code-block:: bash + + client-server $ docker run -i -t -rm -link redis_ambassador:redis relateiq/redis-cli + redis 172.17.0.160:6379> ping + PONG + + + +How it works +------------ + +The following example shows what the ``svendowideit/ambassador`` container does +automatically (with a tiny amount of ``sed``) + +On the docker host (192.168.1.52) that redis will run on: + +.. code-block:: bash + + # start actual redis server + $ docker run -d -name redis crosbymichael/redis + + # get a redis-cli container for connection testing + $ docker pull relateiq/redis-cli + + # test the redis server by talking to it directly + $ docker run -t -i -rm -link redis:redis relateiq/redis-cli + redis 172.17.0.136:6379> ping + PONG + ^D + + # add redis ambassador + $ docker run -t -i -link redis:redis -name redis_ambassador -p 6379:6379 busybox sh + +in the redis_ambassador container, you can see the linked redis containers's env + +.. code-block:: bash + + $ env + REDIS_PORT=tcp://172.17.0.136:6379 + REDIS_PORT_6379_TCP_ADDR=172.17.0.136 + REDIS_NAME=/redis_ambassador/redis + HOSTNAME=19d7adf4705e + REDIS_PORT_6379_TCP_PORT=6379 + HOME=/ + REDIS_PORT_6379_TCP_PROTO=tcp + container=lxc + REDIS_PORT_6379_TCP=tcp://172.17.0.136:6379 + TERM=xterm + PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin + PWD=/ + + +This environment is used by the ambassador socat script to expose redis to the world +(via the -p 6379:6379 port mapping) + +.. code-block:: bash + + $ docker rm redis_ambassador + $ sudo ./contrib/mkimage-unittest.sh + $ docker run -t -i -link redis:redis -name redis_ambassador -p 6379:6379 docker-ut sh + + $ socat TCP4-LISTEN:6379,fork,reuseaddr TCP4:172.17.0.136:6379 + +then ping the redis server via the ambassador + +.. code-block::bash + + $ docker run -i -t -rm -link redis_ambassador:redis relateiq/redis-cli + redis 172.17.0.160:6379> ping + PONG + +Now goto a different server + +.. code-block:: bash + + $ sudo ./contrib/mkimage-unittest.sh + $ docker run -t -i -expose 6379 -name redis_ambassador docker-ut sh + + $ socat TCP4-LISTEN:6379,fork,reuseaddr TCP4:192.168.1.52:6379 + +and get the redis-cli image so we can talk over the ambassador bridge + +.. code-block:: bash + + $ docker pull relateiq/redis-cli + $ docker run -i -t -rm -link redis_ambassador:redis relateiq/redis-cli + redis 172.17.0.160:6379> ping + PONG + +The svendowideit/ambassador Dockerfile +-------------------------------------- + +The ``svendowideit/ambassador`` image is a small busybox image with ``socat`` built in. +When you start the container, it uses a small ``sed`` script to parse out the (possibly multiple) +link environment variables to set up the port forwarding. On the remote host, you need to set the +variable using the ``-e`` command line option. + +``-expose 1234 -e REDIS_PORT_1234_TCP=tcp://192.168.1.52:6379`` will forward the +local ``1234`` port to the remote IP and port - in this case ``192.168.1.52:6379``. + + +.. code-block:: Dockerfile + + # + # + # first you need to build the docker-ut image using ./contrib/mkimage-unittest.sh + # then + # docker build -t SvenDowideit/ambassador . + # docker tag SvenDowideit/ambassador ambassador + # then to run it (on the host that has the real backend on it) + # docker run -t -i -link redis:redis -name redis_ambassador -p 6379:6379 ambassador + # on the remote host, you can set up another ambassador + # docker run -t -i -name redis_ambassador -expose 6379 sh + + FROM docker-ut + MAINTAINER SvenDowideit@home.org.au + + + CMD env | grep _TCP= | sed 's/.*_PORT_\([0-9]*\)_TCP=tcp:\/\/\(.*\):\(.*\)/socat TCP4-LISTEN:\1,fork,reuseaddr TCP4:\2:\3 \&/' | sh && top + diff --git a/docs/sources/use/index.rst b/docs/sources/use/index.rst index 38f61ba744..a3e595a1b8 100644 --- a/docs/sources/use/index.rst +++ b/docs/sources/use/index.rst @@ -21,3 +21,4 @@ Contents: host_integration working_with_volumes working_with_links_names + ambassador_pattern_linking