From 9a1330e96612fd72ee0ca7c40a289d7c2ce87504 Mon Sep 17 00:00:00 2001
From: Gwendolynne Barr <31074572+gbarr01@users.noreply.github.com>
Date: Tue, 29 Aug 2017 15:32:43 -0700
Subject: [PATCH] Distinguish tasks from containers (#4378)

---
 get-started/part3.md | 47 +++++++++++++++++++++++++++++++++++++-------
 1 file changed, 40 insertions(+), 7 deletions(-)

diff --git a/get-started/part3.md b/get-started/part3.md
index 30a817d676..a3fa0e4d8d 100644
--- a/get-started/part3.md
+++ b/get-started/part3.md
@@ -146,10 +146,40 @@ Now let's run it. You have to give your app a name. Here, it is set to
 docker stack deploy -c docker-compose.yml getstartedlab
 ```
 
-See a list of the 5 containers you just launched:
+Our single service stack is running 5 container instances of our deployed image
+on one host. Let's investigate.
+
+Get the service ID for the one service in our application:
 
 ```shell
-docker stack ps getstartedlab
+docker service ls
+```
+
+Docker swarms run tasks that spawn containers. Tasks have state and their own
+IDs:
+
+```shell
+docker service ps <service>
+```
+
+>**Note**: Docker's support for swarms is built using a project called SwarmKit. SwarmKit tasks do not need to be containers, but Docker swarm tasks are defined to spawn them.
+
+Let's inspect one task and limit the ouput to container ID:
+
+```shell
+docker inspect --format='{% raw %}{{.Status.ContainerStatus.ContainerID}}{% endraw %}' <task>
+```
+
+Vice versa, inspect the container ID, and extract the task ID:
+
+```shell
+docker inspect --format="{% raw %}{{index .Config.Labels \"com.docker.swarm.task.id\"}}{% endraw %}" <container>
+```
+
+Now list all 5 containers:
+
+```shell
+docker container ls -q
 ```
 
 You can run `curl http://localhost` several times in a row, or go to that URL in
@@ -174,8 +204,9 @@ docker stack deploy -c docker-compose.yml getstartedlab
 Docker will do an in-place update, no need to tear the stack down first or kill
 any containers.
 
-Now, re-run the `docker stack ps` command to see the deployed instances reconfigured. For example, if you scaled up the replicas, there will be more
-running containers.
+Now, re-run `docker container ls -q` to see the deployed instances reconfigured.
+If you scaled up the replicas, more tasks, and hence, more containers, are
+started.
 
 ### Take down the app and the swarm
 
@@ -215,9 +246,11 @@ it runs, using the same command that launched the service:
 Some commands to explore at this stage:
 
 ```shell
-docker stack ls              # List all running applications on this Docker host
+docker stack ls                                            # List stacks or apps
 docker stack deploy -c <composefile> <appname>  # Run the specified Compose file
-docker stack services <appname>       # List the services associated with an app
-docker stack ps <appname>   # List the running containers associated with an app
+docker service ls                 # List running services associated with an app
+docker service ps <service>                  # List tasks associated with an app
+docker inspect <task or container>                   # Inspect task or container
+docker container ls -q                                      # List container IDs
 docker stack rm <appname>                             # Tear down an application
 ```