Overlay networks and the routing mesh

Overlay networks span every node of the swarm. Each service gets a virtual IP that balances over its healthy tasks, and a published port answers on every node and forwards to a task wherever it runs.

How it works

A stack creates its networks with the overlay driver (shop_default). Inside them, a service's name (api, or shop_api) resolves to its virtual IP; tasks.api resolves to the IP of each task. ports: publishes in ingress mode by default: the routing mesh listens on every node, so a load balancer in front can target all of them.

What breaks

A task joins the virtual IP as soon as it is Running. Without a healthcheck, Running means the container started, not that the app listens: requests reach it during its warm-up and fail. A container started with docker run cannot join a stack's network unless that network is attachable.

In compose.yaml

networks:
  backend:
    driver: overlay
    attachable: true

services:
  api:
    image: registry.shop.internal/shop/api:2.3
    networks: [backend]
    ports:
      - "80:3000"

See it break, then fix it

Write the Dockerfile or the compose file, type the docker commands, and watch a simulated server run them through reboots, upgrades and traffic. Free to start.

Open the learning path Open the sandbox