new file mode 100644

@@ -0,0 +1,138 @@

+<!--[metadata]>

+title = "Configure container DNS in user-defined networks"

+description = "Learn how to configure DNS in user-defined networks"

+keywords = ["docker, DNS, network"]

+[menu.main]

+parent = "smn_networking"

+<![end-metadata]-->

+

+# Embedded DNS server in user-defined networks

+

+The information in this section covers the embedded DNS server operation for

+containers in user-defined networks. DNS lookup for containers connected to

+user-defined networks works differently compared to the containers connected

+to `default bridge` network.

+

+> **Note**: In order to maintain backward compatibility, the DNS configuration

+> in `default bridge` network is retained with no behaviorial change.

+> Please refer to the [DNS in default bridge network](default_network/configure-dns.md)

+> for more information on DNS configuration in the `default bridge` network.

+

+As of Docker 1.10, the docker daemon implements an embedded DNS server which

+provides built-in service discovery for any container created with a valid

+`name` or `net-alias` or aliased by `link`. The exact details of how Docker

+manages the DNS configurations inside the container can change from one Docker

+version to the next. So you should not assume the way the files such as

+`/etc/hosts`, `/etc/resolv.conf` are managed inside the containers and leave

+the files alone and use the following Docker options instead.

+

+Various container options that affect container domain name services.

+

+<table>

+  <tr>

+    <td>

+    <p>

+    <code>--name=CONTAINER-NAME</code>

+    </p>

+    </td>

+    <td>

+    <p>

+     Container name configured using <code>--name</code> is used to discover a container within

+     an user-defined docker network. The embedded DNS server maintains the mapping between

+     the container name and its IP address (on the network the container is connected to).

+    </p>

+    </td>

+  </tr>

+  <tr>

+    <td>

+    <p>

+    <code>--net-alias=ALIAS</code>

+    </p>

+    </td>

+    <td>

+    <p>

+     In addition to <code>--name</code> as described above, a container is discovered by one or more 

+     of its configured <code>--net-alias</code> (or <code>--alias</code> in <code>docker network connect</code> command)

+     within the user-defined network. The embedded DNS server maintains the mapping between

+     all of the container aliases and its IP address on a specific user-defined network.

+     A container can have different aliases in different networks by using the <code>--alias</code>

+     option in <code>docker network connect</code> command.

+    </p>

+    </td>

+  </tr>

+  <tr>

+    <td>

+    <p>

+    <code>--link=CONTAINER_NAME:ALIAS</code>

+    </p>

+    </td>

+    <td>

+    <p>

+      Using this option as you <code>run</code> a container gives the embedded DNS

+      an extra entry named <code>ALIAS</code> that points to the IP address

+      of the container identified by <code>CONTAINER_NAME</code>. When using <code>--link</code>

+      the embedded DNS will guarantee that localized lookup result only on that

+      container where the <code>--link</code> is used. This lets processes inside the new container 

+      connect to container without without having to know its name or IP.

+    </p>

+    </td>

+  </tr>

+  <tr>

+    <td><p>

+    <code>--dns=[IP_ADDRESS...]</code>

+    </p></td>

+    <td><p>

+     The IP addresses passed via the <code>--dns</code> option is used by the embedded DNS

+     server to forward the DNS query if embedded DNS server is unable to resolve a name

+     resolution request from the containers.

+     These  <code>--dns</code> IP addresses are managed by the embedded DNS server and

+     will not be updated in the container's <code>/etc/resolv.conf</code> file.

+  </tr>

+  <tr>

+    <td><p>

+    <code>--dns-search=DOMAIN...</code>

+    </p></td>

+    <td><p>

+    Sets the domain names that are searched when a bare unqualified hostname is

+    used inside of the container. These <code>--dns-search</code> options are managed by the

+    embedded DNS server and will not be updated in the container's <code>/etc/resolv.conf</code> file.

+    When a container process attempts to access <code>host</code> and the search

+    domain <code>example.com</code> is set, for instance, the DNS logic will not only

+    look up <code>host</code> but also <code>host.example.com</code>.

+    </p>

+    </td>

+  </tr>

+  <tr>

+    <td><p>

+    <code>--dns-opt=OPTION...</code>

+    </p></td>

+    <td><p>

+      Sets the options used by DNS resolvers. These options are managed by the embedded

+      DNS server and will not be updated in the container's <code>/etc/resolv.conf</code> file.

+    </p>

+    <p>

+    See documentation for <code>resolv.conf</code> for a list of valid options

+    </p></td>

+  </tr>

+</table>

+

+

+In the absence of the `--dns=IP_ADDRESS...`, `--dns-search=DOMAIN...`, or

+`--dns-opt=OPTION...` options, Docker uses the `/etc/resolv.conf` of the

+host machine (where the `docker` daemon runs). While doing so the daemon

+filters out all localhost IP address `nameserver` entries from the host's

+original file.

+

+Filtering is necessary because all localhost addresses on the host are

+unreachable from the container's network. After this filtering, if there are

+no more `nameserver` entries left in the container's `/etc/resolv.conf` file,

+the daemon adds public Google DNS nameservers (8.8.8.8 and 8.8.4.4) to the

+container's DNS configuration. If IPv6 is enabled on the daemon, the public

+IPv6 Google DNS nameservers will also be added (2001:4860:4860::8888 and

+2001:4860:4860::8844).

+

+> **Note**: If you need access to a host's localhost resolver, you must modify

+> your DNS service on the host to listen on a non-localhost address that is

+> reachable from within the container.

@@ -14,7 +14,7 @@ The information in this section explains configuring container DNS within

 the Docker default bridge. This is a `bridge` network named `bridge` created

 automatically when you install Docker.  

-**Note**: The [Docker networks feature](../dockernetworks.md) allows you to create user-defined networks in addition to the default bridge network.

+> **Note**: The [Docker networks feature](../dockernetworks.md) allows you to create user-defined networks in addition to the default bridge network. Please refer to the [Docker Embedded DNS](../configure-dns.md) section for more information on DNS configurations in user-defined networks.

 How can Docker supply each container with a hostname and DNS configuration, without having to build a custom image with the hostname written inside?  Its trick is to overlay three crucial `/etc` files inside the container with virtual files where it can write fresh information.  You can see this by running `mount` inside a container:

@@ -11,7 +11,7 @@ weight=-2

 # Legacy container links

-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.  

+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. 

 Before the [Docker networks feature](../dockernetworks.md), you could use the

 Docker link feature to allow containers to discover each other and securely

@@ -95,6 +95,12 @@ configurations. For example, if you've bound the container port to the

 ## Connect with the linking system

+> **Note**:

+> This section covers the legacy link feature in the default `bridge` network.

+> Please refer to [linking containers in user-defined networks]

+> (../work-with-networks.md#linking-containers-in-user-defined-networks)

+> for more information on links in user-defined networks.

+

 Network port mappings are not the only way Docker containers can connect to one

 another. Docker also has a linking system that allows you to link multiple

 containers together and send connection information from one to another. When

@@ -284,7 +284,7 @@ The default `docker0` bridge network supports the use of port mapping and  `dock

 ## User-defined networks

 You can create your own user-defined networks that better isolate containers.

-Docker provides some default **network drivers** for use creating these

+Docker provides some default **network drivers** for creating these

 networks. You can create a new **bridge network** or **overlay network**. You

 can also create a **network plugin** or **remote network**  written to your own

 specifications.

@@ -439,6 +439,10 @@ Docker Engine for use with `overlay` network. There are two options to set:

         <td><pre>--cluster-advertise=HOST_IP|HOST_IFACE:PORT</pre></td>

         <td>The IP address or interface of the HOST used for clustering.</td>

     </tr>

+    <tr>

+        <td><pre>--cluster-store-opt=KEY-VALUE OPTIONS</pre></td>

+        <td>Options such as TLS certificate or tuning discovery Timers</td>

+    </tr>

     </tbody>

 </table>

@@ -485,17 +489,28 @@ networks can include features not present in Docker's default networks. For more

 information on writing plugins, see [Extending Docker](../../extend/index.md) and

 [Writing a network driver plugin](../../extend/plugins_network.md).

-## Legacy links

+### Docker embedded DNS server

+

+Docker daemon runs an embedded DNS server to provide automatic service discovery

+for containers connected to user defined networks. Name resolution requests from

+the containers are handled first by the embedded DNS server. If the embedded DNS

+server is unable to resolve the request it will be forwarded to any external DNS

+servers configured for the container. To facilitate this when the container is

+created, only the embedded DNS server reachable at `127.0.0.11` will be listed

+in the container's `resolv.conf` file. More information on embedded DNS server on

+user-defined networks can be found in the [embedded DNS server in user-defined networks]

+(configure-dns.md)

+

+## Links

 Before the Docker network feature, you could use the Docker link feature to

-allow containers to discover each other and securely transfer information about

-one container to another container. With the introduction of Docker networks,

-you can still create links but they are only supported on the default `bridge`

-network named `bridge` and appearing in your network stack as `docker0`.

-

-While links are still supported in this limited capacity, you should avoid them

-in preference of Docker networks. The link feature is expected to be deprecated

-and removed in a future release.

+allow containers to discover each other.  With the introduction of Docker networks,

+containers can be discovered by its name automatically. But you can still create

+links but they behave differently when used in the default `docker0` bridge network

+compared to user-defined networks. For more information, please refer to

+[Legacy Links](default_network/dockerlinks.md) for link feature in default `bridge` network

+and the [linking containers in user-defined networks](work-with-networks.md#linking-containers-in-user-defined-networks) for links

+functionality in user-defined networks.

 ## Related information

@@ -158,10 +158,16 @@ To create an overlay network

 3. Create your `overlay` network.

-		$ docker network create --driver overlay my-net

+		$ docker network create --driver overlay --subnet=10.0.9.0/24 my-net

 	You only need to create the network on a single host in the cluster. In this case, you used the Swarm master but you could easily have run it on any host in the cluster.

+> **Note** : It is highly recommended to use the `--subnet` option when creating

+> a network. If the `--subnet` is not specified, the docker daemon automatically

+> chooses and assigns a subnet for the network and it could overlap with another subnet

+> in your infrastructure that is not managed by docker. Such overlaps can cause

+> connectivity issues or failures when containers are connected to that network.

+

 4. Check that the network is running:

 		$ docker network ls

@@ -308,41 +314,9 @@ to have external connectivity outside of their cluster.

 ## Step 6: Extra Credit with Docker Compose

-You can try starting a second network on your existing Swarm cluster using Docker Compose.

-

-1. If you haven't already, install Docker Compose.

-

-2. Change your environment to the Swarm master.

-

-		$ eval $(docker-machine env --swarm mhs-demo0)

-

-3. Create a `docker-compose.yml` file.

-

-4. Add the following content to the file.

-

-		web:

-			image: bfirsh/compose-mongodb-demo

-			environment:

-				- "MONGO_HOST=counter_mongo_1"

-				- "constraint:node==mhs-demo0"

-			ports:

-				- "80:5000"

-		mongo:

-			image: mongo

-

-5. Save and close the file.

-

-6. Start the application with Compose.

-

-		$ docker-compose --x-networking --project-name=counter up -d

-

-7. Get the Swarm master's IP address.

-

-		$ docker-machine ip mhs-demo0

-

-8. Put the IP address into your web browser.

-

-	Upon success, the browser should display the web application.

+Please refer to the Networking feature introduced in [Compose V2 format]

+(https://docs.docker.com/compose/networking/) and execute the

+multi-host networking scenario in the Swarm cluster used above.

 ## Related information

@@ -79,7 +79,13 @@ management that can assist your implementation.

 When you create a network, Engine creates a non-overlapping subnetwork for the

 network by default. You can override this default and specify a subnetwork

 directly using the the `--subnet` option. On a `bridge` network you can only

-create a single subnet. An `overlay` network supports multiple subnets.

+specify a single subnet. An `overlay` network supports multiple subnets.

+

+> **Note** : It is highly recommended to use the `--subnet` option while creating

+> a network. If the `--subnet` is not specified, the docker daemon automatically

+> chooses and assigns a subnet for the network and it could overlap with another subnet

+> in your infrastructure that is not managed by docker. Such overlaps can cause

+> connectivity issues or failures when containers are connected to that network.

 In addition to the `--subnetwork` option, you also specify the `--gateway` `--ip-range` and `--aux-address` options.

@@ -778,6 +784,25 @@ round-trip min/avg/max = 0.119/0.146/0.174 ms

 / #

 ```

+There are certain scenarios such as ungraceful docker daemon restarts in multi-host network,

+where the daemon is unable to cleanup stale connectivity endpoints. Such stale endpoints

+may cause an error `container already connected to network` when a new container is

+connected to that network with the same name as the stale endpoint. In order to cleanup

+these stale endpoints, first remove the container and force disconnect 

+(`docker network disconnect -f`)  the endpoint from the network. Once the endpoint is 

+cleaned up, the container can be connected to the network.

+

+```

+$ docker run -d --name redis_db --net multihost redis

+ERROR: Cannot start container bc0b19c089978f7845633027aa3435624ca3d12dd4f4f764b61eac4c0610f32e: container already connected to network multihost

+

+$ docker rm -f redis_db

+$ docker network disconnect -f multihost redis_db

+

+$ docker run -d --name redis_db --net multihost redis

+7d986da974aeea5e9f7aca7e510bdb216d58682faa83a9040c2f2adc0544795a

+```

+

 ## Remove a network

 When all the containers in a network are stopped or disconnected, you can remove a network.