Enable Swarm Network Auto-Discovery

Early Access

Swarm network auto-discovery is currently in early access. Available starting v3.21.0-ea.3.

By default, the Traefik Hub gateway Swarm service must be manually attached to every overlay network that contains services it should route to. Each new service on a separate network requires a network attachment and a gateway re-deploy.

The Swarm network auto-discovery side service removes that manual step. It watches Docker Swarm services for the traefik.swarm.network label, computes the set of overlay networks the gateway needs, and keeps the gateway service attached to that set automatically. New services become reachable without any gateway restart.

Mirantis Kubernetes Engine (MKE) / UCP

This also works against Docker Swarm exposed through Mirantis Kubernetes Engine (formerly UCP): the side service only calls standard Docker API endpoints (ServiceList/Inspect/Update, NetworkList, Events), which MKE exposes the same way a stock Swarm daemon does. Grant the side service's credentials MKE RBAC access to the gateway service and the overlay networks it needs to attach to.

Before You Begin

Ensure the following are in place before you start:

Docker Swarm mode is enabled on your cluster.
The Traefik Hub gateway is deployed as a Swarm service (not a standalone container).
The ghcr.io/traefik/traefik-hub image (v3.21.0-ea.3 or later) is available. It includes the swarm-network-autodiscovery subcommand.
The host running the side service can reach the Docker socket (/var/run/docker.sock or a remote TCP endpoint).

Step 1: Verify the gateway service label

The side service identifies the Hub gateway by matching a label on the Swarm service. The default label is io.traefik.hub.component=gateway.

Inspect the running gateway service:

docker service inspect traefik-hub --format '{{ json .Spec.Labels }}'

Confirm that io.traefik.hub.component=gateway appears in the output. If your gateway uses a different label, record the exact key=value pair. You will pass it to the side service as --swarm.gatewayLabel.

The gateway service's label set does not change between this step and the side service start-up.

Step 2: Label user services

For each Swarm service that the gateway should route to, add the following label:

Label	Value	Purpose
`traefik.swarm.network`	`<overlay-network-name>`	Tells the side service which overlay network to attach the gateway to

About traefik.enable

swarm.exposedByDefault defaults to true, so the traefik.swarm.network label alone is enough. Add traefik.enable=true only if you set swarm.exposedByDefault: false. See swarm.exposedByDefault in the configuration reference.

Example: update an existing service.

docker service update \
  --label-add traefik.enable=true \
  --label-add traefik.swarm.network=my-overlay \
  my-service

Example: create a new service with both labels.

docker service create \
  --name my-service \
  --network my-overlay \
  --label traefik.enable=true \
  --label traefik.swarm.network=my-overlay \
  my-image:latest

Stack-prefixed network names

When a service is deployed as part of a Docker Stack, Docker prefixes the network name with the stack name (for example, mystack_my-overlay). The side service resolves this prefix automatically, so you can use either the bare name (my-overlay) or the full prefixed name in the label value.

After this step, the labeled services are ready to be discovered. The gateway will be attached to their networks once the side service is running.

Step 3: Deploy the auto-discovery side service

Run the traefik-hub swarm-network-autodiscovery subcommand alongside the gateway. It needs read-write access to the Docker socket so it can call ServiceUpdate on the gateway.

Deploy it as a Swarm service constrained to a manager node (required for ServiceUpdate access):

docker service create \
  --name swarm-network-autodiscovery \
  --constraint node.role==manager \
  --mount type=bind,source=/var/run/docker.sock,target=/var/run/docker.sock \
  ghcr.io/traefik/traefik-hub:latest \
  swarm-network-autodiscovery

Or as part of a Docker Stack compose file:

docker-compose.yml
services:
  swarm-network-autodiscovery:
    image: ghcr.io/traefik/traefik-hub:latest
    command:
      - swarm-network-autodiscovery
      - --swarm.endpoint=unix:///var/run/docker.sock
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    deploy:
      placement:
        constraints:
          - node.role == manager

Once running, the side service performs an immediate reconcile pass and then continues to watch Docker events. Check the readiness endpoint to confirm the first pass completed:

curl -sf http://localhost:8081/readyz && echo "ready"

The gateway service is now kept in sync with the discovered networks. Adding or removing user services with traefik.swarm.network labels updates the gateway's network attachments automatically within the resyncInterval plus any detachDebounce window.

Configuration reference

Swarm network auto-discovery accepts CLI flags, environment variables, or a YAML/TOML file. See the Swarm network auto-discovery configuration reference for the full list of fields, defaults, and a sample configuration file.

Troubleshooting

Gateway not attaching to a new network

Confirm the user service has the traefik.swarm.network=<name> label. If you set swarm.exposedByDefault: false, also confirm it has traefik.enable=true:
```
docker service inspect my-service --format '{{ json .Spec.Labels }}'
```
Confirm the network name in the label matches the actual overlay network (accounting for any stack prefix).

Check the side service logs for reconcile errors:

docker service logs swarm-network-autodiscovery

If the gateway service label does not match the default, pass the correct value via --swarm.gatewayLabel=<key>=<value>.

/readyz returns 503

The /readyz endpoint returns 503 Service Unavailable until the first reconcile pass completes successfully. If it stays at 503:

Check that the Docker socket is mounted and the side service can reach it.
Look for creating Docker client or EnsureReachable errors in the logs.
Verify the side service runs on a manager node. Worker nodes cannot call ServiceUpdate.

Gateway detaches from a network unexpectedly

The side service waits detachDebounce (default 5s) before removing a network from the gateway. If services are restarted frequently and the gateway detaches during that window, increase the debounce:

traefik-hub swarm-network-autodiscovery --swarm.detachDebounce=30s

Read the Docker installation documentation.
Read the Migrate from Traefik Proxy on Docker documentation.
See the Swarm network auto-discovery configuration reference for the full list of fields.

Before You Begin​

Step 1: Verify the gateway service label​

Step 2: Label user services​

Step 3: Deploy the auto-discovery side service​

Configuration reference​

Troubleshooting​

Related content​