docker-swarm
Orchestrate and manage a cluster of Docker nodes
TLDR
Initialize a swarm cluster
Display the token to join a manager or a worker
Join a new node to the cluster
Remove a worker from the swarm (run inside the worker node)
Display the current CA certificate in PEM format
Rotate the current CA certificate and display the new certificate
Change the valid period for node certificates
SYNOPSIS
docker swarm [OPTIONS] COMMAND
Available Commands:
init Initialize a swarm
join Join a swarm as a node and/or manager
leave Leave the swarm
update Update the swarm
Global Options (for docker swarm command itself):
--help Print usage
PARAMETERS
--advertise-addr
Address that manager nodes use to advertise themselves to other nodes in the swarm. Used by init and join.
--listen-addr
Address on which the swarm manager or worker listens for incoming cluster management and orchestration traffic. Used by init and join.
--token
Token for joining a swarm. Required when using join to add a node.
--force
Force a node to leave the swarm, even if it is a manager. Used by leave.
--autolock
Enable or disable swarm autolock. Autolock protects the swarm secret key, requiring a key to unlock managers after a restart. Used by update.
--task-history-limit
Set the number of historical tasks to retain per service. Used by update.
--default-addr-pool
Set the default address pool for swarm overlay networks. Used by init.
--help
Prints the help message for the docker swarm command or its subcommands.
DESCRIPTION
The docker swarm command is the primary tool for managing Docker Swarm clusters directly from the Docker CLI. It allows users to initialize a new swarm, add manager or worker nodes, remove nodes, and update global swarm configurations. Swarm mode, built into the Docker Engine, provides native container orchestration capabilities, enabling the deployment of applications as services across a cluster of machines. It handles service discovery, load balancing, desired state reconciliation, and rolling updates, simplifying the process of running highly available and fault-tolerant containerized applications in a distributed environment.
CAVEATS
The docker swarm commands are part of the Docker Engine's built-in swarm mode, available since Docker Engine 1.12. It requires Docker Engine to be installed and running. For production deployments, it's crucial to have an odd number of manager nodes (e.g., 3, 5) for fault tolerance and quorum. While robust, for very large-scale or highly complex orchestration needs, alternative platforms like Kubernetes might be considered.
CORE SWARM CONCEPTS
Docker Swarm operates with two main node types: manager nodes, which handle orchestration tasks and maintain the swarm state, and worker nodes, which execute service tasks. Services define the desired state of your applications, including the image to use, the number of replicas, and exposed ports. Swarm mode ensures that the actual state of your services matches the desired state, automatically rebalancing or rescheduling tasks as needed. Key features include built-in load balancing via the ingress routing mesh, service discovery, and rolling updates for zero-downtime deployments.
NETWORK CONSIDERATIONS
For docker swarm to function correctly, specific ports must be open between nodes: 2377/TCP (Swarm management traffic), 7946/TCP and 7946/UDP (container network discovery), and 4789/UDP (overlay network traffic). Proper firewall configuration is essential for inter-node communication.
SECURITY BEST PRACTICES
Swarm communication is secured with TLS. It's recommended to enable autolock for manager nodes using docker swarm update --autolock=true to encrypt the swarm key, preventing unauthorized access if a manager node is compromised or lost. Node join tokens should be kept secure and rotated regularly to prevent unauthorized nodes from joining the swarm.
HISTORY
Swarm mode was introduced in Docker Engine 1.12 (July 2016), integrating native orchestration capabilities directly into the Docker daemon. This built-in functionality replaced the older, standalone 'Docker Swarm' tool. The aim was to provide a simpler, more tightly integrated, and opinionated orchestration solution for users already familiar with the Docker ecosystem, making it easier to scale applications across multiple machines without needing external orchestrators.