From 9970f81c0d2f258ce2f1b8043ebfa0eeec1fc8c1 Mon Sep 17 00:00:00 2001 From: Allie Sadler <102604716+aevesdocker@users.noreply.github.com> Date: Thu, 14 Dec 2023 09:15:29 +0000 Subject: [PATCH] Engdocs 1912b - freshness (#18914) * swarm tutorial and concepts * how swarm works * review edits --- content/engine/swarm/_index.md | 83 ++++++++++--------- .../swarm/how-swarm-mode-works/nodes.md | 31 +++---- .../engine/swarm/how-swarm-mode-works/pki.md | 6 +- .../swarm/how-swarm-mode-works/services.md | 28 ++++--- content/engine/swarm/ingress.md | 24 +++--- content/engine/swarm/key-concepts.md | 44 +++++----- content/engine/swarm/swarm-tutorial/_index.md | 42 +++++----- .../engine/swarm/swarm-tutorial/add-nodes.md | 7 +- .../swarm/swarm-tutorial/create-swarm.md | 11 +-- .../swarm/swarm-tutorial/delete-service.md | 9 +- .../swarm/swarm-tutorial/deploy-service.md | 8 +- .../engine/swarm/swarm-tutorial/drain-node.md | 24 +++--- .../swarm/swarm-tutorial/inspect-service.md | 19 +++-- .../swarm/swarm-tutorial/rolling-update.md | 6 +- .../swarm/swarm-tutorial/scale-service.md | 11 +-- data/toc.yaml | 8 +- 16 files changed, 197 insertions(+), 164 deletions(-) diff --git a/content/engine/swarm/_index.md b/content/engine/swarm/_index.md index 43e630b4c0..6f5612ed2d 100644 --- a/content/engine/swarm/_index.md +++ b/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,27 +57,34 @@ 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 @@ -88,46 +92,49 @@ 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) \ No newline at end of file +* 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) \ No newline at end of file diff --git a/content/engine/swarm/how-swarm-mode-works/nodes.md b/content/engine/swarm/how-swarm-mode-works/nodes.md index 113b2eba60..c9b0423e5c 100644 --- a/content/engine/swarm/how-swarm-mode-works/nodes.md +++ b/content/engine/swarm/how-swarm-mode-works/nodes.md @@ -6,27 +6,27 @@ 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 @@ -34,7 +34,7 @@ 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. \ No newline at end of file +* Read about how Swarm mode [services](services.md) work. +* Learn how [PKI](pki.md) works in Swarm mode. \ No newline at end of file diff --git a/content/engine/swarm/how-swarm-mode-works/pki.md b/content/engine/swarm/how-swarm-mode-works/pki.md index c8998fb7d3..143a21f21a 100644 --- a/content/engine/swarm/how-swarm-mode-works/pki.md +++ b/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. \ No newline at end of file +* Learn how Swarm mode [services](services.md) work. \ No newline at end of file diff --git a/content/engine/swarm/how-swarm-mode-works/services.md b/content/engine/swarm/how-swarm-mode-works/services.md index 51861666b7..81a854126d 100644 --- a/content/engine/swarm/how-swarm-mode-works/services.md +++ b/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. \ No newline at end of file +* Read about how Swarm mode [nodes](nodes.md) work. +* Learn how [PKI](pki.md) works in Swarm mode. \ No newline at end of file diff --git a/content/engine/swarm/ingress.md b/content/engine/swarm/ingress.md index d3f42de723..132da6fef7 100644 --- a/content/engine/swarm/ingress.md +++ b/content/engine/swarm/ingress.md @@ -1,18 +1,18 @@ --- description: Use the routing mesh to publish services externally to a swarm keywords: guide, swarm mode, swarm, network, ingress, routing mesh -title: Use swarm mode routing mesh +title: Use Swarm mode routing mesh --- -Docker Engine swarm mode makes it easy to publish ports for services to make +Docker Engine Swarm mode makes it easy to publish ports for services to make them available to resources outside the swarm. All nodes participate in an -ingress **routing mesh**. The routing mesh enables each node in the swarm to +ingress routing mesh. The routing mesh enables each node in the swarm to accept connections on published ports for any service running in the swarm, even if there's no task running on the node. The routing mesh routes all incoming requests to published ports on available nodes to an active container. To use the ingress network in the swarm, you need to have the following -ports open between the swarm nodes before you enable swarm mode: +ports open between the swarm nodes before you enable Swarm mode: * Port `7946` TCP/UDP for container network discovery. * Port `4789` UDP (configurable) for the container ingress network. @@ -42,7 +42,9 @@ $ docker service create \ ``` -> **Note**: The older form of this syntax is a colon-separated string, where +> **Note** +> +> The older form of this syntax is a colon-separated string, where > the published port is first and the target port is second, such as > `-p 8080:80`. The new syntax is preferred because it is easier to read and > allows more flexibility. @@ -107,7 +109,7 @@ set the `protocol` key to either `tcp` or `udp`. #### TCP only -**Long syntax:** +Long syntax: ```console $ docker service create --name dns-cache \ @@ -115,7 +117,7 @@ $ docker service create --name dns-cache \ dns-cache ``` -**Short syntax:** +Short syntax: ```console $ docker service create --name dns-cache \ @@ -125,7 +127,7 @@ $ docker service create --name dns-cache \ #### TCP and UDP -**Long syntax:** +Long syntax: ```console $ docker service create --name dns-cache \ @@ -134,7 +136,7 @@ $ docker service create --name dns-cache \ dns-cache ``` -**Short syntax:** +Short syntax: ```console $ docker service create --name dns-cache \ @@ -145,7 +147,7 @@ $ docker service create --name dns-cache \ #### UDP only -**Long syntax:** +Long syntax: ```console $ docker service create --name dns-cache \ @@ -153,7 +155,7 @@ $ docker service create --name dns-cache \ dns-cache ``` -**Short syntax:** +Short syntax: ```console $ docker service create --name dns-cache \ diff --git a/content/engine/swarm/key-concepts.md b/content/engine/swarm/key-concepts.md index 980265bb13..830d484153 100644 --- a/content/engine/swarm/key-concepts.md +++ b/content/engine/swarm/key-concepts.md @@ -1,6 +1,6 @@ --- description: Introducing key concepts for Docker Engine swarm mode -keywords: docker, container, cluster, swarm mode +keywords: docker, container, cluster, swarm mode, docker engine title: Swarm mode key concepts --- @@ -9,19 +9,19 @@ orchestration features of Docker Engine 1.12. ## What is a swarm? -The cluster management and orchestration features embedded in the Docker Engine +The cluster management and orchestration features embedded in Docker Engine are built using [swarmkit](https://github.com/docker/swarmkit/). Swarmkit is a separate project which implements Docker's orchestration layer and is used directly within Docker. -A swarm consists of multiple Docker hosts which run in **swarm mode** and act as -managers (to manage membership and delegation) and workers (which run -[swarm services](#services-and-tasks)). A given Docker host can +A swarm consists of multiple Docker hosts which run in Swarm mode and act as +managers, to manage membership and delegation, and workers, which run +[swarm services](#services-and-tasks). A given Docker host can be a manager, a worker, or perform both roles. When you create a service, you -define its optimal state (number of replicas, network and storage resources -available to it, ports the service exposes to the outside world, and more). +define its optimal state - number of replicas, network and storage resources +available to it, ports the service exposes to the outside world, and more. Docker works to maintain that desired state. For instance, if a worker node -becomes unavailable, Docker schedules that node's tasks on other nodes. A _task_ +becomes unavailable, Docker schedules that node's tasks on other nodes. A task is a running container which is part of a swarm service and is managed by a swarm manager, as opposed to a standalone container. @@ -31,7 +31,7 @@ is connected to, without the need to manually restart the service. Docker will update the configuration, stop the service tasks with out of date configuration, and create new ones matching the desired configuration. -When Docker is running in swarm mode, you can still run standalone containers +When Docker is running in Swarm mode, you can still run standalone containers on any of the Docker hosts participating in the swarm, as well as swarm services. A key difference between standalone containers and swarm services is that only swarm managers can manage a swarm, while standalone containers can be @@ -46,17 +46,17 @@ including nodes, services, tasks, and load balancing. ## Nodes -A **node** is an instance of the Docker engine participating in the swarm. You can also think of this as a Docker node. You can run one or more nodes on a single physical computer or cloud server, but production swarm deployments typically include Docker nodes distributed across multiple physical and cloud machines. +A node is an instance of the Docker engine participating in the swarm. You can also think of this as a Docker node. You can run one or more nodes on a single physical computer or cloud server, but production swarm deployments typically include Docker nodes distributed across multiple physical and cloud machines. To deploy your application to a swarm, you submit a service definition to a -**manager node**. The manager node dispatches units of work called +manager node*. The manager node dispatches units of work called [tasks](#services-and-tasks) to worker nodes. Manager nodes also perform the orchestration and cluster management functions required to maintain the desired state of the swarm. Manager nodes elect a single leader to conduct orchestration tasks. -**Worker nodes** receive and execute tasks dispatched from manager nodes. +Worker nodes receive and execute tasks dispatched from manager nodes. By default manager nodes also run services as worker nodes, but you can configure them to run manager tasks exclusively and be manager-only nodes. An agent runs on each worker node and reports on the tasks assigned to @@ -66,21 +66,21 @@ worker. ## Services and tasks -A **service** is the definition of the tasks to execute on the manager or worker nodes. It +A service is the definition of the tasks to execute on the manager or worker nodes. It is the central structure of the swarm system and the primary root of user interaction with the swarm. When you create a service, you specify which container image to use and which commands to execute inside running containers. -In the **replicated services** model, the swarm manager distributes a specific +In the replicated services model, the swarm manager distributes a specific number of replica tasks among the nodes based upon the scale you set in the desired state. -For **global services**, the swarm runs one task for the service on every +For global services, the swarm runs one task for the service on every available node in the cluster. -A **task** carries a Docker container and the commands to run inside the +A task carries a Docker container and the commands to run inside the container. It is the atomic scheduling unit of swarm. Manager nodes assign tasks to worker nodes according to the number of replicas set in the service scale. Once a task is assigned to a node, it cannot move to another node. It can only @@ -88,20 +88,20 @@ run on the assigned node or fail. ## Load balancing -The swarm manager uses **ingress load balancing** to expose the services you +The swarm manager uses ingress load balancing to expose the services you want to make available externally to the swarm. The swarm manager can -automatically assign the service a **PublishedPort** or you can configure a -PublishedPort for the service. You can specify any unused port. If you do not +automatically assign the service a published port or you can configure a +published port for the service. You can specify any unused port. If you do not specify a port, the swarm manager assigns the service a port 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 whether or not the node is currently -running the task for the service. All nodes in the swarm route ingress +published port of any node in the cluster whether or not the node is currently +running the task for the service. All nodes in the swarm route ingress connections to a running task instance. Swarm mode has an internal DNS component that automatically assigns each service -in the swarm a DNS entry. The swarm manager uses **internal load balancing** to +in the swarm a DNS entry. The swarm manager uses internal load balancing to distribute requests among services within the cluster based upon the DNS name of the service. diff --git a/content/engine/swarm/swarm-tutorial/_index.md b/content/engine/swarm/swarm-tutorial/_index.md index b19f0c9b45..48e9ddd7ae 100644 --- a/content/engine/swarm/swarm-tutorial/_index.md +++ b/content/engine/swarm/swarm-tutorial/_index.md @@ -1,7 +1,7 @@ --- -description: Getting Started tutorial for Docker Engine swarm mode -keywords: tutorial, cluster management, swarm mode -title: Getting started with swarm mode +description: Getting Started tutorial for Docker Engine Swarm mode +keywords: tutorial, cluster management, swarm mode, docker engine, get started +title: Getting started with Swarm mode toc_max: 4 --- @@ -9,12 +9,12 @@ This tutorial introduces you to the features of Docker Engine Swarm mode. You may want to familiarize yourself with the [key concepts](../key-concepts.md) before you begin. -The tutorial guides you through the following activities: +The tutorial guides you through: -* initializing a cluster of Docker Engines in swarm mode -* adding nodes to the swarm -* deploying application services to the swarm -* managing the swarm once you have everything running +* Initializing a cluster of Docker Engines in swarm mode +* 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. @@ -23,11 +23,11 @@ If you are brand new to Docker, see [About Docker Engine](../../index.md). ## Set up -To run this tutorial, you need the following: +To run this tutorial, you need: -* [three Linux hosts which can communicate over a network, with Docker installed](#three-networked-host-machines) -* [the IP address of the manager machine](#the-ip-address-of-the-manager-machine) -* [open ports between the hosts](#open-protocols-and-ports-between-the-hosts) +* [Three Linux hosts which can communicate over a network, with Docker installed](#three-networked-host-machines) +* [The IP address of the manager machine](#the-ip-address-of-the-manager-machine) +* [Open ports between the hosts](#open-protocols-and-ports-between-the-hosts) ### Three networked host machines @@ -40,11 +40,11 @@ for one possible set-up for the hosts. One of these machines is a manager (called `manager1`) and two of them are workers (`worker1` and `worker2`). - ->**Note**: You can follow many of the tutorial steps to test single-node swarm -as well, in which case you need only one host. Multi-node commands do not -work, but you can initialize a swarm, create services, and scale them. - +>**Note** +> +> You can follow many of the tutorial steps to test single-node swarm +> as well, in which case you need only one host. Multi-node commands do not +> work, but you can initialize a swarm, create services, and scale them. #### Install Docker Engine on Linux machines @@ -76,7 +76,7 @@ The following ports must be available. On some systems, these ports are open by * Port `4789` UDP (configurable) for overlay network traffic If you plan on creating an overlay network with encryption (`--opt encrypted`), -you also need to ensure **IP protocol 50** (**IPSec ESP**) traffic is allowed. +you also need to ensure IP protocol 50 (IPSec ESP) traffic is allowed. Port `4789` is the default value for the Swarm data path port, also known as the VXLAN port. It is important to prevent any untrusted traffic from reaching this port, as VXLAN does not @@ -95,6 +95,8 @@ additional hardening is suggested: iptables -I INPUT -m udp --dport 4789 -m policy --dir in --pol none -j DROP ``` -## What's next? +## Next steps -After you have set up your environment, you are ready to [create a swarm](create-swarm.md). +Next, you'll create a swarm. + +{{< button text="Create a swarm" url="create-swarm.md" >}} diff --git a/content/engine/swarm/swarm-tutorial/add-nodes.md b/content/engine/swarm/swarm-tutorial/add-nodes.md index 81c56959c2..f77411d755 100644 --- a/content/engine/swarm/swarm-tutorial/add-nodes.md +++ b/content/engine/swarm/swarm-tutorial/add-nodes.md @@ -1,6 +1,6 @@ --- description: Add nodes to the swarm -keywords: tutorial, cluster management, swarm +keywords: tutorial, cluster management, swarm, get started title: Add nodes to the swarm notoc: true --- @@ -70,5 +70,6 @@ to add worker 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. \ No newline at end of file +Now your swarm consists of a manager and two worker nodes. Next, you'll deploy a service. + +{{< button text="Deploy a service" url="deploy-service.md" >}} diff --git a/content/engine/swarm/swarm-tutorial/create-swarm.md b/content/engine/swarm/swarm-tutorial/create-swarm.md index bafcc1ea65..dcf5ca5f33 100644 --- a/content/engine/swarm/swarm-tutorial/create-swarm.md +++ b/content/engine/swarm/swarm-tutorial/create-swarm.md @@ -1,6 +1,6 @@ --- description: Initialize the swarm -keywords: tutorial, cluster management, swarm mode +keywords: tutorial, cluster management, swarm mode, get started, docker engine title: Create a swarm notoc: true --- @@ -73,10 +73,11 @@ machines. The `*` next to the node ID indicates that you're currently connected on this node. - Docker Engine swarm mode automatically names the node with the machine host + Docker Engine Swarm mode automatically names the node with the machine host name. The tutorial covers other columns in later steps. -## What's next? +## Next steps -In the next section of the tutorial, we [add two more nodes](add-nodes.md) to -the cluster. \ No newline at end of file +Next, you'll add two more nodes to the cluster. + +{{< button text="Add two more nodes" url="add-nodes.md" >}} diff --git a/content/engine/swarm/swarm-tutorial/delete-service.md b/content/engine/swarm/swarm-tutorial/delete-service.md index f8336dbcf7..ff3b71bd36 100644 --- a/content/engine/swarm/swarm-tutorial/delete-service.md +++ b/content/engine/swarm/swarm-tutorial/delete-service.md @@ -1,6 +1,6 @@ --- description: Remove the service from the swarm -keywords: tutorial, cluster management, swarm, service +keywords: tutorial, cluster management, swarm, service, get started title: Delete the service running on the swarm notoc: true --- @@ -49,7 +49,8 @@ you can delete the service from the swarm. ``` -## What's next? +## Next steps -In the next step of the tutorial, you set up a new service and apply a -[rolling update](rolling-update.md). \ No newline at end of file +Next, you'll set up a new service and apply a rolling update. + +{{< button text="Apply rolling updates" url="rolling-update.md" >}} diff --git a/content/engine/swarm/swarm-tutorial/deploy-service.md b/content/engine/swarm/swarm-tutorial/deploy-service.md index 962a0184fd..9fb69b8057 100644 --- a/content/engine/swarm/swarm-tutorial/deploy-service.md +++ b/content/engine/swarm/swarm-tutorial/deploy-service.md @@ -1,6 +1,6 @@ --- description: Deploy a service to the swarm -keywords: tutorial, cluster management, swarm mode +keywords: tutorial, cluster management, swarm mode, get started title: Deploy a service to the swarm notoc: true --- @@ -35,6 +35,8 @@ is not a requirement to deploy a service. 9uk4639qpg7n helloworld 1/1 alpine ping docker.com ``` -## What's next? +## Next steps -Now you've deployed a service to the swarm, you're ready to [inspect the service](inspect-service.md). \ No newline at end of file +Now you're ready to inspect the service. + +{{< button text="Deploy a service" url="inspect-service.md" >}} diff --git a/content/engine/swarm/swarm-tutorial/drain-node.md b/content/engine/swarm/swarm-tutorial/drain-node.md index 995231d6cf..8adb354b7d 100644 --- a/content/engine/swarm/swarm-tutorial/drain-node.md +++ b/content/engine/swarm/swarm-tutorial/drain-node.md @@ -1,24 +1,24 @@ --- description: Drain nodes on the swarm -keywords: tutorial, cluster management, swarm, service, drain +keywords: tutorial, cluster management, swarm, service, drain, get started title: Drain a node on the swarm notoc: true --- -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 up to +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 up to now all nodes have been available to receive tasks. -Sometimes, such as planned maintenance times, you need to set a node to `DRAIN` -availability. `DRAIN` availability prevents a node from receiving new tasks +Sometimes, such as planned maintenance times, you need to set a node to `Drain` +availability. `Drain` availability 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. +node and launches replica tasks on a node with `Active` availability. > **Important**: > -> Setting a node to `DRAIN` does not remove standalone containers from that node, +> Setting a node to `Drain` does not remove standalone containers from that node, > such as those created with `docker run`, `docker compose up`, or the Docker Engine -> API. A node's status, including `DRAIN`, only affects the node's ability to schedule +> API. A node's status, including `Drain`, only affects the node's ability to schedule > swarm service workloads. { .important } @@ -83,7 +83,7 @@ had a task assigned to it: ...snip... ``` - The drained node shows `Drain` for `AVAILABILITY`. + The drained node shows `Drain` for `Availability`. 7. Run `docker service ps redis` to see how the swarm manager updated the task assignments for the `redis` service: @@ -131,6 +131,8 @@ drained node to an active state: * when you set another node to `Drain` availability * when a task fails on another active node -## What's next? +## Next steps -Learn how to [use a swarm mode routing mesh](../ingress.md). \ No newline at end of file +Next, you'll learn how to use a Swarm mode routing mesh + +{{< button text="Use a Swarm mode routing mesh" url="../ingress.md" >}} diff --git a/content/engine/swarm/swarm-tutorial/inspect-service.md b/content/engine/swarm/swarm-tutorial/inspect-service.md index 6351a9e2e4..3f14e56d79 100644 --- a/content/engine/swarm/swarm-tutorial/inspect-service.md +++ b/content/engine/swarm/swarm-tutorial/inspect-service.md @@ -1,6 +1,6 @@ --- description: Inspect the application -keywords: tutorial, cluster management, swarm mode +keywords: tutorial, cluster management, swarm mode, get started title: Inspect a service on the swarm notoc: true --- @@ -34,8 +34,11 @@ the Docker CLI to see details about the service running in the swarm. Endpoint Mode: vip ``` - >**Tip**: To return the service details in json format, run the same command + >**Tip** + > + > To return the service details in json format, run the same command without the `--pretty` flag. + { .tip } ```console [manager1]$ docker service inspect helloworld @@ -107,8 +110,11 @@ the Docker CLI to see details about the service running in the swarm. 4. Run `docker ps` on the node where the task is running to see details about the container for the task. - >**Tip**: If `helloworld` is running on a node other than your manager node, + >**Tip** + > + > If `helloworld` is running on a node other than your manager node, you must ssh to that node. + { .tip } ```console [worker2]$ docker ps @@ -117,7 +123,8 @@ the Docker CLI to see details about the service running in the swarm. e609dde94e47 alpine:latest "ping docker.com" 3 minutes ago Up 3 minutes helloworld.1.8p1vev3fq5zm0mi8g0as41w35 ``` -## What's next? +## Next steps -Next, you can [change the scale](scale-service.md) for the service running in -the swarm. \ No newline at end of file +Next, you'll change the scale for the service running in the swarm. + +{{< button text="Change the scale" url="scale-service.md" >}} diff --git a/content/engine/swarm/swarm-tutorial/rolling-update.md b/content/engine/swarm/swarm-tutorial/rolling-update.md index 94dd74e2e1..246718b564 100644 --- a/content/engine/swarm/swarm-tutorial/rolling-update.md +++ b/content/engine/swarm/swarm-tutorial/rolling-update.md @@ -146,6 +146,8 @@ Redis 3.0.7 container image using rolling updates. `redis:3.0.6` while others are running `redis:3.0.7`. The output above shows the state once the rolling updates are done. -## What's next? +## Next steps -Next, learn about how to [drain a node](drain-node.md) in the swarm. \ No newline at end of file +Next, you'll learn how to drain a node in the swarm. + +{{< button text="Drain a node" url="drain-node.md" >}} diff --git a/content/engine/swarm/swarm-tutorial/scale-service.md b/content/engine/swarm/swarm-tutorial/scale-service.md index 66bc4cf1f8..b146684f2e 100644 --- a/content/engine/swarm/swarm-tutorial/scale-service.md +++ b/content/engine/swarm/swarm-tutorial/scale-service.md @@ -1,13 +1,13 @@ --- description: Scale the service running in the swarm -keywords: tutorial, cluster management, swarm mode, scale +keywords: tutorial, cluster management, swarm mode, scale, get started title: Scale the service in the swarm notoc: true --- 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 containers in -the service. Containers running in a service are called "tasks." +the service. Containers running in a service are called tasks. 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 @@ -58,7 +58,8 @@ the service. Containers running in a service are called "tasks." If you want to see the containers running on other nodes, ssh into those nodes and run the `docker ps` command. -## What's next? +## Next steps -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). \ No newline at end of file +At this point in the tutorial, you're finished with the `helloworld` service. Next, you'll delete the service + +{{< button text="Delete the service" url="delete-service.md" >}} \ No newline at end of file diff --git a/data/toc.yaml b/data/toc.yaml index 303999e4c1..a4f88e25d8 100644 --- a/data/toc.yaml +++ b/data/toc.yaml @@ -1645,8 +1645,8 @@ Manuals: - path: /engine/swarm/swarm-tutorial/drain-node/ title: Drain a node - path: /engine/swarm/ingress/ - title: Use swarm mode routing mesh - - sectiontitle: How swarm mode works + title: Use Swarm mode routing mesh + - sectiontitle: How Swarm mode works section: - path: /engine/swarm/how-swarm-mode-works/nodes/ title: How nodes work @@ -1657,7 +1657,7 @@ Manuals: - path: /engine/swarm/how-swarm-mode-works/swarm-task-states/ title: Swarm task states - path: /engine/swarm/swarm-mode/ - title: Run Docker in swarm mode + title: Run Docker in Swarm mode - path: /engine/swarm/join-nodes/ title: Join nodes to a swarm - path: /engine/swarm/manage-nodes/ @@ -1677,7 +1677,7 @@ Manuals: - path: /engine/swarm/admin_guide/ title: Swarm administration guide - path: /engine/swarm/raft/ - title: Raft consensus in swarm mode + title: Raft consensus in Swarm mode - sectiontitle: Advanced concepts section: - sectiontitle: Container runtime