Docs cleanup for networking features added in v1.10
Signed-off-by: Madhu Venugopal <madhu@docker.com>
This commit is contained in:
Madhu Venugopal
parent
5f5a752bcf
commit
6f863cfa18
6 changed files with 207 additions and 49 deletions
138
docs/userguide/networking/configure-dns.md
Normal file
138
docs/userguide/networking/configure-dns.md
Normal 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.
|
||||
|
|
@ -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.
|
||||
|
|
|
|||
Loading…
Reference in a new issue