Difference between --link and --alias in overlay docker network?

Question

I am reading this official Docker 0.10.3 documentation (at this time, it is still in a branch) and it says:

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

Does network alias from one container actually is a link from the second container in the same network?

Answer 1

There are two differences between --net-alias and --link:

1. With --net-alias, one container can access the other container only if they are on the same network. In other words, in addition to --net-alias foo and --net-alias bar, you need to start both containers with --net foobar_net after creating the network with docker network create foobar_net.
2. With --net-alias foo, all containers in the same network can reach the container by using its alias foo. With --link, only the linked container can reach the container by using the name foo.

Historically, --link was created before libnetwork and all network-related features. Before libnetwork, all containers ran in the same network bridge, and --link only added names to /etc/hosts. Then, custom networks were added and the behavior of --link in user-defined networks was changed.

See also Legacy container links for more information on --link.