7.1.2.5 Service Network Aliases
A focused guide to Service Network Aliases, connecting core concepts with practical Docker and container operations.
Service network aliases are additional names a container can be reached by on a given network, beyond its own container name, useful for providing a more generic or role-based name that other containers can rely on independently of a specific container's actual name.
Assigning a Network Alias
An alias is specified when a container connects to a network, providing an additional resolvable name alongside the container's own name.
docker network create app-network
docker run -d --name postgres-primary --network app-network --network-alias db postgres:16
Other containers on app-network can now reach this container either by its actual name (postgres-primary) or by its alias (db).
docker exec api ping db
docker exec api ping postgres-primary
Both of these succeed, resolving to the same container through two different names.
Why Aliases Provide Useful Indirection
An alias lets dependent containers reference a service by its functional role (db, cache) rather than a specific container's actual name, which can be valuable if the underlying container is later replaced by a differently named one serving the same role.
docker run -d --name postgres-v2 --network app-network --network-alias db postgres:16
Dependent containers configured to reach db continue working correctly even though the actual underlying container's name has changed.
Using Aliases for Multiple Containers Sharing a Role
Multiple containers can share the same network alias, useful for basic load distribution scenarios where Docker's embedded DNS returns multiple addresses for the shared alias.
docker run -d --name worker-1 --network app-network --network-alias worker worker-image:1.0
docker run -d --name worker-2 --network app-network --network-alias worker worker-image:1.0
Why Service Network Aliases Matter
Network aliases provide a useful layer of indirection between a service's functional role and the specific container currently fulfilling that role, supporting more flexible, resilient service configuration than relying purely on fixed container names.