Links are deprecated

[amouat]

The documentation tells users to use --link to connect applications to the mysql container, but this is unnecessary and deprecated: https://docs.docker.com/network/links/

[tianon]

https://github.com/docker-library/faq/blob/master/README.md#--link-is-deprecated

[amouat]

Ok, thanks and apologies for not spotting that before.

Feel free to close, but I do feel this is pretty misleading for new users (who shouldn't be pushed towards links).

[amouat]

Wait, I'm missing something. Why would you need to explain --network? By default they'll be in the same network and able to communicate, right? There will need to some more work to get the port number, but I guess you could use docker port.

I think using links actually adds more complexity for the user, as now they have another concept to look up, only to find it's "legacy" and wonder why it was used here.

I can come up with an alternative as a PR if you would consider changing.

[thaJeztah]

I (personally) don't think it should recommend using --link, but use a custom network instead.

Note that --link itself is not deprecated, but (yes, it's confusing) uses a different implementation when using a custom network.

On the default (bridge) network, links are actual "links" between containers. They have a lot of limitations (eg it's not possible to replace a linked container, as it's hard-wired to the actual container, so to re-establish a link, both containers have to be recreated), they also leak environment variables to any linked container, which may not always be desirable.

I actually proposed to replace the old (hard-wired) links, and use the same approach for both the default bridge network as for custom networks, and use the embedded DNS for all cases; moby/moby#22295, but that needs further discussion (should all behaviours of the old links stay in place, including the environment-variables?)

[amouat]

Just wanted to say thanks for this @yosifkit ; I think it was worth the work.