kotovalexarian-likes-github/moby--moby
1
0
Fork 0
mirror of https://github.com/moby/moby.git synced 2022-11-09 12:21:53 -05:00
Code Releases Activity

Docs cleanup for networking features added in v1.10

Browse source 
Signed-off-by: Madhu Venugopal <madhu@docker.com>
This commit is contained in:
Madhu Venugopal 2016-01-31 11:13:25 -08:00
parent 5f5a752bcf
commit 6f863cfa18
6 changed files with 207 additions and 49 deletions
Download patch file Download diff file Expand all files Collapse all files

138
docs/userguide/networking/configure-dns.md Normal file
View file

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

2
docs/userguide/networking/default_network/configure-dns.md
View file

@ -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 the Docker default bridge. This is a `bridge` network named `bridge` created
automatically when you install Docker. 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: 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:

6
docs/userguide/networking/default_network/dockerlinks.md
View file

@ -95,6 +95,12 @@ configurations. For example, if you've bound the container port to the
## Connect with the linking system ## 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 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 another. Docker also has a linking system that allows you to link multiple
containers together and send connection information from one to another. When containers together and send connection information from one to another. When

35
docs/userguide/networking/dockernetworks.md
View file

@ -284,7 +284,7 @@ The default `docker0` bridge network supports the use of port mapping and `dock
## User-defined networks ## User-defined networks
You can create your own user-defined networks that better isolate containers. 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 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 can also create a **network plugin** or **remote network** written to your own
specifications. 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><pre>--cluster-advertise=HOST_IP|HOST_IFACE:PORT</pre></td>
<td>The IP address or interface of the HOST used for clustering.</td> <td>The IP address or interface of the HOST used for clustering.</td>
</tr> </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> </tbody>
</table> </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 information on writing plugins, see [Extending Docker](../../extend/index.md) and
[Writing a network driver plugin](../../extend/plugins_network.md). [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 Before the Docker network feature, you could use the Docker link feature to
allow containers to discover each other and securely transfer information about allow containers to discover each other. With the introduction of Docker networks,
one container to another container. With the introduction of Docker networks, containers can be discovered by its name automatically. But you can still create
you can still create links but they are only supported on the default `bridge` links but they behave differently when used in the default `docker0` bridge network
network named `bridge` and appearing in your network stack as `docker0`. compared to user-defined networks. For more information, please refer to
[Legacy Links](default_network/dockerlinks.md) for link feature in default `bridge` network
While links are still supported in this limited capacity, you should avoid them and the [linking containers in user-defined networks](work-with-networks.md#linking-containers-in-user-defined-networks) for links
in preference of Docker networks. The link feature is expected to be deprecated functionality in user-defined networks.
and removed in a future release.
## Related information ## Related information

46
docs/userguide/networking/get-started-overlay.md
View file

@ -158,10 +158,16 @@ To create an overlay network
3. Create your `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. 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: 4. Check that the network is running:
$ docker network ls $ docker network ls
@ -308,41 +314,9 @@ to have external connectivity outside of their cluster.
## Step 6: Extra Credit with Docker Compose ## Step 6: Extra Credit with Docker Compose
You can try starting a second network on your existing Swarm cluster using Docker Compose. Please refer to the Networking feature introduced in [Compose V2 format]
(https://docs.docker.com/compose/networking/) and execute the
1. If you haven't already, install Docker Compose. multi-host networking scenario in the Swarm cluster used above.
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.
## Related information ## Related information

27
docs/userguide/networking/work-with-networks.md
View file

@ -79,7 +79,13 @@ management that can assist your implementation.
When you create a network, Engine creates a non-overlapping subnetwork for the 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 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 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. 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 ## Remove a network
When all the containers in a network are stopped or disconnected, you can remove a network. When all the containers in a network are stopped or disconnected, you can remove a network.