diff --git a/src/tools/docker-swarm-memo/docker-swarm.md b/src/tools/docker-swarm-memo/docker-swarm.md index 24a5a4fc..4fb50467 100644 --- a/src/tools/docker-swarm-memo/docker-swarm.md +++ b/src/tools/docker-swarm-memo/docker-swarm.md @@ -1,194 +1,478 @@ -**Docker Swarm Mode** is Docker’s native clustering and orchestration solution. It allows you to manage a group of Docker nodes as a single virtual system, enabling high availability, load balancing, and simplified deployment of containerized applications. +**Docker Swarm Mode** is Docker's native clustering and orchestration solution. It lets you manage a group of Docker nodes as a single virtual system, enabling high availability, load balancing, and simplified deployment of containerized applications. Key features: -- Built-in orchestration -- Declarative service model -- Rolling updates -- Auto-scaling and self-healing -- Secure node communication via TLS +- Built-in orchestration with a declarative service model +- Rolling updates and rollback +- Self-healing (failed replicas are rescheduled automatically) +- Secure node-to-node communication via mutual TLS +- Built-in secrets and config distribution + +> ℹ️ Swarm does **not** auto-scale based on load. Replica counts are set manually with `docker service scale` or `--replicas`. ## πŸ“Œ Swarm Initialization -- **Initialize Swarm** - ```bash - docker swarm init - ``` +Initialize a new swarm on the current node (becomes the first manager): -- **Join Swarm (on worker/manager node)** - ```bash - docker swarm join-token worker - ``` +```bash +docker swarm init +``` -- **Leave Swarm** - ```bash - docker swarm leave - ``` +If the host has multiple network interfaces, specify which one to advertise on: -- **Force Leave (on manager)** - ```bash - docker swarm leave --force - ``` +```bash +docker swarm init --advertise-addr +``` + +Show the command another node needs to join as a worker: + +```bash +docker swarm join-token worker +``` + +Show the command for joining as a manager: + +```bash +docker swarm join-token manager +``` + +Join an existing swarm (run on the joining node, using the output of the commands above): + +```bash +docker swarm join --token :2377 +``` + +Rotate join tokens (invalidates the old ones): + +```bash +docker swarm join-token --rotate worker +``` + +Leave the swarm (on a worker): + +```bash +docker swarm leave +``` + +Force leave (on a manager β€” last manager must use `--force`): + +```bash +docker swarm leave --force +``` ## πŸ‘₯ Node Management -- **List nodes** - ```bash - docker node ls - ``` +List nodes in the swarm: -- **Promote node to manager** - ```bash - docker node promote - ``` +```bash +docker node ls +``` -- **Demote node to worker** - ```bash - docker node demote - ``` +Inspect a node: -- **Inspect node** - ```bash - docker node inspect --pretty - ``` +```bash +docker node inspect --pretty +``` -- **Drain node (prevent scheduling)** - ```bash - docker node update --availability drain - ``` +Promote a worker to manager: -- **Activate node** - ```bash - docker node update --availability active - ``` +```bash +docker node promote +``` + +Demote a manager to worker: + +```bash +docker node demote +``` + +Drain a node (reschedule its tasks elsewhere, prevent new scheduling): + +```bash +docker node update --availability drain +``` + +Pause a node (keep running tasks, prevent new ones): + +```bash +docker node update --availability pause +``` + +Activate a drained or paused node: + +```bash +docker node update --availability active +``` + +Add a label to a node (for use with placement constraints): + +```bash +docker node update --label-add env=production +``` + +Remove a node from the swarm (after it has left or is unreachable): + +```bash +docker node rm +``` ## 🧠 Manager Nodes -Manager nodes are responsible for: -- Orchestrating tasks and services -- Maintaining cluster state -- Handling API requests +Manager nodes orchestrate tasks, maintain cluster state via Raft consensus, and handle API requests. You can run multiple managers for HA, but only one is the **leader** at any time. -You can have multiple managers for high availability, but only one is the **leader** at any time. +> ⚠️ **Use an odd number of managers** (3, 5, or 7). Raft tolerates `(N-1)/2` failures β€” 3 managers tolerate 1 failure, 5 tolerate 2. More than 7 hurts performance. -- **Check manager status** - ```bash - docker node ls - ``` +Show Swarm and Raft state for the local node: -- **View Raft consensus info** - ```bash - docker swarm inspect - ``` +```bash +docker info +``` + +Inspect the current node (includes manager status if applicable): + +```bash +docker node inspect self --pretty +``` + +Enable autolock (encrypts Raft logs; managers need a key to restart): + +```bash +docker swarm update --autolock=true +``` + +Unlock a manager after restart: + +```bash +docker swarm unlock +``` + +Show or rotate the unlock key: + +```bash +docker swarm unlock-key +docker swarm unlock-key --rotate +``` ## πŸ“¦ Service Management -- **Create service** - ```bash - docker service create --name - ``` +Create a service: -- **Create service with replicas** - ```bash - docker service create --name --replicas - ``` +```bash +docker service create --name +``` -- **List services** - ```bash - docker service ls - ``` +Create a service with a fixed number of replicas: -- **Inspect service** - ```bash - docker service inspect --pretty - ``` +```bash +docker service create --name --replicas +``` -- **Scale service** - ```bash - docker service scale = - ``` +Create a global service (one task per node): -- **Update service** - ```bash - docker service update --image - ``` +```bash +docker service create --name --mode global +``` -- **Remove service** - ```bash - docker service rm - ``` +List services: + +```bash +docker service ls +``` + +Inspect a service: + +```bash +docker service inspect --pretty +``` + +Scale a service: + +```bash +docker service scale = +``` + +Update a service (e.g. change image): + +```bash +docker service update --image +``` + +Roll back the last update: + +```bash +docker service rollback +``` + +Follow logs from all tasks of a service: + +```bash +docker service logs -f +``` + +Remove a service: + +```bash +docker service rm +``` ## πŸ” Replicas -Replicas define how many instances of a service should run across the swarm. +Replicas define how many instances of a service should run across the swarm. Swarm distributes them across available nodes and reschedules them if they fail. -- **Set replicas when creating a service** - ```bash - docker service create --replicas 5 --name myapp myimage - ``` +Set replicas at create time: -- **Scale replicas** - ```bash - docker service scale myapp=10 - ``` +```bash +docker service create --replicas 5 --name myapp myimage +``` -Swarm automatically distributes replicas across available nodes and restarts them if they fail. +Change replica count later: + +```bash +docker service scale myapp=10 +``` ## 🐝 Task & Container Management -- **List tasks of a service** - ```bash - docker service ps - ``` +In Swarm, a **task** is a single container slot managed by Swarm. A task maps to a running container on some node. -- **List all tasks** - ```bash - docker node ps - ``` +List tasks of a service (shows which node each runs on): -- **List containers** - ```bash - docker container ls - ``` +```bash +docker service ps +``` -- **Inspect container** - ```bash - docker container inspect - ``` +List tasks running on a specific node: + +```bash +docker node ps +``` + +List containers on the current node: + +```bash +docker container ls +``` + +Inspect a container: + +```bash +docker container inspect +``` ## 🌐 Networking -### 🧠 What Is an Overlay Network? -An overlay network is a virtual network that spans across multiple Docker hosts. It allows containers running on different nodes +### What is an overlay network? -### Commands +An overlay network is a virtual network that spans multiple Docker hosts. It lets containers running on different nodes communicate as if they were on the same Layer 2 network, with built-in DNS-based service discovery and encrypted traffic between nodes. -- **Create overlay network** - ```bash - docker network create --driver overlay - ``` +Create an overlay network: -- **List networks** - ```bash - docker network ls - ``` +```bash +docker network create --driver overlay +``` -- **Attach service to network** - ```bash - docker service create --name --network - ``` +Create an encrypted overlay network (encrypts data plane between nodes): -## πŸ›  Useful Flags +```bash +docker network create --driver overlay --opt encrypted +``` + +List networks: + +```bash +docker network ls +``` + +Inspect a network (shows attached services and containers): + +```bash +docker network inspect +``` + +Attach a service to a network at create time: + +```bash +docker service create --name --network +``` + +Attach an existing service to an additional network: + +```bash +docker service update --network-add +``` + +## πŸ”„ Rolling Updates & Rollback + +Configure update behavior at service create or update time: + +```bash +docker service create \ + --name web \ + --replicas 5 \ + --update-parallelism 2 \ + --update-delay 10s \ + --update-failure-action rollback \ + --update-monitor 30s \ + nginx:1.25 +``` + +Trigger an update by changing the image: + +```bash +docker service update --image nginx:1.26 web +``` + +Roll back to the previous spec: + +```bash +docker service rollback web +``` + +Update flags worth knowing: | Flag | Description | |------|-------------| -| `--replicas` | Number of service instances | +| `--update-parallelism` | How many tasks to update at once | +| `--update-delay` | Delay between batches | +| `--update-failure-action` | `pause`, `continue`, or `rollback` on failure | +| `--update-monitor` | Time to watch each task for failure | +| `--update-order` | `stop-first` (default) or `start-first` | + +## πŸ” Secrets + +Secrets are encrypted at rest in the Raft log and mounted into containers as in-memory files under `/run/secrets/`. + +Create a secret from a file: + +```bash +docker secret create db_password ./db_password.txt +``` + +Create a secret from stdin: + +```bash +echo "s3cr3t" | docker secret create db_password - +``` + +List secrets: + +```bash +docker secret ls +``` + +Inspect a secret (does **not** reveal the value): + +```bash +docker secret inspect db_password +``` + +Attach a secret to a service: + +```bash +docker service create --name db --secret db_password postgres:16 +``` + +Remove a secret (only if no service uses it): + +```bash +docker secret rm db_password +``` + +## πŸ”‘ Configs + +Configs are like secrets but **not encrypted at rest** β€” meant for non-sensitive config files (nginx.conf, etc.). + +Create a config: + +```bash +docker config create my_nginx_conf ./nginx.conf +``` + +List configs: + +```bash +docker config ls +``` + +Attach a config to a service at a specific path: + +```bash +docker service create \ + --name web \ + --config source=my_nginx_conf,target=/etc/nginx/nginx.conf \ + nginx +``` + +Remove a config: + +```bash +docker config rm my_nginx_conf +``` + +## πŸ“š Stacks + +A **stack** is a group of related services deployed together from a Compose file. This is the standard production workflow for Swarm. + +Deploy (or update) a stack: + +```bash +docker stack deploy -c stack.yaml mystack +``` + +List stacks: + +```bash +docker stack ls +``` + +List services in a stack: + +```bash +docker stack services mystack +``` + +List tasks in a stack: + +```bash +docker stack ps mystack +``` + +Remove a stack: + +```bash +docker stack rm mystack +``` + +Stacks honor the `deploy:` block in Compose files (replicas, placement, restart policy, update config). `build:`, top-level `restart:`, and `depends_on:` are ignored. + +## πŸ›  Common Flags Reference + +### `docker service create` / `update` + +| Flag | Description | +|------|-------------| +| `--replicas` | Number of service replicas | +| `--mode` | `replicated` (default) or `global` | | `--publish` | Port mapping (`:`) | | `--mount` | Volume mounting | -| `--constraint` | Node placement rules | -| `--update-delay` | Delay between updates | -| `--limit-cpu` / `--limit-memory` | Resource limits | +| `--network` | Attach to a network | +| `--constraint` | Node placement rule (e.g. `node.role==worker`) | +| `--placement-pref` | Spread tasks (e.g. `spread=node.labels.zone`) | +| `--limit-cpu` / `--limit-memory` | Hard resource limits | +| `--reserve-cpu` / `--reserve-memory` | Reserved resources | +| `--secret` / `--config` | Attach a secret or config | +| `--env` / `--env-file` | Environment variables | +| `--restart-condition` | `none`, `on-failure`, or `any` | -## πŸ“„ Example: Create a Web Service +### Update-specific flags + +| Flag | Description | +|------|-------------| +| `--update-parallelism` | Tasks updated in parallel | +| `--update-delay` | Delay between update batches | +| `--update-failure-action` | `pause`, `continue`, `rollback` | +| `--update-order` | `stop-first` or `start-first` | + +## πŸ“„ Example: Production-style Web Service ```bash docker service create \ @@ -196,5 +480,20 @@ docker service create \ --replicas 3 \ --publish 80:80 \ --network webnet \ - nginx -``` \ No newline at end of file + --constraint 'node.role==worker' \ + --constraint 'node.labels.env==production' \ + --update-parallelism 1 \ + --update-delay 10s \ + --update-failure-action rollback \ + --limit-memory 512m \ + --reserve-memory 256m \ + nginx:1.25 +``` + +## πŸ“š Resources + +- [Swarm mode overview](https://docs.docker.com/engine/swarm/) +- [Swarm services](https://docs.docker.com/engine/swarm/services/) +- [Manage secrets](https://docs.docker.com/engine/swarm/secrets/) +- [Manage configs](https://docs.docker.com/engine/swarm/configs/) +- [Stack file reference (Compose Spec `deploy:`)](https://docs.docker.com/compose/compose-file/deploy/)