Container Hostnames and DNS with Docker Compose

1. Introduction

In this tutorial, we’ll explore how to create different names for the same service in docker-compose.yml. First, we’ll recap the basics of Docker networking. Then we’ll create a docker-compose.yml file with the necessary settings. Finally, we’ll test an example scenario.

2. Understanding Docker Networking Basics

Unless otherwise specified, Docker Compose creates a default network for your services. Containers access the network via a network interface, which includes an IP address, a gateway, a routing table, DNS services, and other networking details.

Each container gets an IP address and a DNS entry that allows services to refer to each other by name. So, when we define a service in a Docker Compose file, Docker automatically assigns a hostname to the container corresponding to the service name. In addition, it registers the container name in an internal DNS, making it accessible to other containers on the same network.

For example, a service named web can be accessed by other services via http://web. In addition, containers take over their host’s DNS settings, that is they use the same DNS nameserver defined in the host’s /etc/resolv.conf file.

However, localhost within a container refers to the container itself, not the host machine. Consequently, this distinction can lead to confusion when testing services or setting up inter-container communication, as there are cases where we want to allow other containers and the container itself to communicate using a single hostname or specific alias.

So, let’s understand how to use the hostname flag correctly and how creating an alias for containers via docker-compose.yml can help fill this gap.

3. Defining Custom Hostnames for Containers

Although the default service name works as a hostname, we can explicitly define a hostname for a container:

services:
  app:
    image: my-app
    hostname: myapp-host

In this case, the container will recognize itself internally, as well as other containers that are on the same network as myapp-host. However, this doesn’t change the container’s name, which must be set using the container_name flag.

4. Setting Up an Alias for a Container

Another way of accessing a service by a name other than the declared one is by defining an alias. To create an alias in docker-compose.yml, we’ll leverage Docker’s ability to define custom networks and aliases. So, let’s add the following entry to the service description in our file:

networks:
  <network-name>:
    aliases:
      - <alias-chosen>

This enables us to assign the service to a customized Docker network, ensuring isolated communication with containers on the same network. Additionally, we need to specify a name for the network and, if desired, an alias for the container. Once the alias is defined, other containers on the same network can access the service via the alias instead of its default name.

However, aliases are defined within the scope of a network, meaning the same service can have different names across various networks, with multiple aliases possible for the same service.

After that, a custom network needs to be configured:

networks:
  <network-name>:
    driver: <network-driver>

The networks key defines the custom network configurations for the Docker Compose setup. Next, network-name is the name of the custom network being defined. We can give it any meaningful name that we choose. Finally, the driver key specifies the option that will be used by the network.

In addition, there are several drivers available that provide basic network functionality:

5. Testing the Configuration

To illustrate, let’s say we’re using mock services but want to access them under the real service names so that we don’t have to adjust our application configuration elsewhere.

So, let’s create a Docker Compose file that contains three services:

• mock_db, which uses the Redis image and has the hostname prod_db
• mock_api, a simple API that has the alias prod_api
• mock_nginx, which uses the Nginx image and has the container name specified as prod_nginx

In addition, both services connect to a custom bridge network called custom_network for communication between containers:

services:
  mock_db:
    image: redis
    hostname: prod_db
    networks:
      - custom_network

  mock_api:
    image: kennethreitz/httpbin 
    networks:
      custom_network:
        aliases:
          - prod_api
      
  mock_nginx:
    image: nginx:latest
    container_name: prod_nginx
    networks:
      - custom_network

networks:
  custom_network:
    driver: bridge

Let’s enable the services using Docker Compose:

$ docker compose up -d
[+] Running 3/3
 ✔ Container alias-mock_db-1   Started                                                               0.0s 
 ✔ Container alias-mock_api-1  Started                                                               0.0s 
 ✔ Container prod_nginx        Started                                                               0.0s

And now let’s run the docker ps command to check the names assigned to the containers:

$ docker ps
CONTAINER ID   IMAGE                  COMMAND                  CREATED              STATUS              PORTS                               NAMES
ae860f1b9764   kennethreitz/httpbin   "gunicorn -b 0.0.0.0…"   About a minute ago   Up About a minute   80/tcp                              alias-mock_api-1
63cdc9e7f086   nginx:latest           "/docker-entrypoint.…"   About a minute ago   Up About a minute   0.0.0.0:80->80/tcp, :::80->80/tcp   prod_nginx
d28b8b141c9f   redis                  "docker-entrypoint.s…"   About a minute ago   Up About a minute   6379/tcp                            alias-mock_db-1

As defined in the file, the Nginx container was given the name prod_nginx, while the other containers were named according to the standard format.

Thus, with active containers, we can access the service from any container within the network, including the container assigned the alias itself, using the service name, hostname, or alias.

To check, let’s first communicate with our database by hostname:

$ docker exec -it prod_nginx ping prod_db
PING prod_db (172.23.0.2) 56(84) bytes of data.
64 bytes from alias-mock_db-1.alias_custom_network (172.23.0.2): icmp_seq=1 ttl=64 time=0.364 ms
...

To be sure, let’s look up the name of the service:

$ docker exec -it prod_nginx ping mock_db
PING mock_db (172.23.0.2) 56(84) bytes of data.
64 bytes from alias-mock_db-1.alias_custom_network (172.23.0.2): icmp_seq=1 ttl=64 time=0.182 ms
...

We can also query our API by its alias or service name:

$ docker exec -it prod_nginx ping prod_api
PING prod_api (172.23.0.3) 56(84) bytes of data.
64 bytes from alias-mock_api-1.alias_custom_network (172.23.0.3): icmp_seq=1 ttl=64 time=0.129 ms
...

$ docker exec -it prod_nginx ping mock_api
PING mock_api (172.23.0.3) 56(84) bytes of data.
64 bytes from alias-mock_api-1.alias_custom_network (172.23.0.3): icmp_seq=1 ttl=64 time=0.085 ms
...

This example shows that containers can use hostnames, aliases, and service names interchangeably for communication within a custom Docker network, allowing us to maintain flexibility without updating upstream configurations.

6. Conclusion

In this article, we explored different methods for naming a container. We also covered how to set up a custom network with Docker Compose, including configuring the initial DNS service and assigning a hostname and alias to a service (or container).