github.com/brahmaroutu/docker@v1.2.1-0.20160809185609-eb28dde01f16/docs/userguide/networking/default_network/dockerlinks.md (about)

     1  <!--[metadata]>
     2  +++
     3  title = "Legacy container links"
     4  description = "Learn how to connect Docker containers together."
     5  keywords = ["Examples, Usage, user guide, links, linking, docker, documentation, examples, names, name, container naming, port, map, network port,  network"]
     6  [menu.main]
     7  parent = "smn_networking_def"
     8  weight=-2
     9  +++
    10  <![end-metadata]-->
    11  
    12  # Legacy container links
    13  
    14  The information in this section explains legacy container links within the Docker default bridge. This is a `bridge` network named `bridge` created automatically when you install Docker.
    15  
    16  Before the [Docker networks feature](../dockernetworks.md), you could use the
    17  Docker link feature to allow containers to discover each other and securely
    18  transfer information about one container to another container. With the
    19  introduction of the Docker networks feature, you can still create links but they
    20  behave differently between default `bridge` network and
    21  [user defined networks](../work-with-networks.md#linking-containers-in-user-defined-networks)
    22  
    23  This section briefly discusses connecting via a network port and then goes into
    24  detail on container linking in default `bridge` network.
    25  
    26  ## Connect using network port mapping
    27  
    28  In [Run a simple application](../../../tutorials/usingdocker.md), you created a
    29  container that ran a Python Flask application:
    30  
    31      $ docker run -d -P training/webapp python app.py
    32  
    33  > **Note:**
    34  > Containers have an internal network and an IP address
    35  > (as we saw when we used the `docker inspect` command to show the container's
    36  > IP address in [Run a simple application](../../../tutorials/usingdocker.md) section).
    37  > Docker can have a variety of network configurations. You can see more
    38  > information on Docker networking [here](../index.md).
    39  
    40  When that container was created, the `-P` flag was used to automatically map
    41  any network port inside it to a random high port within an *ephemeral port
    42  range* on your Docker host. Next, when `docker ps` was run, you saw that port
    43  5000 in the container was bound to port 49155 on the host.
    44  
    45      $ docker ps nostalgic_morse
    46  
    47      CONTAINER ID  IMAGE                   COMMAND       CREATED        STATUS        PORTS                    NAMES
    48      bc533791f3f5  training/webapp:latest  python app.py 5 seconds ago  Up 2 seconds  0.0.0.0:49155->5000/tcp  nostalgic_morse
    49  
    50  You also saw how you can bind a container's ports to a specific port using
    51  the `-p` flag. Here port 80 of the host is mapped to port 5000 of the
    52  container:
    53  
    54      $ docker run -d -p 80:5000 training/webapp python app.py
    55  
    56  And you saw why this isn't such a great idea because it constrains you to
    57  only one container on that specific port.
    58  
    59  Instead, you may specify a range of host ports to bind a container port to
    60  that is different than the default *ephemeral port range*:
    61  
    62      $ docker run -d -p 8000-9000:5000 training/webapp python app.py
    63  
    64  This would bind port 5000 in the container to a randomly available port
    65  between 8000 and 9000 on the host.
    66  
    67  There are also a few other ways you can configure the `-p` flag. By
    68  default the `-p` flag will bind the specified port to all interfaces on
    69  the host machine. But you can also specify a binding to a specific
    70  interface, for example only to the `localhost`.
    71  
    72      $ docker run -d -p 127.0.0.1:80:5000 training/webapp python app.py
    73  
    74  This would bind port 5000 inside the container to port 80 on the
    75  `localhost` or `127.0.0.1` interface on the host machine.
    76  
    77  Or, to bind port 5000 of the container to a dynamic port but only on the
    78  `localhost`, you could use:
    79  
    80      $ docker run -d -p 127.0.0.1::5000 training/webapp python app.py
    81  
    82  You can also bind UDP ports by adding a trailing `/udp`. For example:
    83  
    84      $ docker run -d -p 127.0.0.1:80:5000/udp training/webapp python app.py
    85  
    86  You also learned about the useful `docker port` shortcut which showed us the
    87  current port bindings. This is also useful for showing you specific port
    88  configurations. For example, if you've bound the container port to the
    89  `localhost` on the host machine, then the `docker port` output will reflect that.
    90  
    91      $ docker port nostalgic_morse 5000
    92  
    93      127.0.0.1:49155
    94  
    95  > **Note:**
    96  > The `-p` flag can be used multiple times to configure multiple ports.
    97  
    98  ## Connect with the linking system
    99  
   100  > **Note**:
   101  > This section covers the legacy link feature in the default `bridge` network.
   102  > Please refer to [linking containers in user-defined networks]
   103  > (../work-with-networks.md#linking-containers-in-user-defined-networks)
   104  > for more information on links in user-defined networks.
   105  
   106  Network port mappings are not the only way Docker containers can connect to one
   107  another. Docker also has a linking system that allows you to link multiple
   108  containers together and send connection information from one to another. When
   109  containers are linked, information about a source container can be sent to a
   110  recipient container. This allows the recipient to see selected data describing
   111  aspects of the source container.
   112  
   113  ### The importance of naming
   114  
   115  To establish links, Docker relies on the names of your containers.
   116  You've already seen that each container you create has an automatically
   117  created name; indeed you've become familiar with our old friend
   118  `nostalgic_morse` during this guide. You can also name containers
   119  yourself. This naming provides two useful functions:
   120  
   121  1. It can be useful to name containers that do specific functions in a way
   122     that makes it easier for you to remember them, for example naming a
   123     container containing a web application `web`.
   124  
   125  2. It provides Docker with a reference point that allows it to refer to other
   126     containers, for example, you can specify to link the container `web` to container `db`.
   127  
   128  You can name your container by using the `--name` flag, for example:
   129  
   130      $ docker run -d -P --name web training/webapp python app.py
   131  
   132  This launches a new container and uses the `--name` flag to
   133  name the container `web`. You can see the container's name using the
   134  `docker ps` command.
   135  
   136      $ docker ps -l
   137  
   138      CONTAINER ID  IMAGE                  COMMAND        CREATED       STATUS       PORTS                    NAMES
   139      aed84ee21bde  training/webapp:latest python app.py  12 hours ago  Up 2 seconds 0.0.0.0:49154->5000/tcp  web
   140  
   141  You can also use `docker inspect` to return the container's name.
   142  
   143  
   144  > **Note:**
   145  > Container names have to be unique. That means you can only call
   146  > one container `web`. If you want to re-use a container name you must delete
   147  > the old container (with `docker rm`) before you can create a new
   148  > container with the same name. As an alternative you can use the `--rm`
   149  > flag with the `docker run` command. This will delete the container
   150  > immediately after it is stopped.
   151  
   152  ## Communication across links
   153  
   154  Links allow containers to discover each other and securely transfer information
   155  about one container to another container. When you set up a link, you create a
   156  conduit between a source container and a recipient container. The recipient can
   157  then access select data about the source. To create a link, you use the `--link`
   158  flag. First, create a new container, this time one containing a database.
   159  
   160      $ docker run -d --name db training/postgres
   161  
   162  This creates a new container called `db` from the `training/postgres`
   163  image, which contains a PostgreSQL database.
   164  
   165  Now, you need to delete the `web` container you created previously so you can replace it
   166  with a linked one:
   167  
   168      $ docker rm -f web
   169  
   170  Now, create a new `web` container and link it with your `db` container.
   171  
   172      $ docker run -d -P --name web --link db:db training/webapp python app.py
   173  
   174  This will link the new `web` container with the `db` container you created
   175  earlier. The `--link` flag takes the form:
   176  
   177      --link <name or id>:alias
   178  
   179  Where `name` is the name of the container we're linking to and `alias` is an
   180  alias for the link name. You'll see how that alias gets used shortly.
   181  The `--link` flag also takes the form:
   182  
   183  	--link <name or id>
   184  
   185  In which case the alias will match the name. You could have written the previous
   186  example as:
   187  
   188      $ docker run -d -P --name web --link db training/webapp python app.py
   189  
   190  Next, inspect your linked containers with `docker inspect`:
   191  
   192      $ docker inspect -f "{{ .HostConfig.Links }}" web
   193  
   194      [/db:/web/db]
   195  
   196  You can see that the `web` container is now linked to the `db` container
   197  `web/db`. Which allows it to access information about the `db` container.
   198  
   199  So what does linking the containers actually do? You've learned that a link allows a
   200  source container to provide information about itself to a recipient container. In
   201  our example, the recipient, `web`, can access information about the source `db`. To do
   202  this, Docker creates a secure tunnel between the containers that doesn't need to
   203  expose any ports externally on the container; you'll note when we started the
   204  `db` container we did not use either the `-P` or `-p` flags. That's a big benefit of
   205  linking: we don't need to expose the source container, here the PostgreSQL database, to
   206  the network.
   207  
   208  Docker exposes connectivity information for the source container to the
   209  recipient container in two ways:
   210  
   211  * Environment variables,
   212  * Updating the `/etc/hosts` file.
   213  
   214  ### Environment variables
   215  
   216  Docker creates several environment variables when you link containers. Docker
   217  automatically creates environment variables in the target container based on
   218  the `--link` parameters.  It will also expose all environment variables
   219  originating from Docker from the source container. These include variables from:
   220  
   221  * the `ENV` commands in the source container's Dockerfile
   222  * the `-e`, `--env` and `--env-file` options on the `docker run`
   223  command when the source container is started
   224  
   225  These environment variables enable programmatic discovery from within the
   226  target container of information related to the source container.
   227  
   228  > **Warning**:
   229  > It is important to understand that *all* environment variables originating
   230  > from Docker within a container are made available to *any* container
   231  > that links to it. This could have serious security implications if sensitive
   232  > data is stored in them.
   233  
   234  Docker sets an `<alias>_NAME` environment variable for each target container
   235  listed in the `--link` parameter. For example, if a new container called
   236  `web` is linked to a database container called `db` via `--link db:webdb`,
   237  then Docker creates a `WEBDB_NAME=/web/webdb` variable in the `web` container.
   238  
   239  Docker also defines a set of environment variables for each port exposed by the
   240  source container.  Each variable has a unique prefix in the form:
   241  
   242  `<name>_PORT_<port>_<protocol>`
   243  
   244  The components in this prefix are:
   245  
   246  * the alias `<name>` specified in the `--link` parameter (for example, `webdb`)
   247  * the `<port>` number exposed
   248  * a `<protocol>` which is either TCP or UDP
   249  
   250  Docker uses this prefix format to define three distinct environment variables:
   251  
   252  * The `prefix_ADDR` variable contains the IP Address from the URL, for
   253  example `WEBDB_PORT_5432_TCP_ADDR=172.17.0.82`.
   254  * The `prefix_PORT` variable contains just the port number from the URL for
   255  example `WEBDB_PORT_5432_TCP_PORT=5432`.
   256  * The `prefix_PROTO` variable contains just the protocol from the URL for
   257  example `WEBDB_PORT_5432_TCP_PROTO=tcp`.
   258  
   259  If the container exposes multiple ports, an environment variable set is
   260  defined for each one. This means, for example, if a container exposes 4 ports
   261  that Docker creates 12 environment variables, 3 for each port.
   262  
   263  Additionally, Docker creates an environment variable called `<alias>_PORT`.
   264  This variable contains the URL of the source container's first exposed port.
   265  The  'first' port is defined as the exposed port with the lowest number.
   266  For example, consider the `WEBDB_PORT=tcp://172.17.0.82:5432` variable.  If
   267  that port is used for both tcp and udp, then the tcp one is specified.
   268  
   269  Finally, Docker also exposes each Docker originated environment variable
   270  from the source container as an environment variable in the target. For each
   271  variable Docker creates an `<alias>_ENV_<name>` variable in the target
   272  container. The variable's value is set to the value Docker used when it
   273  started the source container.
   274  
   275  Returning back to our database example, you can run the `env`
   276  command to list the specified container's environment variables.
   277  
   278  ```
   279      $ docker run --rm --name web2 --link db:db training/webapp env
   280  
   281      . . .
   282      DB_NAME=/web2/db
   283      DB_PORT=tcp://172.17.0.5:5432
   284      DB_PORT_5432_TCP=tcp://172.17.0.5:5432
   285      DB_PORT_5432_TCP_PROTO=tcp
   286      DB_PORT_5432_TCP_PORT=5432
   287      DB_PORT_5432_TCP_ADDR=172.17.0.5
   288      . . .
   289  ```
   290  
   291  You can see that Docker has created a series of environment variables with
   292  useful information about the source `db` container. Each variable is prefixed
   293  with
   294  `DB_`, which is populated from the `alias` you specified above. If the `alias`
   295  were `db1`, the variables would be prefixed with `DB1_`. You can use these
   296  environment variables to configure your applications to connect to the database
   297  on the `db` container. The connection will be secure and private; only the
   298  linked `web` container will be able to talk to the `db` container.
   299  
   300  ### Important notes on Docker environment variables
   301  
   302  Unlike host entries in the [`/etc/hosts` file](#updating-the-etchosts-file),
   303  IP addresses stored in the environment variables are not automatically updated
   304  if the source container is restarted. We recommend using the host entries in
   305  `/etc/hosts` to resolve the IP address of linked containers.
   306  
   307  These environment variables are only set for the first process in the
   308  container. Some daemons, such as `sshd`, will scrub them when spawning shells
   309  for connection.
   310  
   311  ### Updating the `/etc/hosts` file
   312  
   313  In addition to the environment variables, Docker adds a host entry for the
   314  source container to the `/etc/hosts` file. Here's an entry for the `web`
   315  container:
   316  
   317      $ docker run -t -i --rm --link db:webdb training/webapp /bin/bash
   318  
   319      root@aed84ee21bde:/opt/webapp# cat /etc/hosts
   320  
   321      172.17.0.7  aed84ee21bde
   322      . . .
   323      172.17.0.5  webdb 6e5cdeb2d300 db
   324  
   325  You can see two relevant host entries. The first is an entry for the `web`
   326  container that uses the Container ID as a host name. The second entry uses the
   327  link alias to reference the IP address of the `db` container. In addition to
   328  the alias you provide, the linked container's name--if unique from the alias
   329  provided to the `--link` parameter--and the linked container's hostname will
   330  also be added in `/etc/hosts` for the linked container's IP address. You can ping
   331  that host now via any of these entries:
   332  
   333      root@aed84ee21bde:/opt/webapp# apt-get install -yqq inetutils-ping
   334  
   335      root@aed84ee21bde:/opt/webapp# ping webdb
   336  
   337      PING webdb (172.17.0.5): 48 data bytes
   338      56 bytes from 172.17.0.5: icmp_seq=0 ttl=64 time=0.267 ms
   339      56 bytes from 172.17.0.5: icmp_seq=1 ttl=64 time=0.250 ms
   340      56 bytes from 172.17.0.5: icmp_seq=2 ttl=64 time=0.256 ms
   341  
   342  > **Note:**
   343  > In the example, you'll note you had to install `ping` because it was not included
   344  > in the container initially.
   345  
   346  Here, you used the `ping` command to ping the `db` container using its host entry,
   347  which resolves to `172.17.0.5`. You can use this host entry to configure an application
   348  to make use of your `db` container.
   349  
   350  > **Note:**
   351  > You can link multiple recipient containers to a single source. For
   352  > example, you could have multiple (differently named) web containers attached to your
   353  >`db` container.
   354  
   355  If you restart the source container, the linked containers `/etc/hosts` files
   356  will be automatically updated with the source container's new IP address,
   357  allowing linked communication to continue.
   358  
   359      $ docker restart db
   360  
   361      db
   362  
   363      $ docker run -t -i --rm --link db:db training/webapp /bin/bash
   364  
   365      root@aed84ee21bde:/opt/webapp# cat /etc/hosts
   366  
   367      172.17.0.7  aed84ee21bde
   368      . . .
   369      172.17.0.9  db
   370  
   371  # Related information