Skip to content
Tutorials Center
My learning

Topics

Lesson 19 of 38 ยท Networking and Overlay

The Routing Mesh and Published Ports

Learn how the Swarm ingress routing mesh exposes a service on every node, how host mode differs, and how to front it with a load balancer and keep client IPs.

Overlay networks connect services to each other. To let the outside world reach a service you publish a port. Swarm offers two ways: the routing mesh (the default) and host mode. Understanding both explains why you can browse to any node's IP and still reach your application, and why sometimes you should not.

Publishing with the routing mesh

CONSOLE
$ docker service create --name web --replicas 2 \
    --publish published=8080,target=80 nginx:1.27

The long form is explicit: target is the container's port, published the port opened on the nodes. The short form --publish 8080:80 means the same.

The result: every node in the swarm listens on port 8080, including nodes that run no web task. A connection arriving at any node is forwarded to a healthy task, wherever it runs.

flowchart LR
  U["Client"] -->|"node3:8080"| N3["Node 3 (no web task)"]
  N3 -->|"ingress overlay"| T1["web.1 on node 1"]
  N3 -.-> T2["web.2 on node 2"]

The mesh on the receiving node forwards the connection to a task over the ingress network.

How it works

  • Swarm creates a special overlay network called ingress the first time you initialize the swarm.
  • Each node has a hidden ingress sandbox where IPVS rules map "published port" to the service's VIP on ingress.
  • The first node touched does a NAT: it rewrites the destination to a task IP (via IPVS) and sends it through the overlay (VXLAN). The reply returns the same way.
  • Port 4789 UDP and 7946 must therefore be open between nodes for the mesh to work, in addition to the public published port on whichever nodes your load balancer targets.

Benefits: any node can be your entry point, a node can fail without changing clients' addresses, and external load balancers need no knowledge of task placement.

Putting a load balancer in front

In production you point an external load balancer (cloud LB, HAProxy, nginx, keepalived with a floating IP) at all nodes on the published port, with a health check on the port. Because every node forwards correctly, it does not matter which one the balancer chooses. Add TLS termination at the balancer or in a proxy service such as Traefik or Caddy (Stacks and Deployment).

Limits of ingress mode

  • Client source IP is lost. Because the first node performs source NAT, containers see the node's ingress address, not the client's. Logging and IP allow-lists inside the container break. Solutions: host mode, or put a proxy in front that adds X-Forwarded-For / uses the PROXY protocol, or terminate at an external load balancer that passes the header.
  • Extra hop. A request may cross the network to another node.
  • Port reservation. The published port is taken on every node: two services cannot publish the same port, and a host process using the port will conflict.
  • Layer 4 only. The mesh balances TCP and UDP connections; it does not understand HTTP paths or hostnames. Use a reverse-proxy service for host-based routing.
  • UDP: add protocol=udp to the publish spec: --publish published=5353,target=53,protocol=udp.

Host mode

CONSOLE
$ docker service create --name edge --mode global \
    --publish published=80,target=80,mode=host \
    nginx:1.27

In host mode the port is opened only on the node that runs the task, directly, with no mesh. Clients see the true source IP, and there is no extra hop. The costs:

  • Only nodes running a task answer; you must know where tasks are (combine with --mode global or constraints so one task runs on each entry node).
  • You cannot run two tasks of the service on the same node (port clash). Use --replicas-max-per-node 1.
  • Rolling updates may briefly leave a node without a listener.

It is the standard setup for edge proxies that must see client IPs, and the only way to publish ports for dnsrr services.

Choosing

Need Choose
Reach the service from any node, simple Ingress (default)
Real client IP Host mode (or proxy headers)
Avoid the extra hop for latency-sensitive traffic Host mode
dnsrr endpoint mode Host mode
HTTP routing by host or path A reverse-proxy service (published on ingress or host)

Changing and inspecting ports

CONSOLE
$ docker service update --publish-add published=8443,target=443 web
$ docker service update --publish-rm 8080 web
$ docker service inspect --format '{{json .Endpoint.Ports}}' web

Stand-in: routing mesh forwarding

The simulation below accepts requests on any node, forwards them to a task and counts hops, comparing ingress with host mode. The IP rewriting is illustrated by printing what the container would see.

Python Stand-in: ingress versus host mode

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Stand-in: port conflicts

Published ingress ports are reserved on every node. This check shows how two services collide and how host mode changes the rule.

Python Stand-in: port reservation

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Check your understanding

Quick check ยท 3 questions

of 3 answered You scored / 3 ยท perfect!

  1. 1. A service publishes port 8080 in ingress mode and runs on node 1 only. You connect to node 3 on port 8080. What happens?

    The routing mesh listens on every node and forwards to a healthy task.
  2. 2. Why might your application log wrong client IP addresses behind the routing mesh?

    Ingress mode rewrites the source, so use host mode or forward headers from a proxy or load balancer.
  3. 3. Which publish option opens the port only on the nodes running the task?

    mode=host bypasses the mesh and binds the port on the node directly.

Summary

  • The routing mesh opens a published port on every node and forwards to a healthy task over the ingress network.
  • It is layer 4 only and hides client IPs; host mode keeps them and avoids the hop.
  • Front the nodes with an external load balancer and a reverse proxy for HTTP routing.
  • Published ports are reserved cluster-wide in ingress mode.

Next: Network Troubleshooting and Tuning