Links and Container Naming

[crosbymichael]

Links - Spec

Links are a way of expressing a relationship between one container and another. When you link a container, you create a parent/child relationship between the two. As a side effect links also allow you to name containers and reference them by name. Containers can be references by more than one name.

Breaking changes

This the new link feature we will be disabling intercontainer communication by default. Containers will not be able to communicate with each other over the docker0 bridge without having a link to that container. Even with a link, a parent can only communicate to the ports exposed by the child and nothing more.

Initially links will be expressed by injecting the child's data into the parent's environment accessible via namespaced variables:

Examples

• REDIS_ENV_{key}={value}
• REDIS_PORT={value}
• REDIS_PORT_6379_TCP={value}.

Create a named container

docker run -d -name db1 crosbymichael/redis
32da9f6caf76

docker ps
ID              IMAGE                  CMD                     EXPOSES      NAMES
32da9f6caf76    crosbymichael/redis    /redis/src/redis-ser    6379/tcp     db1

Link a container into another

Using the container named 'db1' from our previous example we will create a relationship between our webapp container and redis.

To create a link between two containers you add the -link flag to your docker run command passing the name and alias of the container that you want to link as the child. The alias will be used as the namespace to set environment variables in the parent container. The format is -link <name>:<alias>. The alias will be converted to ALL_CAPS when environment variables are created.

# run a new webapp container and add our redis database as a child
docker run -name frontend -link db1:redis -t -i webapp sh


# access the environment inside our webapp conatiner to collect to redis

BusyBox v1.19.3 (Ubuntu 1:1.19.3-7ubuntu1.1) built-in shell (ash)
Enter 'help' for a list of built-in commands.

/ #

echo $REDIS_PORT_6379_ADDR
tcp://172.17.0.2:6379
./redis-cli -h 172.17.0.2
redis 172.17.0.2:6379>

# back on the host

docker ps
ID              IMAGE                 CMD                     EXPOSES        NAMES
32da9f6caf76    crosbymichael/redis   /redis/src/redis-ser    6379/tcp       db1, frontend/redis
37ewg328232g    webapp                sh                                     frontend

# List all the links 

# we can see that our redis container is now a child of our webapp

Remove redis as a child of frontend

docker rm -link frontend/redis

Introspecting the linked container's environment

Lets run another redis container with a password that the client must use to connect. We store the password in the environment of the container so we can use introspection to retreive the password by the parent.

REDIS=$(docker run -d -e PASSWORD=dockerpass crosbymichael/redis --requirepass dockerpass)

docker link $REDIS db1

docker run -t -i -link db1:redis webapp sh

# inside the webapp container

BusyBox v1.19.3 (Ubuntu 1:1.19.3-7ubuntu1.1) built-in shell (ash)
Enter 'help' for a list of built-in commands.

echo $db_PORT_6379_ADDR
tcp://172.17.0.2:6379
./redis-cli -h 172.17.0.2 -a $db_ENV_PASSWORD
redis 172.17.0.2:6379> set hello world
OK
redis 172.17.0.2:6379>

Client Libs

With client libs you can simplify links more.

import docker
import time
from redis import Redis

proto, ip, port = docker.require('redis')
password = docker.require_env('redis', 'password')

r = Redis(host=ip, port=int(port), password=password)

print 'Connected to redis...'

r.set('name', 'docker')
while True:
        print r.get('name')
        time.sleep(1)

TLDR

Links are a way to express relationships between containers and allow introspection based on those relationships.

[vieux]

It should be --requirepass docker

[mattapperson]

Love this idea!

[paulepanter]

Reading the proposal, I do not fully understand this. Why are names and links related at all? Why can’t the host name, passed with -h to docker run, simply be used as the name for a container?

I also do not understand, why the relationship has to be parent and child? Why the different levels?

[vieux]

do we really need to print it ? The debug looks scary now

[crosbymichael]

I guess not but if there was an error other than an invalid constraint it would be good to know. That was my only reason for outputting to debug.

[tianon]

The pseudo-docs here appear to be somewhat out of date. The first example mentions REDIS_PORT_6379_ADDR, but all I get is REDIS_PORT_6379_TCP (and REDIS_PORT and REDIS_NAME).

Also, the later example has db_PORT_6379_ADDR, but the env vars are always all-uppercased, aren't they? I realize these are semi-unofficial, but official docs will probably at least be based in part on them, and us mere mortals are learning the links feature from them in the meantime. :)

[tianon]

Oh, reading back up, I see you initially describe the correct vars, they're just not necessarily correct in the examples. 👍

[shykes]

Guys (@crosbymichael and @vieux) is this ready for review and merge? This branch is growing way too large, I'm seeing all sorts of things unrelated to links in there.

[crosbymichael]

@shykes

Yes this is ready for a final review and merge. The only thing that is not releated to links in this branch is the static dockerinit changes, nothing else.

[shykes]

LGTM

[shykes]

Note: the spec in this issue is now out-of-date. But as long as the docs are not, it doesn't matter :)

[shykes]

NOTE @crosbymichael: I updated the text of the pull request to match the latest version :)