Attaching a docker container to another container's network with --net=container:containerName key

Question

I'm reading the book "Docker and Kubernetes for Java Developers" by Jaroslaw Krochmalski, and I've stumbled upon the following example. The author proposes to create a bridged myNetwork network and then run two containers (Apache Tomcat and BusyBox) attached to this network, as follows (the commands should be run in separate terminal sessions):

$ docker run -it --name myTomcat --net=myNetwork tomcat
$ docker run -it --net container:myTomcat busybox

The author specificaly says that "we want our busybox container to use the same network as Tomcat uses. As an alternative, we could of course go with specifying a network name explicitly, using the --net myNetwork option".

Then the author proposes to check the communication between the containers by running the following command in the busybox container:

$ wget localhost:8080

This indeed worked, but immediately confused me, since we have two different containers, and it's not clear why do they communicate via localhost. Turns out, the above mentioned command with a --net container:myTomcat key doesn't exactly add the container to the network, but makes it somehow visible under the same IP as the myTomcat container.

This is confirmed by the observation that if you run docker network inspect myNetwork, you will see that there's actually only one container attached to the network:

[
    {
        "Name": "myNetwork",
        ...
        "Containers": {
            "464ed70a0c31784226dc943bcbcb79f7c4666b9d7825183706505731ac06a9bf": {
                "Name": "myTomcat",
                "EndpointID": "a4c384f17c6f8e443a430f130093ff6936bb59b1b54d0f056d1f0b4c703c1489",
                "MacAddress": "02:42:ac:14:00:02",
                "IPv4Address": "172.20.0.2/16",
                "IPv6Address": ""
            }
        },
        ...
    }
]

On the contrary, if you run the busybox container as follows:

$ docker run -it --net=myNetwork busybox

the visibility through localhost won't work, but the docker network inspect myNetwork will show both containers attached to the network under different IPs:

[
    {
        "Name": "myNetwork",
        ...
        "Containers": {
            "41c607b78af36cf6512124b6c057ed31997ddd6067a99ae579fe25b53753178e": {
                "Name": "vigorous_clarke",
                "EndpointID": "9bf6d6a294d885febcfe7f38e388f68af3f8bc7c0334c1dcea13512c3ead23d5",
                "MacAddress": "02:42:ac:14:00:03",
                "IPv4Address": "172.20.0.3/16",
                "IPv6Address": ""
            },
            "464ed70a0c31784226dc943bcbcb79f7c4666b9d7825183706505731ac06a9bf": {
                "Name": "myTomcat",
                "EndpointID": "a4c384f17c6f8e443a430f130093ff6936bb59b1b54d0f056d1f0b4c703c1489",
                "MacAddress": "02:42:ac:14:00:02",
                "IPv4Address": "172.20.0.2/16",
                "IPv6Address": ""
            }
        },
        ...
    }
]

So it looks like, contrary to the author's statement, --net=container:myTomcat and --net=myNetwork keys have completely different meanings. The problem is I couldn't find any documentation on the --net=container:containerName notation, so I'm not sure what exactly does it mean or how does it work. Does anyone have any insight on this?

Answer 1

The --network=container:containerName has the following meaning, according to the documentation:

With the network set to container a container will share the network stack of another container. [...] Example running a Redis container with Redis binding to localhost then running the redis-cli command and connecting to the Redis server over the localhost interface.

$ docker run -d --name redis example/redis --bind 127.0.0.1
$ # use the redis container's network stack to access localhost
$ docker run --rm -it --network container:redis example/redis-cli -h 127.0.0.1

This is the reason the busybox container can access the tomcat application via http://localhost:8080 in the book example.

Thanks to @tgogos for pointing me in the right direction.