moby--moby/docs/userguide/networking/configure-dns.md

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

--name=CONTAINER-NAME	Container name configured using --name 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).
--net-alias=ALIAS	In addition to --name as described above, a container is discovered by one or more of its configured --net-alias (or --alias in docker network connect 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 --alias option in docker network connect command.
--link=CONTAINER_NAME:ALIAS	Using this option as you run a container gives the embedded DNS an extra entry named ALIAS that points to the IP address of the container identified by CONTAINER_NAME. When using --link the embedded DNS will guarantee that localized lookup result only on that container where the --link is used. This lets processes inside the new container connect to container without without having to know its name or IP.
--dns=[IP_ADDRESS...]	The IP addresses passed via the --dns 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 --dns IP addresses are managed by the embedded DNS server and will not be updated in the container's /etc/resolv.conf file.
--dns-search=DOMAIN...	Sets the domain names that are searched when a bare unqualified hostname is used inside of the container. These --dns-search options are managed by the embedded DNS server and will not be updated in the container's /etc/resolv.conf file. When a container process attempts to access host and the search domain example.com is set, for instance, the DNS logic will not only look up host but also host.example.com.
--dns-opt=OPTION...	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 /etc/resolv.conf file. See documentation for resolv.conf for a list of valid options

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.