docker
/
docs
mirror of https://github.com/docker/docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Engdocs 1912b - freshness (#18914) 

* swarm tutorial and concepts

* how swarm works

* review edits
This commit is contained in:
Allie Sadler 2023-12-14 09:15:29 +00:00 committed by GitHub
parent b828c661f1
commit 9970f81c0d
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
16 changed files with 197 additions and 164 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

83
content/engine/swarm/_index.md
View File

@ -1,6 +1,6 @@
--- ---
description: Docker Engine swarm mode overview description: Docker Engine Swarm mode overview
keywords: docker, container, cluster, swarm keywords: docker, container, cluster, swarm, docker engine
title: Swarm mode overview title: Swarm mode overview
aliases: aliases:
- /api/swarm-api/ - /api/swarm-api/
@ -47,11 +47,8 @@ aliases:
{{< include "swarm-mode.md" >}} {{< include "swarm-mode.md" >}}
To use Docker in swarm mode, install Docker. See Current versions of Docker include Swarm mode for natively managing a cluster
[installation instructions](../../get-docker.md) for all operating systems and platforms. 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. application services to a swarm, and manage swarm behavior.
Docker Swarm mode is built into the Docker Engine. Do not confuse Docker Swarm mode 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 ## Feature highlights
* **Cluster management integrated with Docker Engine:** Use the Docker Engine ### Cluster management integrated with Docker Engine
CLI to create a swarm of Docker Engines where you can deploy application
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 services. You don't need additional orchestration software to create or manage
a swarm. a swarm.
* **Decentralized design:** Instead of handling differentiation between node ### Decentralized design
roles at deployment time, the Docker Engine handles any specialization at
runtime. You can deploy both kinds of nodes, managers and workers, using the 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 Docker Engine. This means you can build an entire swarm from a single disk
image. 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 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 stack. For example, you might describe an application comprised of a web front
end service with message queueing services and a database backend. 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 run. When you scale up or down, the swarm manager automatically adapts by
adding or removing tasks to maintain the desired state. 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 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 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 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 crashed. The swarm manager assigns the new replicas to workers that are
running and available. 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 services. The swarm manager automatically assigns addresses to the containers
on the overlay network when it initializes or updates the application. 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 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. 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 external load balancer. Internally, the swarm lets you specify how to distribute
service containers between nodes. 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 authentication and encryption to secure communications between itself and all
other nodes. You have the option to use self-signed root certificates or other nodes. You have the option to use self-signed root certificates or
certificates from a custom root CA. 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 incrementally. The swarm manager lets you control the delay between service
deployment to different sets of nodes. If anything goes wrong, you can deployment to different sets of nodes. If anything goes wrong, you can
roll back to a previous version of the service. roll back to a previous version of the service.
## What's next? ## 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). * Get started with the [Swarm mode tutorial](swarm-tutorial/index.md).
* Explore Swarm mode CLI commands
### Swarm mode CLI commands * [swarm init](../reference/commandline/swarm_init.md)
* [swarm join](../reference/commandline/swarm_join.md)
Explore swarm mode CLI commands * [service create](../reference/commandline/service_create.md)
* [service inspect](../reference/commandline/service_inspect.md)
* [swarm init](../reference/commandline/swarm_init.md) * [service ls](../reference/commandline/service_ls.md)
* [swarm join](../reference/commandline/swarm_join.md) * [service rm](../reference/commandline/service_rm.md)
* [service create](../reference/commandline/service_create.md) * [service scale](../reference/commandline/service_scale.md)
* [service inspect](../reference/commandline/service_inspect.md) * [service ps](../reference/commandline/service_ps.md)
* [service ls](../reference/commandline/service_ls.md) * [service update](../reference/commandline/service_update.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)

31
content/engine/swarm/how-swarm-mode-works/nodes.md
View File

@ -6,27 +6,27 @@ aliases:
- /engine/swarm/how-swarm-mode-works/ - /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 cluster of one or more Docker Engines called a swarm. A swarm consists
of one or more nodes: physical or virtual machines running Docker 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 There are two types of nodes: [managers](#manager-nodes) and
[**workers**](#worker-nodes). [workers](#worker-nodes).
![Swarm mode cluster](/engine/swarm/images/swarm-diagram.webp) ![Swarm mode cluster](/engine/swarm/images/swarm-diagram.webp)
If you haven't already, read through the 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). [key concepts](../key-concepts.md).
## Manager nodes ## Manager nodes
Manager nodes handle cluster management tasks: Manager nodes handle cluster management tasks:
* maintaining cluster state * Maintaining cluster state
* scheduling services * Scheduling services
* serving swarm mode [HTTP API endpoints](../../api/index.md) * Serving Swarm mode [HTTP API endpoints](../../api/index.md)
Using a [Raft](https://raft.github.io/raft.pdf) implementation, the managers 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 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 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. 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 you implement an odd number of nodes according to your organization's
high-availability requirements. When you have multiple managers you can recover high-availability requirements. When you have multiple managers you can recover
from the failure of a manager node without downtime. 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. * 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. Docker recommends a maximum of seven manager nodes for a swarm.
>**Important Note**: Adding more managers does NOT mean increased >**Important**
scalability or higher performance. In general, the opposite is true. >
> Adding more managers does NOT mean increased
> scalability or higher performance. In general, the opposite is true.
{ .important }
## Worker nodes ## 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 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. 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 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 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 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 ## Learn more
* Read about how swarm mode [services](services.md) work. * Read about how Swarm mode [services](services.md) work.
* Learn how [PKI](pki.md) works in swarm mode. * Learn how [PKI](pki.md) works in Swarm mode.

6
content/engine/swarm/how-swarm-mode-works/pki.md
View File

@ -4,7 +4,7 @@ keywords: swarm, security, tls, pki,
title: Manage swarm security with public key infrastructure (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 makes it simple to securely deploy a container orchestration system. The nodes
in a swarm use mutual Transport Layer Security (TLS) to authenticate, authorize, in a swarm use mutual Transport Layer Security (TLS) to authenticate, authorize,
and encrypt the communications with other nodes in the swarm. 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. [docker swarm init](../../reference/commandline/swarm_init.md) command.
The manager node also generates two tokens to use when you join additional nodes 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 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 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 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 ## Learn More
* Read about how [nodes](nodes.md) work. * Read about how [nodes](nodes.md) work.
* Learn how swarm mode [services](services.md) work. * Learn how Swarm mode [services](services.md) work.

28
content/engine/swarm/how-swarm-mode-works/services.md
View File

@ -4,7 +4,7 @@ keywords: docker, container, cluster, swarm mode, node
title: How services work 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 service. Frequently a service is the image for a microservice within the
context of some larger application. Examples of services might include an HTTP 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 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 commands to execute inside running containers. You also define options for the
service including: service including:
* the port where the swarm makes the service available outside 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 * An overlay network for the service to connect to other services in the swarm
* CPU and memory limits and reservations * CPU and memory limits and reservations
* a rolling update policy * A rolling update policy
* the number of replicas of the image to run in the swarm * The number of replicas of the image to run in the swarm
## Services, tasks, and containers ## 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) ![ 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 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 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 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 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. 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 orchestrator. The service and task abstractions themselves are unaware of the
containers they implement. Hypothetically, you could implement other types of containers they implement. Hypothetically, you could implement other types of
tasks such as virtual machine tasks or non-containerized process tasks. The 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 scheduler and orchestrator are agnostic about the type of the task. However, the
current version of Docker only supports container tasks. 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. schedules tasks to worker nodes.
![Services flow](../images/service-lifecycle.webp?w=700) ![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`. 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`. 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 > **Tip**
being deployed, scale the service to 0 instead of trying to configure it in > If your only intention is to prevent a service from
such a way that it remains in `pending`. > 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 - 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 pending until a node becomes available. In reality, the first node to become
@ -119,5 +121,5 @@ in black.
## Learn more ## Learn more
* Read about how swarm mode [nodes](nodes.md) work. * Read about how Swarm mode [nodes](nodes.md) work.
* Learn how [PKI](pki.md) works in swarm mode. * Learn how [PKI](pki.md) works in Swarm mode.

24
content/engine/swarm/ingress.md
View File

@ -1,18 +1,18 @@
--- ---
description: Use the routing mesh to publish services externally to a swarm description: Use the routing mesh to publish services externally to a swarm
keywords: guide, swarm mode, swarm, network, ingress, routing mesh 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 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 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 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. 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 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 `7946` TCP/UDP for container network discovery.
* Port `4789` UDP (configurable) for the container ingress network. * Port `4789` UDP (configurable) for the container ingress network.
@ -42,7 +42,9 @@ $ docker service create \
<IMAGE> <IMAGE>
``` ```
> **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 > 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 > `-p 8080:80`. The new syntax is preferred because it is easier to read and
> allows more flexibility. > allows more flexibility.
@ -107,7 +109,7 @@ set the `protocol` key to either `tcp` or `udp`.
#### TCP only #### TCP only
**Long syntax:** Long syntax:
```console ```console
$ docker service create --name dns-cache \ $ docker service create --name dns-cache \
@ -115,7 +117,7 @@ $ docker service create --name dns-cache \
dns-cache dns-cache
``` ```
**Short syntax:** Short syntax:
```console ```console
$ docker service create --name dns-cache \ $ docker service create --name dns-cache \
@ -125,7 +127,7 @@ $ docker service create --name dns-cache \
#### TCP and UDP #### TCP and UDP
**Long syntax:** Long syntax:
```console ```console
$ docker service create --name dns-cache \ $ docker service create --name dns-cache \
@ -134,7 +136,7 @@ $ docker service create --name dns-cache \
dns-cache dns-cache
``` ```
**Short syntax:** Short syntax:
```console ```console
$ docker service create --name dns-cache \ $ docker service create --name dns-cache \
@ -145,7 +147,7 @@ $ docker service create --name dns-cache \
#### UDP only #### UDP only
**Long syntax:** Long syntax:
```console ```console
$ docker service create --name dns-cache \ $ docker service create --name dns-cache \
@ -153,7 +155,7 @@ $ docker service create --name dns-cache \
dns-cache dns-cache
``` ```
**Short syntax:** Short syntax:
```console ```console
$ docker service create --name dns-cache \ $ docker service create --name dns-cache \

44
content/engine/swarm/key-concepts.md
View File

@ -1,6 +1,6 @@
--- ---
description: Introducing key concepts for Docker Engine swarm mode 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 title: Swarm mode key concepts
--- ---
@ -9,19 +9,19 @@ orchestration features of Docker Engine 1.12.
## What is a swarm? ## 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 are built using [swarmkit](https://github.com/docker/swarmkit/). Swarmkit is a
separate project which implements Docker's orchestration layer and is used separate project which implements Docker's orchestration layer and is used
directly within Docker. directly within Docker.
A swarm consists of multiple Docker hosts which run in **swarm mode** and act as 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 managers, to manage membership and delegation, and workers, which run
[swarm services](#services-and-tasks)). A given Docker host can [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 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 define its optimal state - number of replicas, network and storage resources
available to it, ports the service exposes to the outside world, and more). 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 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 is a running container which is part of a swarm service and is managed by a
swarm manager, as opposed to a standalone container. 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 update the configuration, stop the service tasks with out of date
configuration, and create new ones matching the desired configuration. 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 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 services. A key difference between standalone containers and swarm services is
that only swarm managers can manage a swarm, while standalone containers can be 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 ## 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 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. [tasks](#services-and-tasks) to worker nodes.
Manager nodes also perform the orchestration and cluster management functions Manager nodes also perform the orchestration and cluster management functions
required to maintain the desired state of the swarm. Manager nodes elect a required to maintain the desired state of the swarm. Manager nodes elect a
single leader to conduct orchestration tasks. 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 By default manager nodes also run services as worker nodes, but you can
configure them to run manager tasks exclusively and be manager-only 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 nodes. An agent runs on each worker node and reports on the tasks assigned to
@ -66,21 +66,21 @@ worker.
## Services and tasks ## 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 is the central structure of the swarm system and the primary root of user
interaction with the swarm. interaction with the swarm.
When you create a service, you specify which container image to use and which When you create a service, you specify which container image to use and which
commands to execute inside running containers. 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 number of replica tasks among the nodes based upon the scale you set in the
desired state. 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. 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 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. 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 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 ## 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 want to make available externally to the swarm. The swarm manager can
automatically assign the service a **PublishedPort** or you can configure a automatically assign the service a published port or you can configure a
PublishedPort for the service. You can specify any unused port. If you do not 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 specify a port, the swarm manager assigns the service a port in the 30000-32767
range. range.
External components, such as cloud load balancers, can access the service on the 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 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 running the task for the service. All nodes in the swarm route ingress
connections to a running task instance. connections to a running task instance.
Swarm mode has an internal DNS component that automatically assigns each service 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 distribute requests among services within the cluster based upon the DNS name of
the service. the service.

42
content/engine/swarm/swarm-tutorial/_index.md
View File

@ -1,7 +1,7 @@
--- ---
description: Getting Started tutorial for Docker Engine swarm mode description: Getting Started tutorial for Docker Engine Swarm mode
keywords: tutorial, cluster management, swarm mode keywords: tutorial, cluster management, swarm mode, docker engine, get started
title: Getting started with swarm mode title: Getting started with Swarm mode
toc_max: 4 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) may want to familiarize yourself with the [key concepts](../key-concepts.md)
before you begin. 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 * Initializing a cluster of Docker Engines in swarm mode
* adding nodes to the swarm * Adding nodes to the swarm
* deploying application services to the swarm * Deploying application services to the swarm
* managing the swarm once you have everything running * Managing the swarm once you have everything running
This tutorial uses Docker Engine CLI commands entered on the command line of a This tutorial uses Docker Engine CLI commands entered on the command line of a
terminal window. terminal window.
@ -23,11 +23,11 @@ If you are brand new to Docker, see [About Docker Engine](../../index.md).
## Set up ## 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) * [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) * [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) * [Open ports between the hosts](#open-protocols-and-ports-between-the-hosts)
### Three networked host machines ### 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 One of these machines is a manager (called `manager1`) and two of them are
workers (`worker1` and `worker2`). workers (`worker1` and `worker2`).
>**Note**
>**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 > You can follow many of the tutorial steps to test single-node swarm
work, but you can initialize a swarm, create services, and scale them. > 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 #### 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 * Port `4789` UDP (configurable) for overlay network traffic
If you plan on creating an overlay network with encryption (`--opt encrypted`), 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. 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 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 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" >}}

7
content/engine/swarm/swarm-tutorial/add-nodes.md
View File

@ -1,6 +1,6 @@
--- ---
description: Add nodes to the swarm description: Add nodes to the swarm
keywords: tutorial, cluster management, swarm keywords: tutorial, cluster management, swarm, get started
title: Add nodes to the swarm title: Add nodes to the swarm
notoc: true notoc: true
--- ---
@ -70,5 +70,6 @@ to add worker nodes.
## What's next? ## What's next?
Now your swarm consists of a manager and two worker nodes. In the next step of Now your swarm consists of a manager and two worker nodes. Next, you'll deploy a service.
the tutorial, you [deploy a service](deploy-service.md) to the swarm.
{{< button text="Deploy a service" url="deploy-service.md" >}}

11
content/engine/swarm/swarm-tutorial/create-swarm.md
View File

@ -1,6 +1,6 @@
--- ---
description: Initialize the swarm description: Initialize the swarm
keywords: tutorial, cluster management, swarm mode keywords: tutorial, cluster management, swarm mode, get started, docker engine
title: Create a swarm title: Create a swarm
notoc: true notoc: true
--- ---
@ -73,10 +73,11 @@ machines.
The `*` next to the node ID indicates that you're currently connected on The `*` next to the node ID indicates that you're currently connected on
this node. 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. 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 Next, you'll add two more nodes to the cluster.
the cluster.
{{< button text="Add two more nodes" url="add-nodes.md" >}}

9
content/engine/swarm/swarm-tutorial/delete-service.md
View File

@ -1,6 +1,6 @@
--- ---
description: Remove the service from the swarm 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 title: Delete the service running on the swarm
notoc: true 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 Next, you'll set up a new service and apply a rolling update.
[rolling update](rolling-update.md).
{{< button text="Apply rolling updates" url="rolling-update.md" >}}

8
content/engine/swarm/swarm-tutorial/deploy-service.md
View File

@ -1,6 +1,6 @@
--- ---
description: Deploy a service to the swarm 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 title: Deploy a service to the swarm
notoc: true notoc: true
--- ---
@ -35,6 +35,8 @@ is not a requirement to deploy a service.
9uk4639qpg7n helloworld 1/1 alpine ping docker.com 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). Now you're ready to inspect the service.
{{< button text="Deploy a service" url="inspect-service.md" >}}

24
content/engine/swarm/swarm-tutorial/drain-node.md
View File

@ -1,24 +1,24 @@
--- ---
description: Drain nodes on the swarm 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 title: Drain a node on the swarm
notoc: true notoc: true
--- ---
In earlier steps of the tutorial, all the nodes have been running with `ACTIVE` 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 availability. The swarm manager can assign tasks to any `Active` node, so up to
now all nodes have been available to receive tasks. now all nodes have been available to receive tasks.
Sometimes, such as planned maintenance times, you need to set a node to `DRAIN` Sometimes, such as planned maintenance times, you need to set a node to `Drain`
availability. `DRAIN` availability prevents a node from receiving new tasks availability. `Drain` availability prevents a node from receiving new tasks
from the swarm manager. It also means the manager stops tasks running on the 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**: > **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 > 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. > swarm service workloads.
{ .important } { .important }
@ -83,7 +83,7 @@ had a task assigned to it:
...snip... ...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 7. Run `docker service ps redis` to see how the swarm manager updated the
task assignments for the `redis` service: 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 you set another node to `Drain` availability
* when a task fails on another active node * when a task fails on another active node
## What's next? ## Next steps
Learn how to [use a swarm mode routing mesh](../ingress.md). Next, you'll learn how to use a Swarm mode routing mesh
{{< button text="Use a Swarm mode routing mesh" url="../ingress.md" >}}

19
content/engine/swarm/swarm-tutorial/inspect-service.md
View File

@ -1,6 +1,6 @@
--- ---
description: Inspect the application 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 title: Inspect a service on the swarm
notoc: true notoc: true
--- ---
@ -34,8 +34,11 @@ the Docker CLI to see details about the service running in the swarm.
Endpoint Mode: vip 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. without the `--pretty` flag.
{ .tip }
```console ```console
[manager1]$ docker service inspect helloworld [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 4. Run `docker ps` on the node where the task is running to see details about
the container for the task. 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. you must ssh to that node.
{ .tip }
```console ```console
[worker2]$ docker ps [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 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 Next, you'll change the scale for the service running in the swarm.
the swarm.
{{< button text="Change the scale" url="scale-service.md" >}}

6
content/engine/swarm/swarm-tutorial/rolling-update.md
View File

@ -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 `redis:3.0.6` while others are running `redis:3.0.7`. The output above shows
the state once the rolling updates are done. 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. Next, you'll learn how to drain a node in the swarm.
{{< button text="Drain a node" url="drain-node.md" >}}

11
content/engine/swarm/swarm-tutorial/scale-service.md
View File

@ -1,13 +1,13 @@
--- ---
description: Scale the service running in the swarm 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 title: Scale the service in the swarm
notoc: true notoc: true
--- ---
Once you have [deployed a service](deploy-service.md) to a swarm, you are ready 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 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 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 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 If you want to see the containers running on other nodes, ssh into
those nodes and run the `docker ps` command. 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. At this point in the tutorial, you're finished with the `helloworld` service. Next, you'll delete the service
The next step shows how to [delete the service](delete-service.md).
{{< button text="Delete the service" url="delete-service.md" >}}

8
data/toc.yaml
View File

@ -1645,8 +1645,8 @@ Manuals:
- path: /engine/swarm/swarm-tutorial/drain-node/ - path: /engine/swarm/swarm-tutorial/drain-node/
title: Drain a node title: Drain a node
- path: /engine/swarm/ingress/ - path: /engine/swarm/ingress/
title: Use swarm mode routing mesh title: Use Swarm mode routing mesh
- sectiontitle: How swarm mode works - sectiontitle: How Swarm mode works
section: section:
- path: /engine/swarm/how-swarm-mode-works/nodes/ - path: /engine/swarm/how-swarm-mode-works/nodes/
title: How nodes work title: How nodes work
@ -1657,7 +1657,7 @@ Manuals:
- path: /engine/swarm/how-swarm-mode-works/swarm-task-states/ - path: /engine/swarm/how-swarm-mode-works/swarm-task-states/
title: Swarm task states title: Swarm task states
- path: /engine/swarm/swarm-mode/ - path: /engine/swarm/swarm-mode/
title: Run Docker in swarm mode title: Run Docker in Swarm mode
- path: /engine/swarm/join-nodes/ - path: /engine/swarm/join-nodes/
title: Join nodes to a swarm title: Join nodes to a swarm
- path: /engine/swarm/manage-nodes/ - path: /engine/swarm/manage-nodes/
@ -1677,7 +1677,7 @@ Manuals:
- path: /engine/swarm/admin_guide/ - path: /engine/swarm/admin_guide/
title: Swarm administration guide title: Swarm administration guide
- path: /engine/swarm/raft/ - path: /engine/swarm/raft/
title: Raft consensus in swarm mode title: Raft consensus in Swarm mode
- sectiontitle: Advanced concepts - sectiontitle: Advanced concepts
section: section:
- sectiontitle: Container runtime - sectiontitle: Container runtime