7.2.4.4 Overlay Service Discovery
A focused guide to Overlay Service Discovery, connecting core concepts with practical Docker and container operations.
Overlay service discovery is the mechanism by which Swarm services on an overlay network resolve each other by name automatically, with built-in load balancing across all of a target service's currently running replicas, regardless of which specific hosts those replicas happen to be running on.
How a Service Name Resolves
A service's name resolves to a virtual IP address representing the service as a whole, with traffic to that virtual IP automatically distributed across all currently healthy replicas.
docker service create --name api --network app-overlay --replicas 5 myapi:1.0
docker exec $(docker ps -q -f name=worker) ping api
This resolves api to a virtual IP that load balances traffic across all five running replicas, rather than to any single, specific container's address.
Discovery Remains Correct as Replicas Change
As Swarm reschedules, scales, or replaces individual replicas (due to a host failure, a scaling operation, or a rolling update), service discovery continues correctly routing to whatever replicas are currently healthy, without requiring any change to how other services reference it.
docker service scale api=8
docker service update --image myapi:2.0 api
Other services continue reaching api correctly throughout these changes, since discovery operates at the stable service level rather than depending on any individual, potentially short-lived replica.
Discovering Individual Tasks When Needed
For situations specifically needing to address individual replicas rather than the load-balanced service as a whole, Swarm also provides DNS entries for individual tasks.
docker exec $(docker ps -q -f name=worker) nslookup tasks.api
This reveals the individual IP addresses of each current replica, rather than the single load-balanced virtual IP.
Why Overlay Service Discovery Matters
Reliable, automatically maintained service discovery is essential for building resilient distributed applications on Swarm, allowing services to reference each other by stable, meaningful names rather than needing to track individual, frequently changing replica addresses directly.