beenull/moby
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Merge pull request #24207 from sfsmithcha/add_swarm_mode_guide

Browse source 
add run swarm mode guide
This commit is contained in:
Sebastiaan van Stijn 2016-07-25 19:21:01 +02:00 committed by GitHub
commit caedb3f827
2 changed files with 261 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

131
docs/swarm/join-nodes.md Normal file
View file

@ -0,0 +1,131 @@
<!--[metadata]>
+++
title = "Join nodes to a swarm"
description = "Add worker and manager nodes to a swarm"
keywords = ["guide, swarm mode, node"]
advisory = "rc"
[menu.main]
identifier="join-nodes-guide"
parent="engine_swarm"
weight=13
+++
<![end-metadata]-->
# Join nodes to a swarm
When you first create a swarm, you place a single Docker Engine (Engine) into
swarm mode. To take full advantage of swarm mode you can add nodes to the swarm:
* Adding worker nodes increases capacity. When you deploy a service to a swarm,
the Engine schedules tasks on available nodes whether they are worker nodes or
manager nodes. When you add workers to your swarm, you increase the scale of
the swarm to handle tasks without affecting the manager raft consenus.
* Manager nodes increase fault-tolerance. Manager nodes perform the
orchestration and cluster management functions for the swarm. Among manager
nodes, a single leader node conducts orchestration tasks. If a leader node
goes down, the remaining manager nodes elect a new leader and resume
orchestration and maintenance of the swarm state. By default, manager nodes
also run tasks.
Before you add nodes to a swarm you must install Docker Engine 1.12 or later on
the host machine.
## Join as a worker node
To retrieve the join command including the join token for worker nodes, run the
following command on a manager node:
```bash
$ 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
```
Run the command from the output on the worker to join the swarm:
```bash
$ docker swarm join \
--token SWMTKN-1-49nj1cmql0jkz5s954yi3oex3nedyz0fb0xx14ie39trti4wxv-8vxv8rssmk743ojnwacrr2e7c \
192.168.99.100:2377
This node joined a swarm as a worker.
```
The `docker swarm join` command does the following:
* switches the Docker Engine on the current node into swarm mode.
* requests a TLS certificate from the manager.
* names the node with the machine hostname
* joins the current node to the swarm at the manager listen address based upon the swarm token.
* sets the current node to `Active` availability, meaning it can receive tasks
from the scheduler.
* extends the `ingress` overlay network to the current node.
### Join as a manager node
When you run `docker swarm join` and pass the manager token, the Docker Engine
switches into swarm mode the same as for workers. Manager nodes also participate
in the raft consensus. The new nodes should be `Reachable`, but the existing
manager will remain the swarm `Leader`.
Docker recommends three or five manager nodes per cluster to implement high
availability. Because swarm mode manager nodes share data using Raft, there
must be an odd number of managers. The swarm can continue to function after as
long as a quorum of more than half of the manager nodes are available.
For more detail about swarm managers and administering a swarm cluster, see
[Administer and maintain a swarm of Docker Engines](admin_guide.md).
To retrieve the join command including the join token for manager nodes, run the
following command on a manager node:
```bash
$ docker swarm join-token manager
To add a manager to this swarm, run the following command:
docker swarm join \
--token SWMTKN-1-61ztec5kyafptydic6jfc1i33t37flcl4nuipzcusor96k7kby-5vy9t8u35tuqm7vh67lrz9xp6 \
192.168.99.100:2377
```
Run the command from the output on the manager to join the swarm:
```bash
$ docker swarm join \
--token SWMTKN-1-61ztec5kyafptydic6jfc1i33t37flcl4nuipzcusor96k7kby-5vy9t8u35tuqm7vh67lrz9xp6 \
192.168.99.100:2377
This node joined a swarm as a manager.
```
<!--TODO WIP
Manager nodes use the listen address for cluster management communications. The
other nodes on the swarm must be able to access the manager node on the
IP address and port you specify for the listen address.
Especially when there are multiple active network interfaces, you should
you explicitly define the listen address when you add a manager node to the a
swarm:
```bash
docker swarm join \
--token <MANAGER-TOKEN> \
--listen-addr <NODE-IP>:<PORT> \
<MANAGER-IP>:<PORT>
```
this will change for https://github.com/docker/docker/pull/24237 ->>
Replace <NODE-IP> with the IP address of the node that is joining the swarm.
Replace <MANAGER-IP> with the address of the swarm manager.
Only manager nodes use the listen address. If you specify `--listen-addr` for a
worker node, the node only uses the listen address if it is promoted to a
manager.
-->
## Learn More
* `swarm join`[command line reference](../reference/commandline/swarm_join.md)
* [Swarm mode tutorial](swarm-tutorial/index.md)

130
docs/swarm/swarm-mode.md Normal file
View file

@ -0,0 +1,130 @@
<!--[metadata]>
+++
title = "Run Docker Engine in swarm mode"
description = "Run Docker Engine in swarm mode"
keywords = ["guide, swarm mode, node"]
advisory = "rc"
[menu.main]
identifier="initialize-swarm-guide"
parent="engine_swarm"
weight=12
+++
<![end-metadata]-->
# Run Docker Engine in swarm mode
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 `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](join-nodes.md).
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.
These instructions assume you have installed the Docker Engine 1.12 or later on
a machine to serve as a manager node in your swawrm.
If you haven't already, read through the [swarm mode key concepts](key-concepts.md)
and try the [swarm mode tutorial](swarm-tutorial/index.md).
## Create a swarm
When you run the command to create a swarm, the Docker Engine starts running in swarm mode.
Run [`docker swarm init`](/engine/reference/commandline/swarm_init.md)]
to create a single-node swarm on the current node. The Engine sets up the swarm
as 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, meanining it can receive tasks
from the scheduler.
* 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.
* by default, generates a self-signed root CA for the swarm.
* by default, generates tokens for worker and manager nodes to join the
swarm.
* creates an overlay network named `ingress` for publishing service ports
external to the swarm.
The output for `docker swarm init` provides the connection command to use when
you join new worker or manager nodes to the swarm:
```bash
$ 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 the following command:
docker swarm join \
--token SWMTKN-1-61ztec5kyafptydic6jfc1i33t37flcl4nuipzcusor96k7kby-5vy9t8u35tuqm7vh67lrz9xp6 \
192.168.99.100:2377
```
### View the join command or update a swarm join token
The manager node requires a secret token for a new node to join the swarm. The
token for worker nodes is different from the token for manager nodes.
To retrieve the join command including the join token for worker nodes, run:
```bash
$ 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.
```
To view the join command and token for manager nodes, run:
```bash
$ docker swarm join-token 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
```
Pass the `--quiet` flag to print only the token:
```bash
$ docker swarm join-token --quiet worker
SWMTKN-1-49nj1cmql0jkz5s954yi3oex3nedyz0fb0xx14ie39trti4wxv-8vxv8rssmk743ojnwacrr2e7c
```
Pass the `--rotate` for `swarm join-token` to the token for a worker or manager
nodes:
```
$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 \
172.17.0.2:2377
```
## Learn More
* [Join nodes to a swarm](join-nodes.md)
* `swarm init`[command line reference](../reference/commandline/swarm_init.md)
* [Swarm mode tutorial](swarm-tutorial/index.md)