1. docker
  2. Commit ea4fef2d875de39044ca7570c35365b75086e8a5
Browse code

add tutorial

Signed-off-by: Charles Smith <charles.smith@docker.com>

Charles Smith authored on 2016/06/08 09:08:36
Showing 13 changed files
docs/swarm/index.md
History View file @ ea4fef2
1 1 
new file mode 100644
... ... 
@@ -0,0 +1,79 @@
0 
+<!--[metadata]>
1 
+title = "Swarm overview"
2 
+description = "Docker Swarm overview"
3 
+keywords = ["docker, container, cluster, swarm"]
4 
+[menu.main]
5 
+identifier="swarm_overview"
6 
+parent="engine_swarm"
7 
+weight="1"
8 
+advisory = "rc"
9 
+<![end-metadata]-->
10 
+# Docker Swarm overview
11 
+
12 
+To use this version of Swarm, install the Docker Engine `v1.12.0-rc1` or later
13 
+from the [Docker releases GitHub
14 
+repository](https://github.com/docker/docker/releases). Alternatively, install
15 
+the latest Docker for Mac or Docker for Windows Beta.
16 
+
17 
+Docker Engine 1.12 includes Docker Swarm for natively managing a cluster of
18 
+Docker Engines called a Swarm. Use the Docker CLI to create a Swarm, deploy
19 
+application services to the Swarm, and manage the Swarm behavior.
20 
+
21 
+
22 
+If you’re using a Docker version prior to `v1.12.0-rc1`, see [Docker
23 
+Swarm](https://docs.docker.com/swarm).
24 
+
25 
+## Feature highlights
26 
+
27 
+* **Cluster management integrated with Docker Engine:** Use the Docker Engine
28 
+CLI to create a Swarm of Docker Engines where you can deploy application
29 
+services. You don't need additional orchestration software to create or manage
30 
+a Swarm.
31 
+
32 
+* **Decentralized design:** Instead of handling differentiation between node
33 
+roles at deployment time, Swarm handles any specialization at runtime. You can
34 
+deploy both kinds of nodes, managers and workers, using the Docker Engine.
35 
+This means you can build an entire Swarm from a single disk image.
36 
+
37 
+* **Declarative service model:** Swarm uses a declarative syntax to let you
38 
+define the desired state of the various services in your application stack.
39 
+For example, you might describe an application comprised of a web front end
40 
+service with message queueing services and a database backend.
41 
+
42 
+* **Desired state reconciliation:** Swarm constantly monitors the cluster state
43 
+and reconciles any differences between the actual state your expressed desired
44 
+state.
45 
+
46 
+* **Multi-host networking:** You can specify an overlay network for your
47 
+application. Swarm automatically assigns addresses to the containers on the
48 
+overlay network when it initializes or updates the application.
49 
+
50 
+* **Service discovery:** Swarm assigns each service a unique DNS name and load
51 
+balances running containers. Each Swarm has an internal DNS server that can
52 
+query every container in the cluster using DNS.
53 
+
54 
+* **Load balancing:** Using Swarm, you can expose the ports for services to an
55 
+external load balancer. Internally, Swarm lets you specify how to distribute
56 
+service containers between nodes.
57 
+
58 
+* **Secure by default:** Each node in the Swarm enforces TLS mutual
59 
+authentication and encryption to secure communications between itself and all
60 
+other nodes. You have the option to use self-signed root certificates or
61 
+certificates from a custom root CA.
62 
+
63 
+* **Scaling:** For each service, you can declare the number of instances you
64 
+want to run. When you scale up or down, Swarm automatically adapts by adding
65 
+or removing instances of the service to maintain the desired state.
66 
+
67 
+* **Rolling updates:** At rollout time you can apply service updates to nodes
68 
+incrementally. Swarm lets you control the delay between service deployment to
69 
+different sets of nodes. If anything goes wrong, you can roll-back an instance
70 
+of a service.
71 
+
72 
+## What's next?
73 
+* Learn Swarm [key concepts](key-concepts.md).
74 
+* Get started with the [Swarm tutorial](swarm-tutorial/index.md).
75 
+
76 
+<p style="margin-bottom:300px">&nbsp;</p>
docs/swarm/key-concepts.md
History View file @ ea4fef2
0 77 
new file mode 100644
... ... 
@@ -0,0 +1,85 @@
0 
+<!--[metadata]>
1 
+title = "Swarm key concepts"
2 
+description = "Introducing key concepts for Docker Swarm"
3 
+keywords = ["docker, container, cluster, swarm"]
4 
+[menu.main]
5 
+identifier="swarm-concepts"
6 
+parent="engine_swarm"
7 
+weight="2"
8 
+advisory = "rc"
9 
+<![end-metadata]-->
10 
+# Docker Swarm key concepts
11 
+
12 
+Building upon the core features of Docker Engine, Docker Swarm enables you to
13 
+create a Swarm of Docker Engines and orchestrate services to run in the Swarm.
14 
+This topic describes key concepts to help you begin using Docker Swarm.
15 
+
16 
+## Swarm
17 
+
18 
+**Docker Swarm** is the name for the cluster management and orchestration features
19 
+embedded in the Docker Engine.
20 
+
21 
+A **Swarm** is a cluster of Docker Engines where you deploy a set of application
22 
+services. When you deploy an application to a Swarm, you specify the desired
23 
+state of the services, such as which services to run and how many instances of
24 
+those services. The Swarm takes care of all orchestration duties required to
25 
+keep the services running in the desired state.
26 
+
27 
+## Node
28 
+
29 
+A **node** is an active instance of the Docker Engine in the Swarm.
30 
+
31 
+When you deploy your application to a Swarm, **manager nodes** accept the
32 
+service definition that describes the Swarm's desired state. Manager nodes also
33 
+perform the orchestration and cluster management functions required to maintain
34 
+the desired state of the Swarm. For example, when a manager node receives notice
35 
+to deploy a web server, it dispatches the service tasks to worker nodes.
36 
+
37 
+By default the Docker Engine starts one manager node for a Swarm, but as you
38 
+scale you can add more managers to make the cluster more fault-tolerant. If you
39 
+require high availability Swarm management, Docker recommends three or five
40 
+Managers in your cluster.
41 
+
42 
+Because Swarm manager nodes share data using Raft, there must be an odd number
43 
+of managers. The Swarm cluster can continue functioning in the face of up to
44 
+`N/2` failures where `N` is the number of manager nodes.  More than five
45 
+managers is likely to degrade cluster performance and is not recommended.
46 
+
47 
+**Worker nodes** receive and execute tasks dispatched from manager nodes. By
48 
+default manager nodes are also worker nodes, but you can configure managers to
49 
+be manager-only nodes.
50 
+
51 
+## Services and tasks
52 
+
53 
+A **service** is the definition of how to run the various tasks that make up
54 
+your application. For example, you may create a service that deploys a Redis
55 
+image in your Swarm.
56 
+
57 
+A **task** is the atomic scheduling unit of Swarm. For example a task may be to
58 
+schedule a Redis container to run on a worker node.
59 
+
60 
+
61 
+## Service types
62 
+
63 
+For **replicated services**, Swarm deploys a specific number of replica tasks
64 
+based upon the scale you set in the desired state.
65 
+
66 
+For **global services**, Swarm runs one task for the service on every available
67 
+node in the cluster.
68 
+
69 
+## Load balancing
70 
+
71 
+Swarm uses **ingress load balancing** to expose the services you want to make
72 
+available externally to the Swarm. Swarm can automatically assign the service a
73 
+**PublishedPort** or you can configure a PublishedPort for the service in the
74 
+30000-32767 range. External components, such as cloud load balancers, can access
75 
+the service on the PublishedPort of any node in the cluster, even if the node is
76 
+not currently running the service.
77 
+
78 
+Swarm has an internal DNS component that automatically assigns each service in
79 
+the Swarm DNS entry. Swarm uses **internal load balancing** distribute requests
80 
+among services within the cluster based upon the services' DNS name.
81 
+
82 
+<p style="margin-bottom:300px">&nbsp;</p>
docs/swarm/menu.md
History View file @ ea4fef2
0 83 
new file mode 100644
... ... 
@@ -0,0 +1,21 @@
0 
+<!--[metadata]>
1 
+title = "Manage a Swarm (1.12 RC)"
2 
+description = "How to use Docker Swarm to create and manage Docker Engine clusters"
3 
+keywords = [" docker, documentation, developer, "]
4 
+[menu.main]
5 
+identifier = "engine_swarm"
6 
+parent = "engine_use"
7 
+weight = 0
8 
+advisory = "rc"
9 
+<![end-metadata]-->
10 
+
11 
+
12 
+## Use Docker Swarm to create and manage clusters of Docker Engine called Swarms
13 
+
14 
+This section contains the following topics:
15 
+
16 
+* [Docker Swarm overview](index.md)
17 
+* [Docker Swarm key concepts](key-concepts.md)
18 
+* [Getting Started with Docker Swarm](swarm-tutorial/index.md)
docs/swarm/swarm-tutorial/add-nodes.md
History View file @ ea4fef2
0 19 
new file mode 100644
... ... 
@@ -0,0 +1,64 @@
0 
+<!--[metadata]>
1 
+title = "Add nodes to the Swarm"
2 
+description = "Add nodes to the Swarm"
3 
+keywords = ["tutorial, cluster management, swarm"]
4 
+[menu.main]
5 
+identifier="add-nodes"
6 
+parent="swarm-tutorial"
7 
+weight=13
8 
+advisory = "rc"
9 
+<![end-metadata]-->
10 
+
11 
+# Add nodes to the Swarm
12 
+
13 
+Once you've [created a Swarm](create-swarm.md) with a manager node, you're ready
14 
+to add worker nodes.
15 
+
16 
+1. Open a terminal and ssh into the machine where you want to run a worker node.
17 
+This tutorial uses the name `worker1`.
18 
+
19 
+2. Run `docker swarm join MANAGER-IP:PORT` to create a worker node joined to the
20 
+existing Swarm. Replace MANAGER-IP address of the manager node and the port
21 
+where the manager listens.
22 
+
23 
+    In the tutorial, the following command joins `worker1` to the Swarm on `manager1`:
24 
+
25 
+    ```
26 
+    $ docker swarm join 192.168.99.100:2377
27 
+
28 
+    This node joined a Swarm as a worker.
29 
+    ```
30 
+
31 
+3. Open a terminal and ssh into the machine where you want to run a second
32 
+worker node. This tutorial uses the name `worker2`.
33 
+
34 
+4. Run `docker swarm join MANAGER-IP:PORT` to create a worker node joined to
35 
+the existing Swarm. Replace MANAGER-IP address of the manager node and the port
36 
+where the manager listens.
37 
+
38 
+5. Open a terminal and ssh into the machine where the manager node runs and run
39 
+the `docker node ls` command to see the worker nodes:
40 
+
41 
+    ```bash
42 
+    $ docker node ls
43 
+
44 
+    ID              NAME      MEMBERSHIP  STATUS  AVAILABILITY  MANAGER STATUS  LEADER
45 
+09fm6su6c24q *  manager1  Accepted    Ready   Active        Reachable       Yes
46 
+32ljq6xijzb9    worker1   Accepted    Ready   Active
47 
+38fsncz6fal9    worker2   Accepted    Ready   Active
48 
+    ```
49 
+
50 
+    The `MANAGER` column identifies the manager nodes in the Swarm. The empty
51 
+    status in this column for `worker1` and `worker2` identifies them as worker nodes.
52 
+
53 
+    Swarm management commands like `docker node ls` only work on manager nodes.
54 
+
55 
+
56 
+## What's next?
57 
+
58 
+Now your Swarm consists of a manager and two worker nodes. In the next step of
59 
+the tutorial, you [deploy a service](deploy-service.md) to the Swarm.
60 
+
61 
+<p style="margin-bottom:300px">&nbsp;</p>
docs/swarm/swarm-tutorial/create-swarm.md
History View file @ ea4fef2
0 62 
new file mode 100644
... ... 
@@ -0,0 +1,77 @@
0 
+<!--[metadata]>
1 
+title = "Create a Swarm"
2 
+description = "Initialize the Swarm"
3 
+keywords = ["tutorial, cluster management, swarm"]
4 
+[menu.main]
5 
+identifier="initialize-swarm"
6 
+parent="swarm-tutorial"
7 
+weight=12
8 
+advisory = "rc"
9 
+<![end-metadata]-->
10 
+
11 
+# Create a Swarm
12 
+
13 
+After you complete the [tutorial setup](index.md) steps, you're ready
14 
+to create a Swarm. Make sure the Docker Engine daemon is started on the host
15 
+machines.
16 
+
17 
+1. Open a terminal and ssh into the machine where you want to run your manager
18 
+node. For example, the tutorial uses a machine named `manager1`.
19 
+
20 
+2. Run `docker swarm init --listen-addr MANAGER-IP:PORT` to create a new Swarm.
21 
+
22 
+    In the tutorial, the following command creates a Swarm on the `manager1` machine:
23 
+
24 
+    ```
25 
+    $ docker swarm init --listen-addr 192.168.99.100:2377
26 
+
27 
+    Swarm initialized: current node (09fm6su6c24qn) is now a manager.
28 
+    ```
29 
+
30 
+    The `--listen-addr` flag configures the manager node to listen on port
31 
+    `2377`. The other nodes in the Swarm must be able to access the manager at
32 
+    the IP address.
33 
+
34 
+3. Run `docker info` to view the current state of the Swarm:
35 
+
36 
+     ```
37 
+     $ docker info
38 
+
39 
+     Containers: 2
40 
+      Running: 0
41 
+      Paused: 0
42 
+      Stopped: 2
43 
+     ...snip...
44 
+     Swarm:
45 
+      NodeID: 09fm6su6c24qn
46 
+      IsManager: YES
47 
+      Managers: 1
48 
+      Nodes: 1
49 
+     ...snip...
50 
+     ```
51 
+
52 
+4. Run the `docker node ls` command to view information about nodes:
53 
+
54 
+    ```
55 
+    $ docker node ls
56 
+
57 
+    ID              NAME      MEMBERSHIP  STATUS  AVAILABILITY  MANAGER STATUS  LEADER
58 
+09fm6su6c24q *  manager1  Accepted    Ready   Active        Reachable       Yes
59 
+
60 
+    ```
61 
+
62 
+     The `*` next to the node id, indicates that you're currently connected on
63 
+     this node.
64 
+
65 
+     Docker Swarm automatically names the node for the machine host name. The
66 
+     tutorial covers other columns in later steps.
67 
+
68 
+## What's next?
69 
+
70 
+In the next section of the tutorial, we'll [add two more nodes](add-nodes.md) to
71 
+the cluster.
72 
+
73 
+
74 
+<p style="margin-bottom:300px">&nbsp;</p>
docs/swarm/swarm-tutorial/delete-service.md
History View file @ ea4fef2
0 75 
new file mode 100644
... ... 
@@ -0,0 +1,44 @@
0 
+<!--[metadata]>
1 
+title = "Delete the service"
2 
+description = "Remove the service on the Swarm"
3 
+keywords = ["tutorial, cluster management, swarm, service"]
4 
+[menu.main]
5 
+identifier="swarm-tutorial-delete-service"
6 
+parent="swarm-tutorial"
7 
+weight=19
8 
+advisory = "rc"
9 
+<![end-metadata]-->
10 
+
11 
+# Delete the service running on the Swarm
12 
+
13 
+The remaining steps in the tutorial don't use the `helloworld` service, so now
14 
+you can delete the service from the Swarm.
15 
+
16 
+1. If you haven't already, open a terminal and ssh into the machine where you
17 
+run your manager node. For example, the tutorial uses a machine named
18 
+`manager1`.
19 
+
20 
+2. Run `docker service remove helloworld` to remove the `helloworld` service.
21 
+
22 
+    ```
23 
+    $ docker service rm helloworld
24 
+    helloworld
25 
+    ```
26 
+
27 
+3. Run `docker service inspect SERVICE-ID` to veriy that Swarm removed the
28 
+service. The CLI returns a message that the service is not found:
29 
+
30 
+    ```
31 
+    $ docker service inspect helloworld
32 
+    []
33 
+    Error: no such service or task: helloworld
34 
+    ```
35 
+
36 
+## What's next?
37 
+
38 
+In the next step of the tutorial, you set up a new service and and apply a
39 
+[rolling update](rolling-update.md).
40 
+
41 
+<p style="margin-bottom:300px">&nbsp;</p>
docs/swarm/swarm-tutorial/deploy-service.md
History View file @ ea4fef2
0 42 
new file mode 100644
... ... 
@@ -0,0 +1,50 @@
0 
+<!--[metadata]>
1 
+title = "Deploy a service"
2 
+description = "Deploy the application"
3 
+keywords = ["tutorial, cluster management, swarm"]
4 
+[menu.main]
5 
+identifier="deploy-application"
6 
+parent="swarm-tutorial"
7 
+weight=16
8 
+advisory = "rc"
9 
+<![end-metadata]-->
10 
+
11 
+# Deploy a service to the Swarm
12 
+
13 
+After you [create a Swarm](create-swarm.md), you can deploy a service to the
14 
+Swarm. For this tutorial, you also [added worker nodes](add-nodes.md), but that
15 
+is not a requirement to deploy a service.
16 
+
17 
+1. Open a terminal and ssh into the machine where you run your manager node. For
18 
+example, the tutorial uses a machine named `manager1`.
19 
+
20 
+2. Run the the following command:
21 
+
22 
+    ```bash
23 
+    $ docker service create --scale 1 --name helloworld alpine ping docker.com
24 
+
25 
+    2zs4helqu64f3k3iuwywbk49w
26 
+    ```
27 
+
28 
+    * The `docker service create` command creates the service.
29 
+    * The `--name` flag names the service `helloworld`.
30 
+    * The `--scale` flag specifies the desired state of 1 running instance.
31 
+    * The arguments `alpine ping docker.com` define the service as an Alpine
32 
+    Linux container that executes the command `ping docker.com`.
33 
+
34 
+3. Run `docker service ls` to see the list of running services:
35 
+
36 
+    ```
37 
+    $ docker service ls
38 
+
39 
+    ID            NAME        SCALE  IMAGE   COMMAND
40 
+    2zs4helqu64f  helloworld  1      alpine  ping docker.com
41 
+    ```
42 
+
43 
+## What's next?
44 
+
45 
+Now you've deployed a service to the Swarm, you're ready to [inspect the service](inspect-service.md).
46 
+
47 
+<p style="margin-bottom:300px">&nbsp;</p>
docs/swarm/swarm-tutorial/drain-node.md
History View file @ ea4fef2
0 48 
new file mode 100644
... ... 
@@ -0,0 +1,129 @@
0 
+<!--[metadata]>
1 
+title = "Drain a node"
2 
+description = "Drain nodes on the Swarm"
3 
+keywords = ["tutorial, cluster management, swarm, service, drain"]
4 
+[menu.main]
5 
+identifier="swarm-tutorial-drain-node"
6 
+parent="swarm-tutorial"
7 
+weight=21
8 
+<![end-metadata]-->
9 
+
10 
+# Drain a node on the Swarm
11 
+
12 
+In earlier steps of the tutorial, all the nodes have been running with `ACTIVE`
13 
+availability. The Swarm manager can assign tasks to any `ACTIVE` node, so all
14 
+nodes have been available to receive tasks.
15 
+
16 
+Sometimes, such as planned maintenance times, you need to set a node to `DRAIN`
17 
+availabilty. `DRAIN` availabilty  prevents a node from receiving new tasks
18 
+from the Swarm manager. It also means the manager stops tasks running on the
19 
+node and launches replica tasks on a node with `ACTIVE` availability.
20 
+
21 
+1. If you haven't already, open a terminal and ssh into the machine where you
22 
+run your manager node. For example, the tutorial uses a machine named
23 
+`manager1`.
24 
+
25 
+2. Verify that all your nodes are actively available.
26 
+
27 
+    ```
28 
+    $ docker node ls
29 
+
30 
+    ID               NAME      MEMBERSHIP  STATUS  AVAILABILITY  MANAGER STATUS  LEADER
31 
+  1x2bldyhie1cj    worker1   Accepted    Ready   Active
32 
+  1y3zuia1z224i    worker2   Accepted    Ready   Active
33 
+  2p5bfd34mx4op *  manager1  Accepted    Ready   Active        Reachable       Yes
34 
+    ```
35 
+
36 
+2. If you aren't still running the `redis` service from the [rolling
37 
+update](rolling-update.md) tutorial, start it now:
38 
+
39 
+    ```bash
40 
+    $ docker service create --scale 3 --name redis --update-delay 10s --update-parallelism 1 redis:3.0.6
41 
+
42 
+    69uh57k8o03jtqj9uvmteodbb
43 
+    ```
44 
+
45 
+3. Run `docker service tasks redis` to see how the Swarm manager assigned the
46 
+tasks to different nodes:
47 
+
48 
+    ```
49 
+    $ docker service tasks redis
50 
+    ID                         NAME     SERVICE  IMAGE        LAST STATE          DESIRED STATE  NODE
51 
+    3wfqsgxecktpwoyj2zjcrcn4r  redis.1  redis    redis:3.0.6  RUNNING 13 minutes  RUNNING        worker2
52 
+    8lcm041z3v80w0gdkczbot0gg  redis.2  redis    redis:3.0.6  RUNNING 13 minutes  RUNNING        worker1
53 
+    d48skceeph9lkz4nbttig1z4a  redis.3  redis    redis:3.0.6  RUNNING 12 minutes  RUNNING        manager1
54 
+    ```
55 
+
56 
+    In this case the Swarm manager distributed one task to each node. You may
57 
+    see the tasks distributed differently among the nodes in your environment.
58 
+
59 
+4. Run `docker node update --availability drain NODE-ID` to drain a node that
60 
+had a task assigned to it:
61 
+
62 
+    ```bash
63 
+    docker node update --availability drain worker1
64 
+    worker1
65 
+    ```
66 
+
67 
+5. Inspect the node to check its availability:
68 
+
69 
+    ```
70 
+    $ docker node inspect --pretty worker1
71 
+    ID:			1x2bldyhie1cj
72 
+    Hostname:		worker1
73 
+    Status:
74 
+     State:			READY
75 
+     Availability:		DRAIN
76 
+    ...snip...
77 
+    ```
78 
+
79 
+    The drained node shows `Drain` for `AVAILABILITY`.
80 
+
81 
+6. Run `docker service tasks redis` to see how the Swarm manager updated the
82 
+task assignments for the `redis` service:
83 
+
84 
+    ```
85 
+    ID                         NAME     SERVICE  IMAGE        LAST STATE          DESIRED STATE  NODE
86 
+    3wfqsgxecktpwoyj2zjcrcn4r  redis.1  redis    redis:3.0.6  RUNNING 26 minutes  RUNNING        worker2
87 
+    ah7o4u5upostw3up1ns9vbqtc  redis.2  redis    redis:3.0.6  RUNNING 9 minutes   RUNNING        manager1
88 
+    d48skceeph9lkz4nbttig1z4a  redis.3  redis    redis:3.0.6  RUNNING 26 minutes  RUNNING        manager1
89 
+    ```
90 
+
91 
+    The Swarm manager maintains the desired state by ending the task on a node
92 
+    with `Drain` availability and creating a new task on a node with `Active`
93 
+    availability.
94 
+
95 
+7. Run  `docker node update --availability active NODE-ID` to return the drained
96 
+node to an active state:
97 
+
98 
+    ```bash
99 
+    $ docker node update --availability active worker1
100 
+    worker1
101 
+    ```
102 
+
103 
+8. Inspect the node to see the updated state:
104 
+
105 
+   ```
106 
+   $ docker node inspect --pretty worker1
107 
+   ID:			1x2bldyhie1cj
108 
+   Hostname:		worker1
109 
+   Status:
110 
+    State:			READY
111 
+    Availability:		ACTIVE
112 
+  ...snip...
113 
+  ```
114 
+
115 
+  When you set the node back to `Active` availability, it can receive new tasks:
116 
+
117 
+  * during a service update to scale up
118 
+  * during a rolling update
119 
+  * when you set another node to `Drain` availability
120 
+  * when a task fails on another active node
121 
+
122 
+## What's next?
123 
+
124 
+The next topic in the tutorial introduces volumes.
125 
+
126 
+<p style="margin-bottom:300px">&nbsp;</p>
docs/swarm/swarm-tutorial/index.md
History View file @ ea4fef2
0 127 
new file mode 100644
... ... 
@@ -0,0 +1,87 @@
0 
+<!--[metadata]>
1 
+title = "Set up for the tutorial"
2 
+description = "Getting Started tutorial for Docker Swarm"
3 
+keywords = ["tutorial, cluster management, swarm"]
4 
+[menu.main]
5 
+identifier="tutorial-setup"
6 
+parent="swarm-tutorial"
7 
+weight=11
8 
+advisory = "rc"
9 
+<![end-metadata]-->
10 
+
11 
+# Getting Started with Docker Swarm
12 
+
13 
+This tutorial introduces you to the key features of Docker Swarm. It guides you
14 
+through the following activities:
15 
+
16 
+* initializing a cluster of Docker Engines called a Swarm
17 
+* adding nodes to the Swarm
18 
+* deploying application services to the Swarm
19 
+* managing the Swarm once you have everything running
20 
+
21 
+This tutorial uses Docker Engine CLI commands entered on the command line of a
22 
+terminal window. You should be able to install Docker on networked machines and
23 
+be comfortable running commands in the shell of your choice.
24 
+
25 
+If you’re brand new to Docker, see [About Docker Engine](../../index.md).
26 
+
27 
+## Set up
28 
+To run this tutorial, you need the following:
29 
+
30 
+* [three networked host machines](#three-networked-host-machines)
31 
+* [Docker Engine 1.12 or later installed](#docker-engine-1-12-or-later)
32 
+* [the IP address of the manager machine](#the-ip-address-of-the-manager-machine)
33 
+* [open ports between the hosts](#open-ports-between-the-hosts)
34 
+
35 
+### Three networked host machines
36 
+
37 
+The tutorial uses three networked host machines as nodes in the Swarm. These can
38 
+be virtual machines on your PC, in a data center, or on a cloud service
39 
+provider. This tutorial uses the following machine names:
40 
+
41 
+* manager1
42 
+* worker1
43 
+* worker2
44 
+
45 
+###  Docker Engine 1.12 or later
46 
+
47 
+You must install Docker Engine on each one of the host machines. To use this
48 
+version of Swarm, install the Docker Engine `v1.12.0-rc1` or later from the
49 
+[Docker releases GitHub repository](https://github.com/docker/docker/releases).
50 
+Alternatively, install the latest Docker for Mac or Docker for Windows Beta.
51 
+
52 
+Verify that the Docker Engine daemon is running on each of the machines.
53 
+
54 
+<!-- See the following options to install:
55 
+
56 
+* [Install Docker Engine](../../installation/index.md).
57 
+
58 
+* [Example: Manual install on cloud provider](../../installation/cloud/cloud-ex-aws.md).
59 
+-->
60 
+
61 
+### The IP address of the manager machine
62 
+
63 
+The IP address must be assigned to an a network interface available to the host
64 
+operating system. All nodes in the Swarm must be able to access the manager at the IP address.
65 
+
66 
+>**Tip**: You can run `ifconfig` on Linux or Mac OSX to see a list of the
67 
+available network interfaces.
68 
+
69 
+The tutorial uses `manager1` : `192.168.99.100`.
70 
+
71 
+### Open ports between the hosts
72 
+
73 
+* **TCP port 2377** for cluster management communications
74 
+* **TCP** and **UDP port 7946** for communication among nodes
75 
+* **TCP** and **UDP port 4789** for overlay network traffic
76 
+
77 
+>**Tip**: Docker recommends that every node in the cluster be on the same layer
78 
+3 (IP) subnet with all traffic permitted between nodes.
79 
+
80 
+## What's next?
81 
+
82 
+After you have set up your environment, you're ready to [create a Swarm](create-swarm.md).
83 
+
84 
+<p style="margin-bottom:300px">&nbsp;</p>
docs/swarm/swarm-tutorial/inspect-service.md
History View file @ ea4fef2
0 85 
new file mode 100644
... ... 
@@ -0,0 +1,124 @@
0 
+<!--[metadata]>
1 
+title = "Inspect the service"
2 
+description = "Inspect the application"
3 
+keywords = ["tutorial, cluster management, swarm"]
4 
+[menu.main]
5 
+identifier="inspect-application"
6 
+parent="swarm-tutorial"
7 
+weight=17
8 
+advisory = "rc"
9 
+<![end-metadata]-->
10 
+
11 
+# Inspect a service on the Swarm
12 
+
13 
+When you have [deployed a service](deploy-service.md) to your Swarm, you can use
14 
+the Docker CLI to see details about the service running in the Swarm.
15 
+
16 
+1. If you haven't already, open a terminal and ssh into the machine where you
17 
+run your manager node. For example, the tutorial uses a machine named
18 
+`manager1`.
19 
+
20 
+2. Run `docker service inspect --pretty SERVICE-ID` to display the details about
21 
+a service in an easily readable format.
22 
+
23 
+    To see the details on the `helloworld` service:
24 
+    ```
25 
+    $ docker service inspect --pretty helloworld
26 
+
27 
+    ID:		2zs4helqu64f3k3iuwywbk49w
28 
+    Name:		helloworld
29 
+    Mode:		REPLICATED
30 
+     Scale:	1
31 
+    Placement:
32 
+     Strategy:	SPREAD
33 
+    UpateConfig:
34 
+     Parallelism:	1
35 
+    ContainerSpec:
36 
+     Image:		alpine
37 
+     Command:	ping docker.com
38 
+    ```
39 
+
40 
+    >**Tip**: To return the service details in json format, run the same command
41 
+    without the `--pretty` flag.
42 
+
43 
+    ```
44 
+    $ docker service inspect helloworld
45 
+    [
46 
+    {
47 
+        "ID": "2zs4helqu64f3k3iuwywbk49w",
48 
+        "Version": {
49 
+            "Index": 16264
50 
+        },
51 
+        "CreatedAt": "2016-06-06T17:41:11.509146705Z",
52 
+        "UpdatedAt": "2016-06-06T17:41:11.510426385Z",
53 
+        "Spec": {
54 
+            "Name": "helloworld",
55 
+            "ContainerSpec": {
56 
+                "Image": "alpine",
57 
+                "Command": [
58 
+                    "ping",
59 
+                    "docker.com"
60 
+                ],
61 
+                "Resources": {
62 
+                    "Limits": {},
63 
+                    "Reservations": {}
64 
+                }
65 
+            },
66 
+            "Mode": {
67 
+                "Replicated": {
68 
+                    "Instances": 1
69 
+                }
70 
+            },
71 
+            "RestartPolicy": {},
72 
+            "Placement": {},
73 
+            "UpdateConfig": {
74 
+                "Parallelism": 1
75 
+            },
76 
+            "EndpointSpec": {}
77 
+        },
78 
+        "Endpoint": {
79 
+            "Spec": {}
80 
+        }
81 
+    }
82 
+    ]
83 
+    ```
84 
+
85 
+4. Run `docker service tasks SERVICE-ID` to see which nodes are running the
86 
+service:
87 
+
88 
+    ```
89 
+    $ docker service tasks helloworld
90 
+
91 
+    ID                         NAME          SERVICE     IMAGE   DESIRED STATE  LAST STATE          NODE
92 
+    1n6wif51j0w840udalgw6hphg  helloworld.1  helloworld  alpine  RUNNING        RUNNING 19 minutes  manager1
93 
+    ```
94 
+
95 
+    In this case, the one instance of the `helloworld` service is running on the
96 
+    `manager1` node. Manager nodes in a Swarm can execute tasks just like worker
97 
+    nodes.
98 
+
99 
+    Swarm also shows you the `DESIRED STATE` and `LAST STATE` of the service
100 
+    task so you can see if tasks are running according to the service
101 
+    definition.
102 
+
103 
+4. Run `docker ps` on the node where the instance of the service is running to
104 
+see the service container.
105 
+
106 
+    >**Tip**: If `helloworld` is running on a node other than your manager node,
107 
+    you must ssh to that node.
108 
+
109 
+    ```bash
110 
+    $docker ps
111 
+
112 
+    CONTAINER ID        IMAGE               COMMAND             CREATED             STATUS              PORTS               NAMES
113 
+    a0b6c02868ca        alpine:latest       "ping docker.com"   12 minutes ago      Up 12 minutes                           helloworld.1.1n6wif51j0w840udalgw6hphg
114 
+    ```
115 
+
116 
+## What's next?
117 
+
118 
+Next, you can [change the scale](scale-service.md) for the service running in
119 
+the Swarm.
120 
+
121 
+  <p style="margin-bottom:300px">&nbsp;</p>
docs/swarm/swarm-tutorial/menu.md
History View file @ ea4fef2
0 122 
new file mode 100644
... ... 
@@ -0,0 +1,21 @@
0 
+<!--[metadata]>
1 
+title = "Get started with Swarm"
2 
+description = "Getting started tutorial for Docker Swarm"
3 
+keywords = ["cluster, swarm, tutorial"]
4 
+[menu.main]
5 
+identifier="swarm-tutorial"
6 
+parent="engine_swarm"
7 
+weight=10
8 
+advisory = "rc"
9 
+<![end-metadata]-->
10 
+
11 
+#  Docker Swarm getting started tutorial
12 
+
13 
+## TOC
14 
+
15 
+-   [Begin the tutorial](index.md) - Setup your environment to prepare
16 
+    to build a Swarm.
17 
+
18 
+<p style="margin-bottom:300px">&nbsp;</p>
docs/swarm/swarm-tutorial/rolling-update.md
History View file @ ea4fef2
0 19 
new file mode 100644
... ... 
@@ -0,0 +1,105 @@
0 
+<!--[metadata]>
1 
+title = "Apply rolling updates"
2 
+description = "Apply rolling updates to a service on the Swarm"
3 
+keywords = ["tutorial, cluster management, swarm, service, rolling-update"]
4 
+[menu.main]
5 
+identifier="swarm-tutorial-rolling-update"
6 
+parent="swarm-tutorial"
7 
+weight=20
8 
+advisory = "rc"
9 
+<![end-metadata]-->
10 
+
11 
+# Apply rolling updates to a service
12 
+
13 
+In a previous step of the tutorial, you [scaled](scale-service.md) the number of
14 
+instances of a service. In this part of the tutorial, you deploy a new Redis
15 
+service and upgrade the service using rolling updates.
16 
+
17 
+1. If you haven't already, open a terminal and ssh into the machine where you
18 
+run your manager node. For example, the tutorial uses a machine named
19 
+`manager1`.
20 
+
21 
+2. Deploy Redis 3.0.6 to all nodes in the Swarm and configure
22 
+the swarm to update one node every 10 seconds:
23 
+
24 
+    ```bash
25 
+    $ docker service create --scale 3 --name redis --update-delay 10s --update-parallelism 1 redis:3.0.6
26 
+
27 
+    8m228injfrhdym2zvzhl9k3l0
28 
+    ```
29 
+
30 
+    You configure the rolling update policy at service deployment time.
31 
+
32 
+    The `--update-parallelism` flag configures the number of service tasks
33 
+    to update simultaneously.
34 
+
35 
+    The `--update-delay` flag configures the time delay between updates to
36 
+    a service task or sets of tasks. You can describe the time `T` in the number
37 
+    of seconds `Ts`, minutes `Tm`, or hours `Th`. So `10m` indicates a 10 minute
38 
+    delay.
39 
+
40 
+3. Inspect the `redis` service:
41 
+    ```
42 
+    $ docker service inspect redis --pretty
43 
+
44 
+    ID:		75kcmhuf8mif4a07738wttmgl
45 
+    Name:		redis
46 
+    Mode:		REPLICATED
47 
+     Scale:	3
48 
+    Placement:
49 
+     Strategy:	SPREAD
50 
+    UpateConfig:
51 
+     Parallelism:	1
52 
+     Delay:		10s
53 
+    ContainerSpec:
54 
+     Image:		redis:3.0.6
55 
+    ```
56 
+
57 
+4. Now you can update the container image for `redis`. Swarm applies the update
58 
+to nodes according to the `UpdateConfig` policy:
59 
+
60 
+    ```bash
61 
+    $ docker service update --image redis:3.0.7 redis
62 
+    redis
63 
+    ```
64 
+
65 
+5. Run `docker service inspect --pretty redis` to see the new image in the
66 
+desired state:
67 
+
68 
+    ```
69 
+    docker service inspect --pretty redis
70 
+
71 
+    ID:		1yrcci9v8zj6cokua2eishlob
72 
+    Name:		redis
73 
+    Mode:		REPLICATED
74 
+     Scale:		3
75 
+    Placement:
76 
+     Strategy:	SPREAD
77 
+    UpdateConfig:
78 
+     Parallelism:	1
79 
+     Delay:		10s
80 
+   ContainerSpec:
81 
+   Image:		redis:3.0.7
82 
+   ```
83 
+
84 
+6. Run `docker service tasks TASK-ID` to watch the rolling update:
85 
+
86 
+    ```
87 
+    $ docker service tasks redis
88 
+
89 
+    ID                         NAME     SERVICE  IMAGE        DESIRED STATE  LAST STATE          NODE
90 
+    5409nu4crb0smamziqwuug67u  redis.1  redis    redis:3.0.7  RUNNING        RUNNING 21 seconds  worker2
91 
+    b8ezq58zugcg1trk8k7jrq9ym  redis.2  redis    redis:3.0.7  RUNNING        RUNNING 1 seconds   worker1
92 
+    cgdcbipxnzx0y841vysiafb64  redis.3  redis    redis:3.0.7  RUNNING        RUNNING 11 seconds  worker1
93 
+    ```
94 
+
95 
+    Before Swarm updates all of the tasks, you can see that some are running
96 
+    `redis:3.0.6` while others are running `redis:3.0.7`. The output above shows
97 
+    the state once the rolling updates are done. You can see that each instances
98 
+    entered the `RUNNING` state in 10 second increments.
99 
+
100 
+Next, learn about how to [drain a node](drain-node.md) in the Swarm.
101 
+
102 
+<p style="margin-bottom:300px">&nbsp;</p>
docs/swarm/swarm-tutorial/scale-service.md
History View file @ ea4fef2
0 103 
new file mode 100644
... ... 
@@ -0,0 +1,75 @@
0 
+<!--[metadata]>
1 
+title = "Scale the service"
2 
+description = "Scale the service running in the Swarm"
3 
+keywords = ["tutorial, cluster management, swarm, scale"]
4 
+[menu.main]
5 
+identifier="swarm-tutorial-scale-service"
6 
+parent="swarm-tutorial"
7 
+weight=18
8 
+advisory = "rc"
9 
+<![end-metadata]-->
10 
+
11 
+# Scale the service in the Swarm
12 
+
13 
+Once you have [deployed a service](deploy-service.md) to a Swarm, you are ready
14 
+to use the Docker CLI to scale the number of service tasks in
15 
+the Swarm.
16 
+
17 
+1. If you haven't already, open a terminal and ssh into the machine where you
18 
+run your manager node. For example, the tutorial uses a machine named
19 
+`manager1`.
20 
+
21 
+2. Run the following command to change the desired state of the
22 
+service runing in the Swarm:
23 
+
24 
+    ```
25 
+    $ docker service update --scale NUMBER-OF-TASKS SERVICE-ID
26 
+    ```
27 
+
28 
+    The `--scale` flag indicates the number of tasks you want in the new desired
29 
+    state. For example:
30 
+
31 
+    ```
32 
+    $ docker service update --scale 5 helloworld
33 
+    helloworld
34 
+    ```
35 
+
36 
+3. Run `docker service tasks SERVICE-ID` to see the updated task list:
37 
+
38 
+    ```
39 
+    $ docker service tasks helloworld
40 
+
41 
+    ID                         NAME          SERVICE     IMAGE   DESIRED STATE  LAST STATE          NODE
42 
+    1n6wif51j0w840udalgw6hphg  helloworld.1  helloworld  alpine  RUNNING        RUNNING 2 minutes   manager1
43 
+    dfhsosk00wxfb7j0cazp3fmhy  helloworld.2  helloworld  alpine  RUNNING        RUNNING 15 seconds  worker2
44 
+    6cbedbeywo076zn54fnwc667a  helloworld.3  helloworld  alpine  RUNNING        RUNNING 15 seconds  worker1
45 
+    7w80cafrry7asls96lm2tmwkz  helloworld.4  helloworld  alpine  RUNNING        RUNNING 10 seconds  worker1
46 
+    bn67kh76crn6du22ve2enqg5j  helloworld.5  helloworld  alpine  RUNNING        RUNNING 10 seconds  manager1
47 
+    ```
48 
+
49 
+    You can see that Swarm has created 4 new tasks to scale to a total of 5
50 
+    running instances of Alpine Linux. The tasks are distributed between the
51 
+    three nodes of the Swarm. Two are running on `manager1`.
52 
+
53 
+4. Run `docker ps` to see the containers running on the node where you're
54 
+connected. The following example shows the tasks running on `manager1`:
55 
+
56 
+    ```
57 
+    $ docker ps
58 
+
59 
+    CONTAINER ID        IMAGE               COMMAND             CREATED             STATUS              PORTS               NAMES
60 
+    910669d5e188        alpine:latest       "ping docker.com"   10 seconds ago      Up 10 seconds                           helloworld.5.bn67kh76crn6du22ve2enqg5j
61 
+    a0b6c02868ca        alpine:latest       "ping docker.com"   2 minutes  ago      Up 2 minutes                            helloworld.1.1n6wif51j0w840udalgw6hphg
62 
+    ```
63 
+
64 
+    If you want to see the containers running on other nodes, you can ssh into
65 
+    those nodes and run the `docker ps` command.
66 
+
67 
+## What's next?
68 
+
69 
+At this point in the tutorial, you're finished with the `helloworld` service.
70 
+The next step shows how to [delete the service](delete-service.md).
71 
+
72 
+<p style="margin-bottom:300px">&nbsp;</p>