From c75d132f03ff875b7b0f039e354199d4faf5c61e Mon Sep 17 00:00:00 2001 From: Roberto Gandolfo Hashioka Date: Mon, 11 Nov 2013 17:38:54 -0800 Subject: [PATCH 1/2] - Added a doc about Links and Container Naming Upstream-commit: 981560c43631e1b09b6f90945d2d5e58345cabd2 Component: engine --- components/engine/docs/sources/use/index.rst | 1 + .../sources/use/working_with_links_names.rst | 98 +++++++++++++++++++ 2 files changed, 99 insertions(+) create mode 100644 components/engine/docs/sources/use/working_with_links_names.rst diff --git a/components/engine/docs/sources/use/index.rst b/components/engine/docs/sources/use/index.rst index 914d5a2a21..38f61ba744 100644 --- a/components/engine/docs/sources/use/index.rst +++ b/components/engine/docs/sources/use/index.rst @@ -20,3 +20,4 @@ Contents: puppet host_integration working_with_volumes + working_with_links_names diff --git a/components/engine/docs/sources/use/working_with_links_names.rst b/components/engine/docs/sources/use/working_with_links_names.rst new file mode 100644 index 0000000000..ad88b5f910 --- /dev/null +++ b/components/engine/docs/sources/use/working_with_links_names.rst @@ -0,0 +1,98 @@ +:title: Working with Links and Names +:description: How to create and use links and names +:keywords: Examples, Usage, links, docker, documentation, examples, names, name, container naming + +.. _working_with_links_names: + +Working with Links and Names +============================ + +From version 0.6.5 you are able to ``name`` a container and ``link`` it to another +container by referring its name. This will create a relation parent->child where +the parent container can see all the important information about its child. + +.. _run_name: + +Container Naming +---------------- + +.. versionadded:: v0.6.5 + +You can now name your container by using ``-name`` flag. If no name is provided, +Docker will automatically generate a name which can be seen by typing: ``docker ps``. + +.. code-block:: bash + + # format is "sudo docker run -name " + $ sudo docker run -name test ubuntu /bin/bash + +.. _run_link: + +Links: service discovery for docker +----------------------------------- + +.. versionadded:: v0.6.5 + +Links allow containers to discover and securely communicate with each other by using the +flag ``-link name:alias``. Inter-container communication can be disabled with the daemon +flag ``-icc=false``. With this flag set to false, Container A cannot access Container B +unless explicitly allowed via a link. This is a huge win for securing your containers. +When two containers are linked together Docker creates a parent child relationship +between the containers. The parent container will be able to access information via +env variables of the child such as name, exposed ports, ip, and environment variables. + +When linking two containers Docker will use the exposed ports of the container to create +a secure tunnel for the parent to access. If a database container only exposes port 8080 +then the linked container will only be allowed to access port 8080 and nothing else if +inter-container communication is set to false. + +.. code-block:: bash + + # Example: there is an image called redis-2.6 that exposes the port 6379 and starts redis-server. + # Let's name the container as "redis" based on that image and run it as daemon. + $ sudo docker run -d -name redis redis-2.6 + +We can issue all the commands that you would expect using the name "redis"; start, stop, +attach, using the name for our container. The name also allows us to link other containers +into this one. + +Next, we can start a new web application that has a dependency on Redis and apply a link +to connect both containers. If you noticed when running our Redis server we did not use +the -p flag to publish the Redis port to the host system. Redis exposed port 6379 and +this is all we need to establish a link. + +.. code-block:: bash + + # Linking the redis container as a child + $ sudo docker run -t -i -link redis:db -name webapp ubuntu bash + +When you specified -link redis:db you are telling docker to link the container named redis +into this new container with the alias db. Environment variables are prefixed with the alias +so that the parent container can access network and environment information from the containers +that are linked into it. + +If we inspect the environment variables of the second container, we would see all the information +about the child container. + +.. code-block:: bash + + $ sroot@4c01db0b339c:/# env + + HOSTNAME=4c01db0b339c + DB_NAME=/webapp/db + TERM=xterm + DB_PORT=tcp://172.17.0.8:6379 + DB_PORT_6379_TCP=tcp://172.17.0.8:6379 + DB_PORT_6379_TCP_PROTO=tcp + DB_PORT_6379_TCP_ADDR=172.17.0.8 + DB_PORT_6379_TCP_PORT=6379 + PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin + PWD=/ + SHLVL=1 + HOME=/ + container=lxc + _=/usr/bin/env + root@4c01db0b339c:/# + +Accessing the network information along with the environment of the child container allows +us to easily connect to the Redis service on the specific IP and port in the environment. From 9bdd66f858d8e6ee0cced71d2235caa857224409 Mon Sep 17 00:00:00 2001 From: Roberto Gandolfo Hashioka Date: Tue, 12 Nov 2013 10:11:52 -0800 Subject: [PATCH 2/2] - Improved documentation and typos fixing (Thanks to @jamtur01) Upstream-commit: 353243a7254705f92c3d775eec1f9cfe14fa4170 Component: engine --- .../sources/use/working_with_links_names.rst | 20 ++++++++++++------- 1 file changed, 13 insertions(+), 7 deletions(-) diff --git a/components/engine/docs/sources/use/working_with_links_names.rst b/components/engine/docs/sources/use/working_with_links_names.rst index ad88b5f910..02906a8226 100644 --- a/components/engine/docs/sources/use/working_with_links_names.rst +++ b/components/engine/docs/sources/use/working_with_links_names.rst @@ -7,9 +7,9 @@ Working with Links and Names ============================ -From version 0.6.5 you are able to ``name`` a container and ``link`` it to another -container by referring its name. This will create a relation parent->child where -the parent container can see all the important information about its child. +From version 0.6.5 you are now able to ``name`` a container and ``link`` it to another +container by referring to its name. This will create a parent -> child relationship +where the parent container can see selected information about its child. .. _run_name: @@ -18,14 +18,19 @@ Container Naming .. versionadded:: v0.6.5 -You can now name your container by using ``-name`` flag. If no name is provided, -Docker will automatically generate a name which can be seen by typing: ``docker ps``. +You can now name your container by using the ``-name`` flag. If no name is provided, Docker +will automatically generate a name. You can see this name using the ``docker ps`` command. .. code-block:: bash # format is "sudo docker run -name " $ sudo docker run -name test ubuntu /bin/bash + # the flag "-a" Show all containers. Only running containers are shown by default. + $ sudo docker ps -a + CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES + 2522602a0d99 ubuntu:12.04 /bin/bash 14 seconds ago Exit 0 test + .. _run_link: Links: service discovery for docker @@ -39,7 +44,8 @@ flag ``-icc=false``. With this flag set to false, Container A cannot access Cont unless explicitly allowed via a link. This is a huge win for securing your containers. When two containers are linked together Docker creates a parent child relationship between the containers. The parent container will be able to access information via -env variables of the child such as name, exposed ports, ip, and environment variables. +environment variables of the child such as name, exposed ports, IP and other selected +environment variables. When linking two containers Docker will use the exposed ports of the container to create a secure tunnel for the parent to access. If a database container only exposes port 8080 @@ -76,7 +82,7 @@ about the child container. .. code-block:: bash - $ sroot@4c01db0b339c:/# env + $ root@4c01db0b339c:/# env HOSTNAME=4c01db0b339c DB_NAME=/webapp/db