docker-swarm

Initialize a swarm cluster

$ docker swarm init

$ docker swarm join-token [worker|manager]

$ docker swarm join --token [token] [manager_node_url:2377]

$ docker swarm leave

$ docker swarm ca

$ docker swarm ca --rotate

$ docker swarm update --cert-expiry [hours]h[minutes]m[seconds]s

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

--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.

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.

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.

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.

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.

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.

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.

docker(1), docker service(1), docker node(1)