From 92e3749529347089e7596b0ddc853c11927dfaf3 Mon Sep 17 00:00:00 2001 From: radinpirouz Date: Fri, 16 May 2025 00:15:52 +0330 Subject: [PATCH] docker doc: update swarm doc --- .../Docker/5-Docker-Swarm.md | 172 +++++++++++------- 1 file changed, 104 insertions(+), 68 deletions(-) diff --git a/Containerization & Orchestration/Docker/5-Docker-Swarm.md b/Containerization & Orchestration/Docker/5-Docker-Swarm.md index 1f19db3..cdc471d 100755 --- a/Containerization & Orchestration/Docker/5-Docker-Swarm.md +++ b/Containerization & Orchestration/Docker/5-Docker-Swarm.md @@ -1,89 +1,85 @@ -# Docker Swarm Documentation +# 📦 Docker Swarm Documentation -This guide covers key commands and workflows for managing a Docker Swarm cluster. It includes information on initializing the cluster, node management, service management, and best practices to ensure your cluster remains operational. +Comprehensive guide to managing a **Docker Swarm** cluster. This document includes core commands, workflows, and best practices for maintaining a healthy and operational environment. --- -## Table of Contents +## 📚 Table of Contents -1. [Cluster Health & Manager Count](#cluster-health--manager-count) -2. [Example Workflow: Setting Up Nginx](#example-workflow-setting-up-nginx) -3. [Cluster Initialization and Management](#cluster-initialization-and-management) -4. [Node Management](#node-management) -5. [Service Management](#service-management) -6. [Join Tokens](#join-tokens) +1. [🔧 Cluster Health & Manager Count](#-cluster-health--manager-count) +2. [🚀 Example Workflow: Setting Up Nginx](#-example-workflow-setting-up-nginx) +3. [⚙️ Cluster Initialization and Management](#️-cluster-initialization-and-management) +4. [🖥️ Node Management](#️-node-management) +5. [🛠️ Service Management](#️-service-management) +6. [🔑 Join Tokens & Node Configuration](#-join-tokens--node-configuration) --- -## Cluster Health & Manager Count +## 🔧 Cluster Health & Manager Count -To maintain a healthy and functional Docker Swarm cluster, **the number of manager nodes must exceed 50% of the total nodes**. If the manager nodes fall below 51% of the cluster, the system will lose quorum and become non-operational. Always monitor your manager count to ensure high availability. +A Docker Swarm cluster requires a **majority of manager nodes** to be functional for quorum. + +> **Best Practice:** Always maintain **more than 50%** manager nodes online. Losing quorum will render the cluster non-operational. --- -## Example Workflow: Setting Up Nginx +## 🚀 Example Workflow: Setting Up Nginx -When deploying services such as Nginx, the typical workflow in Docker Swarm is: +Docker Swarm handles service deployment through several internal components: -1. **API**: Handle incoming requests. -2. **Allocator**: Distribute workload to available nodes. -3. **Dispatcher**: Manage task assignments. -4. **Scheduler**: Ensure tasks run on the optimal nodes. +1. **API** – Receives service requests. +2. **Allocator** – Determines resource allocation. +3. **Dispatcher** – Assigns tasks to nodes. +4. **Scheduler** – Places tasks on optimal nodes. -This workflow ensures that your service is efficiently distributed and scaled across the cluster. +This process ensures resilient and efficient service distribution. --- -## Cluster Initialization and Management +## ⚙️ Cluster Initialization and Management -### Create Cluster +### 🔹 Initialize Cluster -Initialize a new Docker Swarm cluster: ```bash docker swarm init ``` -This command sets up the current node as the manager of a new cluster. -### Create Cluster with a Specific Interface +### 🔹 Initialize with Specific Interface -Specify an IP address or interface name when initializing the cluster: ```bash -docker swarm init --advertise-addr +docker swarm init --advertise-addr ``` -This ensures that the node advertises the correct network interface for other nodes to join. -### Join Cluster +### 🔹 Join Existing Cluster -Add a node to an existing Docker Swarm cluster: ```bash docker swarm join ``` -### Leave Cluster +### 🔹 Leave Cluster -Remove a node from the cluster: ```bash docker swarm leave ``` -### Unlock Locked Manager +### 🔹 Unlock a Manager Node -Unlock a manager node that has been locked: ```bash docker swarm unlock ``` --- -## Node Management +## 🖥️ Node Management -### List Nodes +### 🔸 List Nodes -View the status and details of all nodes in your cluster: ```bash docker node ls ``` + **Example Output:** + ``` ID HOSTNAME STATUS AVAILABILITY MANAGER STATUS ENGINE VERSION 8yw8jrjeqczaci0qkuy060g09 * docker-1 Ready Active Leader 24.0.5 @@ -92,101 +88,141 @@ kd3ujmt1ey3pw6v9189fouxfa docker-3 Ready Active Reachable tm1msy58ztcltt36rs1lb76p7 docker-4 Down Active 24.0.5 ``` -### Remove Node +### 🔸 Remove a Node -Remove a node from the cluster by specifying its ID: ```bash docker node rm ``` -**Example:** + +### 🔸 Promote to Manager + ```bash -docker node rm tm1msy58ztcltt36rs1lb76p7 +docker node promote ``` -### Promote Node to Manager +### 🔸 Inspect a Node -Upgrade a worker node to a manager node: ```bash -docker node promote +docker node inspect ``` -**Example:** + +### 🔸 Change Node Role + ```bash -docker node promote v4gvf7xenw0izmxgvhr6hb2rj +docker node update --role manager +docker node update --role worker +``` + +### 🔸 Change Node Availability + +```bash +docker node update --availability active +docker node update --availability pause +docker node update --availability drain +``` + +### 🔸 Add or Remove Labels + +**Add:** + +```bash +docker node update --label-add env=development +docker node update --label-add env=testing +``` + +**Remove:** + +```bash +docker node update --label-rm env= +docker node update --label-rm env +``` + +**Use label constraints in service deployment:** + +```yaml +deploy: + placement: + constraints: + - node.labels.env == development ``` -This command promotes the specified node, enabling it to participate in cluster management decisions. --- -## Service Management +## 🛠️ Service Management -### Show Task Status on Cluster +### 🔹 Show Tasks on a Node -Display the status of tasks running on each node: ```bash docker node ps ``` -### List Services +### 🔹 List All Services -List all services currently running in the cluster: ```bash docker service ls ``` -### Create Service +### 🔹 Create a New Service -Create a new service with the specified name and Docker image: ```bash docker service create --name ``` -### Scale Service +### 🔹 Scale a Service -Adjust the number of replicas for an existing service: ```bash docker service scale = ``` + **Example:** + ```bash docker service scale nginx=5 ``` -This command scales the `nginx` service to 5 replicas. -### Inspect Service +### 🔹 Inspect a Service -View detailed information about a specific service: ```bash docker service inspect ``` -### Create Service with Replicas and Environment Variables +### 🔹 Create Service with Replicas, Env Vars, and Port Mapping -Launch a new service with multiple replicas, environment variables, and port publishing: ```bash -docker service create --name --replicas --env --publish : +docker service create \ + --name \ + --replicas \ + --env \ + --publish : \ + ``` + **Example:** + ```bash -docker service create --name nginx --replicas 3 --env MY_ENV_VAR=value --publish 8080:80 nginx +docker service create \ + --name nginx \ + --replicas 3 \ + --env MY_ENV_VAR=value \ + --publish 8080:80 \ + nginx ``` -This creates an `nginx` service with 3 replicas, sets the environment variable `MY_ENV_VAR` to `value`, and maps port 8080 on the host to port 80 in the container. --- -## Join Tokens +## 🔑 Join Tokens & Node Configuration -To securely add new nodes to the swarm, use the join tokens provided by Docker Swarm. +Securely add nodes to your Swarm using join tokens. -### Get Worker Join Token +### 🔹 Get Worker Token -Display the token required for a node to join as a worker: ```bash docker swarm join-token worker ``` -### Get Manager Join Token +### 🔹 Get Manager Token -Display the token required for a node to join as a manager: ```bash docker swarm join-token manager ``` +