path: root/devdocs/docker/engine%2Fswarm%2Fswarm-mode%2Findex.html

<h1>Run Docker Engine in swarm mode</h1>

<p>When you first install and start working with Docker Engine, swarm mode is disabled by default. When you enable swarm mode, you work with the concept of services managed through the <code class="language-plaintext highlighter-rouge">docker service</code> command.</p> <p>There are two ways to run the Engine in swarm mode:</p> <ul> <li>Create a new swarm, covered in this article.</li> <li>
<a href="../join-nodes/index">Join an existing swarm</a>.</li> </ul> <p>When you run the Engine in swarm mode on your local machine, you can create and test services based upon images you’ve created or other available images. In your production environment, swarm mode provides a fault-tolerant platform with cluster management features to keep your services running and available.</p> <p>These instructions assume you have installed the Docker Engine 1.12 or later on a machine to serve as a manager node in your swarm.</p> <p>If you haven’t already, read through the <a href="../key-concepts/index">swarm mode key concepts</a> and try the <a href="../swarm-tutorial/index">swarm mode tutorial</a>.</p> <h2 id="create-a-swarm">Create a swarm</h2> <p>When you run the command to create a swarm, the Docker Engine starts running in swarm mode.</p> <p>Run <a href="../../reference/commandline/swarm_init/index"><code class="language-plaintext highlighter-rouge">docker swarm init</code></a> to create a single-node swarm on the current node. The Engine sets up the swarm as follows:</p> <ul> <li>switches the current node into swarm mode.</li> <li>creates a swarm named <code class="language-plaintext highlighter-rouge">default</code>.</li> <li>designates the current node as a leader manager node for the swarm.</li> <li>names the node with the machine hostname.</li> <li>configures the manager to listen on an active network interface on port 2377.</li> <li>sets the current node to <code class="language-plaintext highlighter-rouge">Active</code> availability, meaning it can receive tasks from the scheduler.</li> <li>starts an internal distributed data store for Engines participating in the swarm to maintain a consistent view of the swarm and all services running on it.</li> <li>by default, generates a self-signed root CA for the swarm.</li> <li>by default, generates tokens for worker and manager nodes to join the swarm.</li> <li>creates an overlay network named <code class="language-plaintext highlighter-rouge">ingress</code> for publishing service ports external to the swarm.</li> <li>creates an overlay default IP addresses and subnet mask for your networks</li> </ul> <p>The output for <code class="language-plaintext highlighter-rouge">docker swarm init</code> provides the connection command to use when you join new worker nodes to the swarm:</p> <div class="highlight"><pre class="highlight" data-language="">$ docker swarm init
Swarm 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:2377

To add a manager to this swarm, run 'docker swarm join-token manager' and follow the instructions.
</pre></div> <h3 id="configuring-default-address-pools">Configuring default address pools</h3> <p>By default Docker Swarm uses a default address pool <code class="language-plaintext highlighter-rouge">10.0.0.0/8</code> for global scope (overlay) networks. Every network that does not have a subnet specified will have a subnet sequentially allocated from this pool. In some circumstances it may be desirable to use a different default IP address pool for networks.</p> <p>For example, if the default <code class="language-plaintext highlighter-rouge">10.0.0.0/8</code> 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 specify each subnet with the <code class="language-plaintext highlighter-rouge">--subnet</code> command.</p> <p>To configure custom default address pools, you must define pools at Swarm initialization using the <code class="language-plaintext highlighter-rouge">--default-addr-pool</code> 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 <code class="language-plaintext highlighter-rouge">10.0.0.0/27</code>, use the value <code class="language-plaintext highlighter-rouge">27</code>.</p> <p>Docker allocates subnet addresses from the address ranges specified by the <code class="language-plaintext highlighter-rouge">--default-addr-pool</code> option. For example, a command line option <code class="language-plaintext highlighter-rouge">--default-addr-pool 10.10.0.0/16</code> indicates that Docker will allocate subnets from that <code class="language-plaintext highlighter-rouge">/16</code> address range. If <code class="language-plaintext highlighter-rouge">--default-addr-pool-mask-len</code> were unspecified or set explicitly to 24, this would result in 256 <code class="language-plaintext highlighter-rouge">/24</code> networks of the form <code class="language-plaintext highlighter-rouge">10.10.X.0/24</code>.</p> <p>The subnet range comes from the <code class="language-plaintext highlighter-rouge">--default-addr-pool</code>, (such as <code class="language-plaintext highlighter-rouge">10.10.0.0/16</code>). The size of 16 there represents the number of networks one can create within that <code class="language-plaintext highlighter-rouge">default-addr-pool</code> range. The <code class="language-plaintext highlighter-rouge">--default-addr-pool</code> option may occur multiple times with each option providing additional addresses for docker to use for overlay subnets.</p> <p>The format of the command is:</p> <div class="highlight"><pre class="highlight" data-language="">$ docker swarm init --default-addr-pool &lt;IP range in CIDR&gt; [--default-addr-pool &lt;IP range in CIDR&gt; --default-addr-pool-mask-length &lt;CIDR value&gt;]
</pre></div> <p>To create a default IP address pool with a /16 (class B) for the 10.20.0.0 network looks like this:</p> <div class="highlight"><pre class="highlight" data-language="">$ docker swarm init --default-addr-pool 10.20.0.0/16
</pre></div> <p>To create a default IP address pool with a <code class="language-plaintext highlighter-rouge">/16</code> (class B) for the <code class="language-plaintext highlighter-rouge">10.20.0.0</code> and <code class="language-plaintext highlighter-rouge">10.30.0.0</code> networks, and to create a subnet mask of <code class="language-plaintext highlighter-rouge">/26</code> for each network looks like this:</p> <div class="highlight"><pre class="highlight" data-language="">$ docker swarm init --default-addr-pool 10.20.0.0/16 --default-addr-pool 10.30.0.0/16 --default-addr-pool-mask-length 26
</pre></div> <p>In this example, <code class="language-plaintext highlighter-rouge">docker network create -d overlay net1</code> will result in <code class="language-plaintext highlighter-rouge">10.20.0.0/26</code> as the allocated subnet for <code class="language-plaintext highlighter-rouge">net1</code>, and <code class="language-plaintext highlighter-rouge">docker network create -d overlay net2</code> will result in <code class="language-plaintext highlighter-rouge">10.20.0.64/26</code> as the allocated subnet for <code class="language-plaintext highlighter-rouge">net2</code>. This continues until all the subnets are exhausted.</p> <p>Refer to the following pages for more information:</p> <ul> <li>
<a href="https://docs.docker.com/network/overlay">Swarm networking</a> for more information about the default address pool usage</li> <li>
<code class="language-plaintext highlighter-rouge">docker swarm init</code> <a href="../../reference/commandline/swarm_init/index">CLI reference</a> for more detail on the <code class="language-plaintext highlighter-rouge">--default-addr-pool</code> flag.</li> </ul> <h3 id="configure-the-advertise-address">Configure the advertise address</h3> <p>Manager nodes use an advertise address to allow other nodes in the swarm access to the Swarmkit API and overlay networking. The other nodes on the swarm must be able to access the manager node on its advertise address.</p> <p>If you don’t specify an advertise address, Docker checks if the system has a single IP address. If so, Docker uses the IP address with the listening port <code class="language-plaintext highlighter-rouge">2377</code> by default. If the system has multiple IP addresses, you must specify the correct <code class="language-plaintext highlighter-rouge">--advertise-addr</code> to enable inter-manager communication and overlay networking:</p> <div class="highlight"><pre class="highlight" data-language="">$ docker swarm init --advertise-addr &lt;MANAGER-IP&gt;
</pre></div> <p>You must also specify the <code class="language-plaintext highlighter-rouge">--advertise-addr</code> if the address where other nodes reach the first manager node is not the same address the manager sees as its own. For instance, in a cloud setup that spans different regions, hosts have both internal addresses for access within the region and external addresses that you use for access from outside that region. In this case, specify the external address with <code class="language-plaintext highlighter-rouge">--advertise-addr</code> so that the node can propagate that information to other nodes that subsequently connect to it.</p> <p>Refer to the <code class="language-plaintext highlighter-rouge">docker swarm init</code> <a href="../../reference/commandline/swarm_init/index">CLI reference</a> for more detail on the advertise address.</p> <h3 id="view-the-join-command-or-update-a-swarm-join-token">View the join command or update a swarm join token</h3> <p>Nodes require a secret token to join the swarm. The token for worker nodes is different from the token for manager nodes. Nodes only use the join-token at the moment they join the swarm. Rotating the join token after a node has already joined a swarm does not affect the node’s swarm membership. Token rotation ensures an old token cannot be used by any new nodes attempting to join the swarm.</p> <p>To retrieve the join command including the join token for worker nodes, run:</p> <div class="highlight"><pre class="highlight" data-language="">$ docker swarm join-token worker

To add a worker to this swarm, run the following command:

    docker swarm join \
    --token SWMTKN-1-49nj1cmql0jkz5s954yi3oex3nedyz0fb0xx14ie39trti4wxv-8vxv8rssmk743ojnwacrr2e7c \
    192.168.99.100:2377

This node joined a swarm as a worker.
</pre></div> <p>To view the join command and token for manager nodes, run:</p> <div class="highlight"><pre class="highlight" data-language="">$ docker swarm join-token manager

To add a worker to this swarm, run the following command:

    docker swarm join \
    --token SWMTKN-1-59egwe8qangbzbqb3ryawxzk3jn97ifahlsrw01yar60pmkr90-bdjfnkcflhooyafetgjod97sz \
    192.168.99.100:2377
</pre></div> <p>Pass the <code class="language-plaintext highlighter-rouge">--quiet</code> flag to print only the token:</p> <div class="highlight"><pre class="highlight" data-language="">$ docker swarm join-token --quiet worker

SWMTKN-1-49nj1cmql0jkz5s954yi3oex3nedyz0fb0xx14ie39trti4wxv-8vxv8rssmk743ojnwacrr2e7c
</pre></div> <p>Be careful with the join tokens because they are the secrets necessary to join the swarm. In particular, checking a secret into version control is a bad practice because it would allow anyone with access to the application source code to add new nodes to the swarm. Manager tokens are especially sensitive because they allow a new manager node to join and gain control over the whole swarm.</p> <p>We recommend that you rotate the join tokens in the following circumstances:</p> <ul> <li>If a token was checked-in by accident into a version control system, group chat or accidentally printed to your logs.</li> <li>If you suspect a node has been compromised.</li> <li>If you wish to guarantee that no new nodes can join the swarm.</li> </ul> <p>Additionally, it is a best practice to implement a regular rotation schedule for any secret including swarm join tokens. We recommend that you rotate your tokens at least every 6 months.</p> <p>Run <code class="language-plaintext highlighter-rouge">swarm join-token --rotate</code> to invalidate the old token and generate a new token. Specify whether you want to rotate the token for <code class="language-plaintext highlighter-rouge">worker</code> or <code class="language-plaintext highlighter-rouge">manager</code> nodes:</p> <div class="highlight"><pre class="highlight" data-language="">$ docker swarm join-token  --rotate worker

To add a worker to this swarm, run the following command:

    docker swarm join \
    --token SWMTKN-1-2kscvs0zuymrsc9t0ocyy1rdns9dhaodvpl639j2bqx55uptag-ebmn5u927reawo27s3azntd44 \
    192.168.99.100:2377
</pre></div> <h2 id="learn-more">Learn more</h2> <ul> <li><a href="../join-nodes/index">Join nodes to a swarm</a></li> <li>
<code class="language-plaintext highlighter-rouge">swarm init</code> <a href="../../reference/commandline/swarm_init/index">command line reference</a>
</li> <li><a href="../swarm-tutorial/index">Swarm mode tutorial</a></li> </ul> 
<p><a href="https://docs.docker.com/search/?q=guide">guide</a>, <a href="https://docs.docker.com/search/?q=swarm%20mode">swarm mode</a>, <a href="https://docs.docker.com/search/?q=node">node</a></p>
<div class="_attribution">
  <p class="_attribution-p">
    &copy; 2019 Docker, Inc.<br>Licensed under the Apache License, Version 2.0.<br>Docker and the Docker logo are trademarks or registered trademarks of Docker, Inc. in the United States and/or other countries.<br>Docker, Inc. and other parties may also have trademark rights in other terms used herein.<br>
    <a href="https://docs.docker.com/engine/swarm/swarm-mode/" class="_attribution-link">https://docs.docker.com/engine/swarm/swarm-mode/</a>
  </p>
</div>