moby--moby/docs/articles/ambassador_pattern_linking.md

<!--[metadata]>
+++
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"]
[menu.main]
parent = "smn_administrate"
weight = 6
+++
<![end-metadata]-->

# Link via an ambassador container

## Introduction

Rather than hardcoding network links between a service consumer and
provider, Docker encourages service portability, for example instead of:

    (consumer) --> (redis)

Requiring you to restart the `consumer` to attach it to a different
`redis` service, you can add ambassadors:

    (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

    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

    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`

    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.

    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:

    # 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 alpine:3.2 sh

In the `redis_ambassador` container, you can see the linked Redis
containers `env`:

    / # 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
    SHLVL=1
    HOME=/root
    REDIS_PORT_6379_TCP_PORT=6379
    REDIS_PORT_6379_TCP_PROTO=tcp
    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=/
    / # exit

This environment is used by the ambassador `socat` script to expose Redis
to the world (via the `-p 6379:6379` port mapping):

    $ docker rm redis_ambassador
    $ CMD="apk update && apk add socat && sh"
    $ docker run -t -i --link redis:redis --name redis_ambassador -p 6379:6379 alpine:3.2 sh -c "$CMD"
    [...]
    / # socat -t 100000000 TCP4-LISTEN:6379,fork,reuseaddr TCP4:172.17.0.136:6379

Now ping the Redis server via the ambassador:

Now go to a different server:

    $ CMD="apk update && apk add socat && sh"
    $ docker run -t -i --expose 6379 --name redis_ambassador alpine:3.2 sh -c "$CMD"
    [...]
    / # socat -t 100000000 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.

    $ 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 based on the `alpine:3.2` image with
`socat` installed. 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`.

    #
    # do
    #   docker build -t svendowideit/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 svendowideit/ambassador
    # on the remote host, you can set up another ambassador
    #    docker run -t -i -name redis_ambassador -expose 6379 -e REDIS_PORT_6379_TCP=tcp://192.168.1.52:6379 svendowideit/ambassador sh
    # you can read more about this process at https://docs.docker.com/articles/ambassador_pattern_linking/

    # use alpine because its a minimal image with a package manager.
    # prettymuch all that is needed is a container that has a functioning env and socat (or equivalent)
    FROM	alpine:3.2
    MAINTAINER	SvenDowideit@home.org.au

    RUN apk update && \
    	apk add socat && \
    	rm -r /var/cache/

    CMD	env | grep _TCP= | sed 's/.*_PORT_\([0-9]*\)_TCP=tcp:\/\/\(.*\):\(.*\)/socat -t 100000000 TCP4-LISTEN:\1,fork,reuseaddr TCP4:\2:\3 \& wait/' | sh