What did Docker's legacy `docker run --link` flag do between two containers, and what replaced it?

## The problem --link was invented for On Docker's default bridge there is no name resolution between containers. A container gets an address from the bridge's subnet when it starts, and that address can be different next time. Before user-defined networks existed, the only way to give one container a stable handle on another was `--link`, and every tutorial written in that era uses it. ## What the flag actually did The syntax is `docker run --link <source-container>:<alias>`, given when the **recipient** container is created. Docker then did two things to the recipient: **An /etc/hosts entry.** The alias (and the source container's name) were written into the recipient's `/etc/hosts`, pointing at the source's current address, so `getent hosts db` or a connection to `db:5432` worked. Docker maintained that entry: if the source container restarted with a new address, the linked container's hosts file was updated. **Environment variables.** For each port the source container exposed, the recipient received a set of variables built from the alias in upper case — for a Postgres source linked as `db` you would see `DB_PORT=tcp://172.17.0.3:5432`, `DB_PORT_5432_TCP_ADDR`, `DB_PORT_5432_TCP_PORT`, `DB_PORT_5432_TCP_PROTO` and `DB_NAME`. On top of that, every environment variable set on the source container was copied in as `DB_ENV_<NAME>`. That is the part interviewers like, because `DB_ENV_POSTGRES_PASSWORD` means the source's credentials are now sitting in the environment of a container that may have no business seeing them, visible to anything that can read `/proc/self/environ` or run `docker inspect`. Those variables were fixed when the recipient started. If the source restarted and took a new address, the hosts entry was corrected but the variables kept the stale one — a classic source of "it works until the database is restarted" bugs in an application that read `DB_PORT_5432_TCP_ADDR` instead of the hostname. ## The structural problems * **One-directional.** Linking a worker to a database gives the worker a handle on the database, not the reverse. * **Create-time only.** A link cannot be added to a running container, and cannot be removed without recreating it. * **Start order.** The source must already exist when the recipient is created, so a stack has a hand-maintained dependency graph. * **Default bridge only, in the sense that mattered.** It solved a problem that only exists there. ## What replaced it Create a network and attach both containers. Docker's embedded resolver answers for container names and for any `--network-alias`, resolution is current rather than baked in at start, it works in both directions, containers can be attached and detached later, and nothing is copied between environments: ``` docker network create digest-net docker run -d --name digest-db --network digest-net -e POSTGRES_PASSWORD=secret postgres:16 docker run -d --name digest-worker --network digest-net digest:1.4 # connects to digest-db:5432 ``` ## The subtlety worth knowing `--link` is still accepted by the CLI, and it behaves differently depending on where you use it. On the default bridge it does the legacy thing described above. On a **user-defined** network it does not inject environment variables at all; it simply gives the source container an extra network-scoped alias inside that network, so `--link digest-db:db` means "also let me call it `db` here". That is the only piece of `--link` that has a modern use, and even then a `--network-alias` on the source is the clearer way to express it. ## How to answer when asked Say what it did (hosts entry plus environment variables), name the environment-variable leak as the reason nobody should reintroduce it, name the structural limits (one-directional, create-time, start order), and say the replacement is a user-defined network with name resolution. If you are shown a legacy script full of `--link`, the migration is mechanical: create one network, add `--network` to every `docker run`, delete the `--link` flags, and replace any application code that reads `*_PORT_*_TCP_ADDR` with the peer's name. ## Why it still comes up Because old documentation and old CI scripts are full of it, and because the environment-variable behaviour is a neat illustration of why implicit configuration sharing between containers is a bad idea. Nobody is marked down for not remembering the exact variable names; being unable to say what replaced it, or claiming it is the current way to connect containers, is a different matter.