From 68a9224bd42437e63972dc9c3374c065872363b3 Mon Sep 17 00:00:00 2001
From: Charles Smith <charles.smith@docker.com>
Date: Mon, 11 Jul 2016 20:06:56 -0700
Subject: [PATCH] clarify update-delay and rolling update behavior

Signed-off-by: Charles Smith <charles.smith@docker.com>
---
 docs/swarm/swarm-tutorial/rolling-update.md | 41 +++++++++++++++------
 1 file changed, 30 insertions(+), 11 deletions(-)

diff --git a/docs/swarm/swarm-tutorial/rolling-update.md b/docs/swarm/swarm-tutorial/rolling-update.md
index 7c2dc0cb66..8e703df01a 100644
--- a/docs/swarm/swarm-tutorial/rolling-update.md
+++ b/docs/swarm/swarm-tutorial/rolling-update.md
@@ -22,24 +22,34 @@ Redis 3.0.7 container image using rolling updates.
 run your manager node. For example, the tutorial uses a machine named
 `manager1`.
 
-2. Deploy Redis 3.0.6 to the swarm and configure the swarm to update one node
-every 10 seconds:
+2. Deploy Redis 3.0.6 to the swarm and configure the swarm with a 10 second
+update delay:
 
     ```bash
-    $ docker service create --replicas 3 --name redis --update-delay 10s --update-parallelism 1 redis:3.0.6
+    $ docker service create \
+      --replicas 3 \
+      --name redis \
+      --update-delay 10s \
+      --update-parallelism 1 \
+      redis:3.0.6
 
     0u6a4s31ybk7yw2wyvtikmu50
     ```
 
     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-parallelism` flag configures the number of service tasks that
+    the scheduler can update simultaneously. When updates to individual tasks
+    return a state of `RUNNING` or `FAILED`, the scheduler schedules another
+    task to update until all tasks are updated.
 
     The `--update-delay` flag configures the time delay between updates to a
-    service task or sets of tasks. You can describe the time `T` as a
-    combination of the number of seconds `Ts`, minutes `Tm`, or hours `Th`. So
-    `10m30s` indicates a 10 minute 30 second delay.
+    service task or sets of tasks.
+
+    You can describe the time `T` as a combination of the number of seconds
+    `Ts`, minutes `Tm`, or hours `Th`. So `10m30s` indicates a 10 minute 30
+    second delay.
+
 
 3. Inspect the `redis` service:
 
@@ -51,6 +61,7 @@ every 10 seconds:
     Mode:           Replicated
      Replicas:      3
     Placement:
+     Strategy:	    Spread
     UpdateConfig:
      Parallelism:   1
      Delay:         10s
@@ -67,6 +78,14 @@ applies the update to nodes according to the `UpdateConfig` policy:
     redis
     ```
 
+    The scheduler applies rolling updates as follows:
+
+    * Stop the initial number of tasks according to `--update-parallelism`.
+    * Schedule updates for the stopped tasks.
+    * Start the containers for the updated tasks.
+    * After an update to a task completes, wait for the specified delay
+    period before stopping the next task.
+
 5. Run `docker service inspect --pretty redis` to see the new image in the
 desired state:
 
@@ -78,13 +97,14 @@ desired state:
     Mode:           Replicated
      Replicas:      3
     Placement:
+     Strategy:	    Spread
     UpdateConfig:
      Parallelism:   1
      Delay:         10s
     ContainerSpec:
      Image:         redis:3.0.7
     Resources:
-   ```
+    ```
 
 6. Run `docker service tasks <TASK-ID>` to watch the rolling update:
 
@@ -99,7 +119,6 @@ desired state:
 
     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 approximately 10 second increments.
+    the state once the rolling updates are done.
 
 Next, learn about how to [drain a node](drain-node.md) in the Swarm.