engine: remove legacy networking from toc

[dvdksn]

Proposed changes

Related issues (optional)

[netlify]

✅ Deploy Preview for docsdocker ready!

Name	Link
🔨 Latest commit	ae9b0bd
🔍 Latest deploy log	https://app.netlify.com/sites/docsdocker/deploys/6388dce8e5710e0008a057e2
😎 Deploy Preview	https://deploy-preview-16260--docsdocker.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site settings.

[usha-mandya]

Thanks @dvdksn. Looks good. Should we also add a redirect from https://docs.docker.com/network/links/?

[thaJeztah]

We should also look if content covered on that page is already covered elsewhere. It's a bit tricky (let me try giving the 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 "old" /etc/hosts based linking 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)

[docker-robott]

Thanks for the pull request. We'd like to make our product docs better, but haven’t been able to review all the suggestions.
As our docs have also diverged, we do not have the bandwidth to review and rebase old pull requests.

If the updates are still relevant, review our contribution guidelines and rebase your pull request against the latest version of the docs, then mark it as fresh with a /remove-lifecycle stale comment.
If not, this pull request will be closed in 30 days. This helps our maintainers focus on the active pull requests.

Prevent pull requests from auto-closing with a /lifecycle frozen comment.

/lifecycle stale