add tutorialswarm

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

13 files changed, 961 insertions, 0 deletions

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