Engdocs 1912b - freshness (#18914)

* swarm tutorial and concepts

* how swarm works

* review edits

content/engine/swarm/_index.md

@@ -1,6 +1,6 @@
 ---
-description: Docker Engine swarm mode overview
-keywords: docker, container, cluster, swarm
+description: Docker Engine Swarm mode overview
+keywords: docker, container, cluster, swarm, docker engine
 title: Swarm mode overview
 aliases:
 - /api/swarm-api/
@@ -47,11 +47,8 @@ aliases:
 
 {{< include "swarm-mode.md" >}}
 
-To use Docker in swarm mode, install Docker. See
-[installation instructions](../../get-docker.md) for all operating systems and platforms.
-
-Current versions of Docker include *swarm mode* for natively managing a cluster
-of Docker Engines called a *swarm*. Use the Docker CLI to create a swarm, deploy
+Current versions of Docker include Swarm mode for natively managing a cluster
+of Docker Engines called a swarm. Use the Docker CLI to create a swarm, deploy
 application services to a swarm, and manage swarm behavior.
 
 Docker Swarm mode is built into the Docker Engine. Do not confuse Docker Swarm mode
@@ -60,74 +57,84 @@ which is no longer actively developed.
 
 ## 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
+### 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, the Docker Engine handles any specialization at
-runtime. You can deploy both kinds of nodes, managers and workers, using the
+### Decentralized design
+
+Instead of handling differentiation between node roles at deployment time, the Docker Engine 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:** Docker Engine uses a declarative approach to
+### Declarative service model
+
+Docker Engine uses a declarative approach 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.
 
-* **Scaling:** For each service, you can declare the number of tasks you want to
+### Scaling 
+
+For each service, you can declare the number of tasks you want to
 run. When you scale up or down, the swarm manager automatically adapts by
 adding or removing tasks to maintain the desired state.
 
-* **Desired state reconciliation:** The swarm manager node constantly monitors
+### Desired state reconciliation
+
+The swarm manager node constantly monitors
 the cluster state and reconciles any differences between the actual state and your
 expressed desired state. For example, if you set up a service to run 10
 replicas of a container, and a worker machine hosting two of those replicas
 crashes, the manager creates two new replicas to replace the replicas that
 crashed. The swarm manager assigns the new replicas to workers that are
 running and available.
 
-* **Multi-host networking:** You can specify an overlay network for your
+### Multi-host networking
+
+You can specify an overlay network for your
 services. The swarm manager automatically assigns addresses to the containers
 on the overlay network when it initializes or updates the application.
 
-* **Service discovery:** Swarm manager nodes assign each service in the swarm a
+### Service discovery
+
+Swarm manager nodes assign each service in the swarm a
 unique DNS name and load balance running containers. You can query every
 container running in the swarm through a DNS server embedded in the swarm.
 
-* **Load balancing:** You can expose the ports for services to an
+### Load balancing
+
+You can expose the ports for services to an
 external load balancer. Internally, the swarm lets you specify how to distribute
 service containers between nodes.
 
-* **Secure by default:** Each node in the swarm enforces TLS mutual
+### 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.
 
-* **Rolling updates:** At rollout time you can apply service updates to nodes
+### Rolling updates
+
+At rollout time you can apply service updates to nodes
 incrementally. The swarm manager lets you control the delay between service
 deployment to different sets of nodes. If anything goes wrong, you can
 roll back to a previous version of the service.
 
 ## What's next?
 
-### Swarm mode key concepts and tutorial
-
-* Learn swarm mode [key concepts](key-concepts.md).
-
+* Learn Swarm mode [key concepts](key-concepts.md).
 * Get started with the [Swarm mode tutorial](swarm-tutorial/index.md).
-
-### Swarm mode CLI commands
-
-Explore swarm mode CLI commands
-
-* [swarm init](../reference/commandline/swarm_init.md)
-* [swarm join](../reference/commandline/swarm_join.md)
-* [service create](../reference/commandline/service_create.md)
-* [service inspect](../reference/commandline/service_inspect.md)
-* [service ls](../reference/commandline/service_ls.md)
-* [service rm](../reference/commandline/service_rm.md)
-* [service scale](../reference/commandline/service_scale.md)
-* [service ps](../reference/commandline/service_ps.md)
-* [service update](../reference/commandline/service_update.md)
+* Explore Swarm mode CLI commands
+  * [swarm init](../reference/commandline/swarm_init.md)
+  * [swarm join](../reference/commandline/swarm_join.md)
+  * [service create](../reference/commandline/service_create.md)
+  * [service inspect](../reference/commandline/service_inspect.md)
+  * [service ls](../reference/commandline/service_ls.md)
+  * [service rm](../reference/commandline/service_rm.md)
+  * [service scale](../reference/commandline/service_scale.md)
+  * [service ps](../reference/commandline/service_ps.md)
+  * [service update](../reference/commandline/service_update.md)

content/engine/swarm/how-swarm-mode-works/nodes.md

@@ -6,35 +6,35 @@ aliases:
 - /engine/swarm/how-swarm-mode-works/
 ---
 
-Docker Engine 1.12 introduces swarm mode that enables you to create a
+Swarm mode lets you create a
 cluster of one or more Docker Engines called a swarm. A swarm consists
 of one or more nodes: physical or virtual machines running Docker
-Engine 1.12 or later in swarm mode.
+Engine.
 
-There are two types of nodes: [**managers**](#manager-nodes) and
-[**workers**](#worker-nodes).
+There are two types of nodes: [managers](#manager-nodes) and
+[workers](#worker-nodes).
 
 ![Swarm mode cluster](/engine/swarm/images/swarm-diagram.webp)
 
 If you haven't already, read through the
-[swarm mode overview](../index.md) and
+[Swarm mode overview](../index.md) and
 [key concepts](../key-concepts.md).
 
 ## Manager nodes
 
 Manager nodes handle cluster management tasks:
 
-* maintaining cluster state
-* scheduling services
-* serving swarm mode [HTTP API endpoints](../../api/index.md)
+* Maintaining cluster state
+* Scheduling services
+* Serving Swarm mode [HTTP API endpoints](../../api/index.md)
 
 Using a [Raft](https://raft.github.io/raft.pdf) implementation, the managers
 maintain a consistent internal state of the entire swarm and all the services
 running on it. For testing purposes it is OK to run a swarm with a single
 manager. If the manager in a single-manager swarm fails, your services
 continue to run, but you need to create a new cluster to recover.
 
-To take advantage of swarm mode's fault-tolerance features, Docker recommends
+To take advantage of Swarm mode's fault-tolerance features, we recommend
 you implement an odd number of nodes according to your organization's
 high-availability requirements. When you have multiple managers you can recover
 from the failure of a manager node without downtime.
@@ -45,8 +45,11 @@ manager nodes.
 * An odd number `N` of manager nodes in the cluster tolerates the loss of at most `(N-1)/2` managers.
 Docker recommends a maximum of seven manager nodes for a swarm.
 
-    >**Important Note**: Adding more managers does NOT mean increased
-    scalability or higher performance. In general, the opposite is true.
+    >**Important**
+    >
+    > Adding more managers does NOT mean increased
+    > scalability or higher performance. In general, the opposite is true.
+    { .important }
 
 ## Worker nodes
 
@@ -57,7 +60,7 @@ state, make scheduling decisions, or serve the swarm mode HTTP API.
 You can create a swarm of one manager node, but you cannot have a worker node
 without at least one manager node. By default, all managers are also workers.
 In a single manager node cluster, you can run commands like `docker service
-create` and the scheduler places all tasks on the local Engine.
+create` and the scheduler places all tasks on the local engine.
 
 To prevent the scheduler from placing tasks on a manager node in a multi-node
 swarm, set the availability for the manager node to `Drain`. The scheduler
@@ -80,5 +83,5 @@ You can also demote a manager node to a worker node. See
 
 ## Learn more
 
-* Read about how swarm mode [services](services.md) work.
-* Learn how [PKI](pki.md) works in swarm mode.
+* Read about how Swarm mode [services](services.md) work.
+* Learn how [PKI](pki.md) works in Swarm mode.

content/engine/swarm/how-swarm-mode-works/pki.md

@@ -4,7 +4,7 @@ keywords: swarm, security, tls, pki,
 title: Manage swarm security with public key infrastructure (PKI)
 ---
 
-The swarm mode public key infrastructure (PKI) system built into Docker
+The Swarm mode public key infrastructure (PKI) system built into Docker
 makes it simple to securely deploy a container orchestration system. The nodes
 in a swarm use mutual Transport Layer Security (TLS) to authenticate, authorize,
 and encrypt the communications with other nodes in the swarm.
@@ -17,7 +17,7 @@ externally-generated root CA, using the `--external-ca` flag of the
 [docker swarm init](../../reference/commandline/swarm_init.md) command.
 
 The manager node also generates two tokens to use when you join additional nodes
-to the swarm: one **worker token** and one **manager token**. Each token
+to the swarm: one worker token and one manager token. Each token
 includes the digest of the root CA's certificate and a randomly generated
 secret. When a node joins the swarm, the joining node uses the digest to
 validate the root CA certificate from the remote manager. The remote manager
@@ -103,4 +103,4 @@ root CA, and do not contain any intermediates.
 ## Learn More
 
 * Read about how [nodes](nodes.md) work.
-* Learn how swarm mode [services](services.md) work.
+* Learn how Swarm mode [services](services.md) work.

content/engine/swarm/how-swarm-mode-works/services.md

@@ -4,7 +4,7 @@ keywords: docker, container, cluster, swarm mode, node
 title: How services work
 ---
 
-To deploy an application image when Docker Engine is in swarm mode, you create a
+To deploy an application image when Docker Engine is in Swarm mode, you create a
 service. Frequently a service is 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
@@ -14,11 +14,11 @@ 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 makes the service available outside the swarm
-* an overlay network for the service to connect to other services in the swarm
+* The port where the swarm makes 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
+* A rolling update policy
+* The number of replicas of the image to run in the swarm
 
 ## Services, tasks, and containers
 
@@ -33,7 +33,7 @@ Each of the three instances of the listener is a task in the swarm.
 
 ![ HTTP listener service with three replicas](../images/services-diagram.webp?w=550)
 
-A container is an isolated process. In the swarm mode model, each task invokes
+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
@@ -56,14 +56,14 @@ series of states: assigned, prepared, running, etc. If the task fails, the
 orchestrator 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
+The underlying logic of Docker's 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 the type of the task. However, the
 current version of Docker only supports container tasks.
 
-The diagram below shows how swarm mode accepts service create requests and
+The diagram below shows how Swarm mode accepts service create requests and
 schedules tasks to worker nodes.
 
 ![Services flow](../images/service-lifecycle.webp?w=700)
@@ -74,9 +74,11 @@ A service may be configured in such a way that no node currently in the
 swarm can run its tasks. In this case, the service remains in state `pending`.
 Here are a few examples of when a service might remain in state `pending`.
 
-> **Note**: If your only intention is to prevent a service from
-being deployed, scale the service to 0 instead of trying to configure it in
-such a way that it remains in `pending`.
+> **Tip**
+> If your only intention is to prevent a service from
+> being deployed, scale the service to 0 instead of trying to configure it in
+> such a way that it remains in `pending`.
+{ .tip }
 
 - If all nodes are paused or drained, and you create a service, it is
   pending until a node becomes available. In reality, the first node to become
@@ -119,5 +121,5 @@ in black.
 
 ## Learn more
 
-* Read about how swarm mode [nodes](nodes.md) work.
-* Learn how [PKI](pki.md) works in swarm mode.
+* Read about how Swarm mode [nodes](nodes.md) work.
+* Learn how [PKI](pki.md) works in Swarm mode.