Run Docker Engine in swarm mode (2024)

Table of contents

When you first install and start working with Docker Engine, Swarm mode isdisabled by default. When you enable Swarm mode, you work with the concept ofservices managed through the docker service command.

There are two ways to run the engine in Swarm mode:

Create a new swarm, covered in this article.
Join an existing swarm.

When you run the engine in Swarm mode on your local machine, you can create andtest services based upon images you've created or other available images. Inyour production environment, Swarm mode provides a fault-tolerant platform withcluster management features to keep your services running and available.

These instructions assume you have installed the Docker Engine ona machine to serve as a manager node in your swarm.

If you haven't already, read through theSwarm mode key conceptsand try theSwarm mode tutorial.

When you run the command to create a swarm, Docker Engine starts running in Swarm mode.

Rundocker swarm initto create a single-node swarm on the current node. The engine sets up the swarmas follows:

Switches the current node into Swarm mode.
Creates a swarm named default.
Designates the current node as a leader manager node for the swarm.
Names the node with the machine hostname.
Configures the manager to listen on an active network interface on port `2377``.
Sets the current node to Active availability, meaning it can receive tasksfrom the scheduler.
Starts an internal distributed data store for Engines participating in theswarm to maintain a consistent view of the swarm and all services running on it.
By default, generates a self-signed root CA for the swarm.
By default, generates tokens for worker and manager nodes to join theswarm.
Creates an overlay network named ingress for publishing service portsexternal to the swarm.
Creates an overlay default IP addresses and subnet mask for your networks

The output for docker swarm init provides the connection command to use whenyou join new worker nodes to the swarm:

$ docker swarm initSwarm initialized: current node (dxn1zf6l61qsb1josjja83ngz) is now a manager.To add a worker to this swarm, run the following command: docker swarm join \ --token SWMTKN-1-49nj1cmql0jkz5s954yi3oex3nedyz0fb0xx14ie39trti4wxv-8vxv8rssmk743ojnwacrr2e7c \ 192.168.99.100:2377To add a manager to this swarm, run 'docker swarm join-token manager' and follow the instructions.

Configuring default address pools

By default Swarm mode uses a default address pool 10.0.0.0/8 for global scope (overlay) networks. Everynetwork that does not have a subnet specified will have a subnet sequentially allocated from this pool. Insome circ*mstances it may be desirable to use a different default IP address pool for networks.

For example, if the default 10.0.0.0/8 range conflicts with already allocated address space in your network,then it is desirable to ensure that networks use a different range without requiring swarm users to specifyeach subnet with the --subnet command.

To configure custom default address pools, you must define pools at swarm initialization using the--default-addr-pool command line option. This command line option uses CIDR notation for defining the subnet mask.To create the custom address pool for Swarm, you must define at least one default address pool, and an optional default address pool subnet mask. For example, for the 10.0.0.0/27, use the value 27.

Configure the advertise address

Manager nodes use an advertise address to allow other nodes in the swarm accessto the Swarmkit API and overlay networking. The other nodes on the swarm must beable to access the manager node on its advertise address.

If you don't specify an advertise address, Docker checks if the system has asingle IP address. If so, Docker uses the IP address with the listening port2377 by default. If the system has multiple IP addresses, you must specify thecorrect --advertise-addr to enable inter-manager communication and overlaynetworking:

$ docker swarm init --advertise-addr <MANAGER-IP>

You must also specify the --advertise-addr if the address where other nodesreach the first manager node is not the same address the manager sees as itsown. For instance, in a cloud setup that spans different regions, hosts haveboth internal addresses for access within the region and external addresses thatyou use for access from outside that region. In this case, specify the externaladdress with --advertise-addr so that the node can propagate that informationto other nodes that subsequently connect to it.

Refer to the docker swarm initCLI referencefor more detail on the advertise address.

View the join command or update a swarm join token

Nodes require a secret token to join the swarm. The token for worker nodes isdifferent from the token for manager nodes. Nodes only use the join-token at themoment they join the swarm. Rotating the join token after a node has alreadyjoined a swarm does not affect the node's swarm membership. Token rotationensures an old token cannot be used by any new nodes attempting to join theswarm.

To retrieve the join command including the join token for worker nodes, run:

$ docker swarm join-token workerTo add a worker to this swarm, run the following command: docker swarm join \ --token SWMTKN-1-49nj1cmql0jkz5s954yi3oex3nedyz0fb0xx14ie39trti4wxv-8vxv8rssmk743ojnwacrr2e7c \ 192.168.99.100:2377This node joined a swarm as a worker.

To view the join command and token for manager nodes, run:

$ docker swarm join-token managerTo add a manager to this swarm, run the following command: docker swarm join \ --token SWMTKN-1-59egwe8qangbzbqb3ryawxzk3jn97ifahlsrw01yar60pmkr90-bdjfnkcflhooyafetgjod97sz \ 192.168.99.100:2377

Pass the --quiet flag to print only the token:

$ docker swarm join-token --quiet workerSWMTKN-1-49nj1cmql0jkz5s954yi3oex3nedyz0fb0xx14ie39trti4wxv-8vxv8rssmk743ojnwacrr2e7c

Be careful with the join tokens because they are the secrets necessary to jointhe swarm. In particular, checking a secret into version control is a badpractice because it would allow anyone with access to the application sourcecode to add new nodes to the swarm. Manager tokens are especially sensitivebecause they allow a new manager node to join and gain control over the wholeswarm.

We recommend that you rotate the join tokens in the following circ*mstances:

If a token was checked-in by accident into a version control system, groupchat or accidentally printed to your logs.
If you suspect a node has been compromised.
If you wish to guarantee that no new nodes can join the swarm.

Additionally, it is a best practice to implement a regular rotation schedule forany secret including swarm join tokens. We recommend that you rotate your tokensat least every 6 months.

Run swarm join-token --rotate to invalidate the old token and generate a newtoken. Specify whether you want to rotate the token for worker or managernodes:

$ docker swarm join-token --rotate workerTo add a worker to this swarm, run the following command: docker swarm join \ --token SWMTKN-1-2kscvs0zuymrsc9t0ocyy1rdns9dhaodvpl639j2bqx55uptag-ebmn5u927reawo27s3azntd44 \ 192.168.99.100:2377

Learn more

Join nodes to a swarm
swarm initcommand line reference
Swarm mode tutorial