diff --git a/docs/swarm/how-swarm-mode-works/nodes.md b/docs/swarm/how-swarm-mode-works/nodes.md
index 90f37caaf7fd1..81e79b53726ee 100644
--- a/docs/swarm/how-swarm-mode-works/nodes.md
+++ b/docs/swarm/how-swarm-mode-works/nodes.md
@@ -86,8 +86,7 @@ take a manager node offline for maintenance. See [node promote](../../reference/
You can also demote a manager node to a worker node. See
[node demote](../../reference/commandline/node_demote.md).
-
diff --git a/docs/swarm/how-swarm-mode-works/services.md b/docs/swarm/how-swarm-mode-works/services.md
new file mode 100644
index 0000000000000..f8a1f8f93999f
--- /dev/null
+++ b/docs/swarm/how-swarm-mode-works/services.md
@@ -0,0 +1,101 @@
+
+
+# How services work
+
+To deploy an application image when Docker Engine is in swarm mode, you create a
+service. Frequently a service will be the image for a microservice within the
+context of some larger application. Examples of services might include an HTTP
+server, a database, or any other type of executable program that you wish to run
+in a distributed environment.
+
+When you create a service, you specify which container image to use and which
+commands to execute inside running containers. You also define options for the
+service including:
+
+* the port where the swarm will make the service available outside the swarm
+* an overlay network for the service to connect to other services in the swarm
+* CPU and memory limits and reservations
+* a rolling update policy
+* the number of replicas of the image to run in the swarm
+
+## Services, tasks, and containers
+
+When you deploy the service to the swarm, the swarm manager accepts your service
+definition as the desired state for the service. Then it schedules the service
+on nodes in the swarm as one or more replica tasks. The tasks run independently
+of each other on nodes in the swarm.
+
+For example, imagine you want to load balance between three instances of an HTTP
+listener. The diagram below shows an HTTP listener service with three replicas.
+Each of the three instances of the listener is a task in the swarm.
+
+
+
+A container is an isolated process. In the swarm mode model, each task invokes
+exactly one container. A task is analogous to a “slot” where the scheduler
+places a container. Once the container is live, the scheduler recognizes that
+the task is in a running state. If the container fails health checks or
+terminates, the task terminates.
+
+## Tasks and scheduling
+
+A task is the atomic unit of scheduling within a swarm. When you declare a
+desired service state by creating or updating a service, the orchestrator
+realizes the desired state by scheduling tasks. For instance, the you define a
+service that instructs the orchestrator to keep three instances of a HTTP
+listener running at all times. The orchestrator responds by creating three
+tasks. Each task is a slot that the scheduler fills by spawning a container. The
+container is the instantiation of the task. If a HTTP listener task subsequently
+fails its health check or crashes, the orchestrator creates a new replica task
+that spawns a new container.
+
+A task is a one-directional mechanism. It progresses monotonically through a
+series of states: assigned, prepared, running, etc. If the task fails the
+scheduler removes the task and its container and then creates a new task to
+replace it according to the desired state specified by the service.
+
+The underlying logic of Docker swarm mode is a general purpose scheduler and
+orchestrator. The service and task abstractions themselves are unaware of the
+containers they implement. Hypothetically, you could implement other types of
+tasks such as virtual machine tasks or non-containerized process tasks. The
+scheduler and orchestrator are agnostic about they type of task. However, the
+current version of Docker only supports container tasks.
+
+The diagram below shows how swarm mode accepts service create requests and
+schedules tasks to worker nodes.
+
+
+
+## Replicated and global services
+
+There are two types of service deployments, replicated and global.
+
+For a replicated service, you specify the number of identical tasks you want to
+run. For example, you decide to deploy an HTTP service with three replicas, each
+serving the same content.
+
+A global service is a service that runs one task on every node. There is no
+pre-specified number of tasks. Each time you add a node to the swarm, the
+orchestrator creates a task and the scheduler assigns the task to the new node.
+Good candidates for global services are monitoring agents, an anti-virus
+scanners or other types of containers that you want to run on every node in the
+swarm.
+
+The diagram below shows a three-service replica in yellow and a global service
+in gray.
+
+
diff --git a/docs/swarm/images/replicated-vs-global.png b/docs/swarm/images/replicated-vs-global.png
new file mode 100644
index 0000000000000..9633999859f54
Binary files /dev/null and b/docs/swarm/images/replicated-vs-global.png differ
diff --git a/docs/swarm/images/service-lifecycle.png b/docs/swarm/images/service-lifecycle.png
new file mode 100644
index 0000000000000..f3c1eca957c0b
Binary files /dev/null and b/docs/swarm/images/service-lifecycle.png differ
diff --git a/docs/swarm/images/services-diagram.png b/docs/swarm/images/services-diagram.png
new file mode 100644
index 0000000000000..ab431b8ef1e1b
Binary files /dev/null and b/docs/swarm/images/services-diagram.png differ
diff --git a/docs/swarm/images/src/replicated-vs-global.svg b/docs/swarm/images/src/replicated-vs-global.svg
new file mode 100644
index 0000000000000..b4b9735ba21ad
--- /dev/null
+++ b/docs/swarm/images/src/replicated-vs-global.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/docs/swarm/images/src/service-lifecycle.svg b/docs/swarm/images/src/service-lifecycle.svg
new file mode 100644
index 0000000000000..5ffa231d8878d
--- /dev/null
+++ b/docs/swarm/images/src/service-lifecycle.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/docs/swarm/images/src/services-diagram.svg b/docs/swarm/images/src/services-diagram.svg
new file mode 100644
index 0000000000000..90c7c0ba3b934
--- /dev/null
+++ b/docs/swarm/images/src/services-diagram.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/docs/swarm/images/src/simple-cluster.svg b/docs/swarm/images/src/simple-cluster.svg
new file mode 100644
index 0000000000000..71d0b5d415a5f
--- /dev/null
+++ b/docs/swarm/images/src/simple-cluster.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/docs/swarm/images/swarm-diagram.png b/docs/swarm/images/swarm-diagram.png
index 170fb6775950c..147dab3cae1e0 100644
Binary files a/docs/swarm/images/swarm-diagram.png and b/docs/swarm/images/swarm-diagram.png differ