184 lines
5.5 KiB
ReStructuredText
184 lines
5.5 KiB
ReStructuredText
:title: Link via an Ambassador Container
|
|
:description: Using the Ambassador pattern to abstract (network) services
|
|
:keywords: Examples, Usage, links, docker, documentation, examples, names, name, container naming
|
|
|
|
.. _ambassador_pattern_linking:
|
|
|
|
Link via an Ambassador Container
|
|
================================
|
|
|
|
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 redis 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``.
|
|
|
|
|
|
::
|
|
|
|
#
|
|
#
|
|
# 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
|
|
|