This issue is based on a comment by @thaJeztah

We should look if content covered on the Legacy container links page can be pruned or improved, and review to see whether it covers the non-legacy implementation of --link.

TL;DR:

• this topic is still relevant / used when using the default (bridge) network; the page containers various topics, some of them more relevant than others;
  • for example, there's a description about port-mapping ("Connect using network port mapping"), which is definitely a relevant topic, and not directly related to "links". We should look if we have that topic covered in-depth elsewhere.
• the --link option on the default (bridge) network is implemented as a "hard-wired" link in one direction (source_container:target_container), this implementation is known to be problematic;
  • environment variables are shared between the linked containers (meant to be a "feature" for discovery and configuration, but also huge information leak (e.g. credentials can leak to other containers))
  • as the link is hard-wired, restarting a container / replacing it breaks the link (with no option to re-establish)
  • DNS resolution to linked containers is done through /etc/hosts, which is brittle
• This functionality was kept for the bridge network for backward-compatibility, but for reasons above, I proposed to break backward-compatibility, and use the new implementation (see below); Proposal: deprecate legacy /etc/hosts based --link and always use embedded DNS moby/moby#22295 . This has not yet been decided on / worked on, so consider that "ongoing work".

However (this is the more tricky part); there's a new implementation of --link (note here: it's using the same --link flag); this implementation is NOT legacy, and thus relevant.

• We should check if we have proper documentation for that
• The new implementation:
  • is (currently) only used when using custom networks (so not the default bridge network)
  • --> When using docker compose, compose always uses custom networks, so when using links: in a compose file, the new (non-legacy) implementation is used
  • does not use a hard-wired link (so no issue when restarting / replacing containers), and does not share environment variables (so no information leak)
  • uses an embedded DNS for resolution of the linked container; setting --link is creating a container+network-scoped DNS entry in the embedded DNS server.
  • uses the network sandboxes to control access (only containers on the same network can communicate)

So we need to somehow capture that (what the functionality of --link is, and that it's not deprecated / legacy on custom networks)

Related:

• docs/deprecated: legacy links env vars cli#6263