What does it mean that `docker run --network=container:CONTAINERID`?

Question

I know that when running a container, I could set the --network argument whose value could be any from the results of docker network ls.
However, I have seen that some run containers like this:

$ docker run --network=container:CONTAINERID IMAGE

I have searched this usage but got no docs to explain it.

I have done some experiments and find that the container using another container's network shares the same network stack and it seems that the two containers are on the same host and they could call each other using localhost.

So when running a container by setting --network=container:CONTAINERID, does it mean that the two containers share the same network stack?

Answer 1

Exactly what you thought, the new container is given the same network namespace as CONTAINERID. So yes, same network stack. As you identified, this means that containers can contact each other via localhost, it also means that you need to be careful with port mappings, as each container will need a unique port within the namespace.

It is documented in the docker run reference here.

--network="bridge" : Connect a container to a network
                      'bridge': create a network stack on the default 
                         Docker bridge
                      'none': no networking
          # ----->    'container:<name|id>': reuse another container's 
                         network stack
                      'host': use the Docker host network stack
                      '<network-name>|<network-id>': connect to a 
                         user-defined network