Развёртывание Docker Swarm на Debian 11: пошаговое руководство

Docker Swarm на Debian 11 — быстрый путь к кластеру контейнеров: установите Docker на все узлы, настройте UFW, инициализируйте Swarm Manager, добавьте рабочие узлы и разверните сервисы командой docker service. В статье — пошаговые команды, чек-листы администратора, рекомендации по безопасности и восстановлению, шаблоны и подсказки для отладки.

Docker Swarm — встроенный механизм оркестрации контейнеров на базе Docker Engine. Он позволяет создать кластер Docker-узлов на нескольких серверах, упростить развёртывание контейнированных приложений в виде сервисов и управлять масштабированием, желаемым состоянием, балансировкой и обновлениями.

В этом руководстве рассматривается развёртывание Swarm на серверах Debian 11: установка Docker, настройка UFW (Uncomplicated Firewall), инициализация Swarm Manager, добавление рабочих узлов и базовые операции с сервисами (создание, масштабирование, удаление). Включены советы по безопасности, отладке и восстановлению.

Важно: команды в руководстве необходимо выполнять от имени пользователя с правами sudo или root. Кодовые примеры используют примерные IP; подставьте свои адреса.

Содержание

• Требования
• Установка Docker на всех узлах
• Настройка UFW и открытие портов для Swarm
• Инициализация Swarm Manager
• Добавление рабочих узлов
• Базовые операции с сервисами: создать, проверить, масштабировать, удалить
• Резервирование, безопасность и рекомендации по рабочему процессу
• Чек-листы ролей: администратор, оператор, разработчик
• Быстрый набор команд (cheat sheet)
• Критерии приёмки и типичные ошибки с их исправлением
• Сводка и дальнейшие шаги

Требования

Для выполнения всех шагов нужно несколько серверов Debian 11 и пользователь с правами sudo/root на каждом сервере.

В демонстрации используем три сервера (пример):

Hostname    IP Address        Used as
-------------------------------------
manager     192.168.5.30      Swarm Manager
node1       192.168.5.120     Worker node
node2       192.168.5.121     Worker node

Проверьте сетевую доступность между узлами (ping, tcp) и корректную настройку /etc/hosts или DNS, если используете имена хостов.

Установка Docker

Рекомендуется установить Docker из официального репозитория Docker, чтобы получить актуальные версии пакетов.

1. На всех серверах выполните установку зависимостей:

sudo apt update
sudo apt install apt-transport-https ca-certificates curl gnupg lsb-release -y

2. Добавьте GPG-ключ и ключевой каталог:

sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/debian/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

3. Добавьте репозиторий Docker (учитывается архитектура):

echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/debian \
  $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

4. Обновите индекс пакетов и установите Docker Engine и сопутствующие пакеты:

sudo apt update
sudo apt install docker-ce docker-ce-cli containerd.io docker-compose-plugin -y

5. Запустите и включите сервис docker:

sudo systemctl start docker
sudo systemctl enable docker
sudo systemctl status docker

Если вы планируете запускать docker-команды без sudo, добавьте пользователя в группу docker:

sudo usermod -aG docker $USER
newgrp docker   # чтобы обновить группу в текущей сессии

Замечание: добавление в группу docker даёт права, эквивалентные root для управления контейнерами — оценивайте риск в продуктивных окружениях.

Настройка брандмауэра (UFW)

Если Swarm разворачивается в продуктивной среде, настройка брандмауэра между узлами обязательна. Здесь используется UFW — простой интерфейс над iptables.

Необходимые порты для Docker Swarm:

• TCP 2377 — управление кластером (join/manager communications).
• TCP/UDP 7946 — коммуникация между узлами (гossip, discovery).
• UDP 4789 — трафик overlay-сетей (VXLAN).
• (Опционально) порты сервисов, которые вы будете пробрасывать, напр. 8000.

Установите и включите UFW:

sudo apt install ufw -y
sudo ufw allow "OpenSSH"
sudo ufw enable

Откройте порты, необходимые для Swarm:

sudo ufw allow 2377/tcp
sudo ufw allow 7946/tcp
sudo ufw allow 7946/udp
sudo ufw allow 4789/udp

Проверьте правила:

sudo ufw status verbose

Советы по безопасности:

• Если у вас публичные IP, ограничьте доступ к порту 2377 только из доверенных сетей (manager-to-manager).
• Разрешайте порты только между узлами кластера при помощи сетевых ACL или VPN.

Инициализация Swarm Manager

Swarm Manager хранит состояние кластера и служит точкой управления. Для отказоустойчивости рекомендуется иметь нечётное число менеджеров (3, 5 и т.д.). В этом руководстве инициализируем один менеджер для примера.

Выполните на узле manager (в нашем примере 192.168.5.30):

docker swarm init --advertise-addr 192.168.5.30 --default-addr-pool 10.20.0.0/16

Опции:

• –advertise-addr — IP/интерфейс, по которому остальные узлы будут соединяться с менеджером.
• –default-addr-pool — пул адресов для overlay-сетей (опционально, удобно задавать, чтобы избежать конфликтов с сетью хоста).

Проверка режима Swarm:

docker info

Вы должны увидеть Swarm: active и пул адресов overlay-сетей.

Список узлов на менеджере:

docker node ls

Пока будет отображён только manager.

Добавление рабочих узлов в Swarm

Каждый рабочий узел должен иметь установленный Docker и настроенный брандмауэр (порты выше). Чтобы присоединить рабочий узел, используйте команду join с токеном worker, который был выведен при инициализации.

На worker (node1 и node2) выполните (замените токен своим):

docker swarm join \
--token SWMTKN-1-5tui5dveqw6n2b0m6suut0w7nf9w0wb5jyvfhmykb4jdehps1j-ag99f7750mmnim6ao5yp0x3s2 \
192.168.5.30:2377

Если потеряли токен, на менеджере можно вывести его повторно:

docker swarm join-token worker

Проверьте на менеджере, что узлы добавлены и в состоянии Ready:

docker node ls

В интерфейсе вы увидите список узлов, их роль и статус. Пример: manager, node1, node2 — все Ready.

Практический совет: сохраняйте токен и защищайте его — токен даёт возможность присоединиться к кластеру.

Управление сервисами в Docker Swarm

В Swarm приложение разворачивается как сервис, основанный на Docker-образе. При создании сервиса укажите образ, порт(ы), ограничения, количество реплик, объёмы и сетевые опции.

Пример: создадим сервис test-httpd на базе httpd:alpine, пробросив порт 8000 на хосты кластера:

docker service create --replicas 1 --name test-httpd -p 8000:80 httpd:alpine

Проверка списка сервисов:

docker service ls

Инспекция сервиса:

docker service inspect test-httpd

docker service inspect --pretty test-httpd

Просмотр задач (tasks) сервиса — показывает, на каких узлах запущены контейнеры:

docker service ps test-httpd

Если сервис слушает на порту 8000, откройте этот порт в UFW на всех узлах:

sudo ufw allow 8000/tcp

Проверка доступности через curl (с любого узла, который имеет доступ к менеджеру):

curl 192.168.5.30:8000
curl -I 192.168.5.30:8000

Вы должны увидеть стандартную страницу httpd.

Управление состоянием и обновления

Swarm поддерживает декларативную модель: вы описываете желаемое состояние (количество реплик, политика обновления) — менеджеры приводят фактическое состояние в соответствие.

Пример обновления изображения сервисa (rolling update):

docker service update --image httpd:2.4-alpine test-httpd

Можно задать стратегию обновления, задержки между обновлениями и количество параллельно обновляемых задач.

Масштабирование сервисов

Чтобы увеличить количество реплик, используйте:

docker service scale test-httpd=3

Проверить задачи:

docker service ps test-httpd

Контейнеры будут распределены по доступным узлам (в зависимости от ограничений, меток и доступных ресурсов).

Проверка на node1/node2:

docker ps
curl node1:8000

docker ps
curl node2:8000

Swarm автоматически выполняет балансировку входящего трафика на слушаемый порт через встроенный маршрутизатор (routing mesh).

Удаление сервисов и очистка

Для удаления сервиса:

docker service rm test-httpd

Проверить отсутствие сервиса:

docker service inspect test-httpd  # вернёт ошибку, если сервис удалён

Проверьте контейнеры и образы на узлах:

docker ps -a
docker images

Резервирование и управление состоянием кластера

• Резервируйте ключевые данные менеджера (Raft). На менеджерах хранится Raft-лог; при потере всех менеджеров кластер не восстановить.
• Для отказоустойчивости держите 3 менеджера (не менее трёх) для сохранения кворума.
• Для бэкапа конфигурации можно экспортировать docker swarm join-token и другие метаданные; однако штатного «плоского» экспорта всего Raft Docker не предоставляет — используйте snapshot на уровне хоста (файловые снимки, резервное копирование /var/lib/docker/volumes и/или системных томов).

Команда для получения токенов и информации:

docker swarm join-token manager

docker swarm join-token worker

Ротация токенов (если утёк токен):

docker swarm join-token --rotate worker

Безопасность и лучшие практики

• Зафиксируйте доступ к портам менеджера (2377) через VPN или ACL.
• Храните токены в защищённом хранилище (vault, секретный менеджер).
• Используйте TLS, который Docker Swarm создаёт и управляет автоматически для межузлового трафика; для дополнительного контроля можно использовать собственные сертификаты.
• Планируйте размещение менеджеров на разнородных хостах/зонах для предотвращения одновременно потери всех менеджеров.
• Избегайте запуска stateful сервисов без внешней системы хранения данных (например, подключённых NFS, CIFS или специализированных решений для контейнеров).

Диагностика проблем — распространённые ошибки и решения

• Узлы не видят друг друга:

  • Проверьте UFW/iptables, откройте 2377, 7946, 4789.
  • Проверьте, что используется правильный –advertise-addr.
  • Проверьте сетевую доступность через ping или nc.

• Невозможно присоединиться с токеном:

  • Убедитесь, что используете токен соответствующего типа (worker или manager).
  • На менеджере выполните docker swarm join-token worker и скопируйте токен заново.

• Непредвиденная потеря менеджера:

  • Если остался кворум (больше половины менеджеров), кластер продолжит работу.
  • Если кворум потерян — восстановление возможно из бэкапа хоста/файловой системы или через перенос Raft-данных с резервного узла.

Чек-лист перед продуктивным запуском

• Docker установлен на всех узлах и service docker включён.
• UFW/брандмауэр настроен и открыты порты 2377, 7946 (TCP/UDP), 4789 (UDP).
• Узлы видят друг друга по сети, правильный –advertise-addr указан на менеджере.
• Токены join безопасно сохранены.
• Создан план резервного копирования данных контейнеров и Raft (менеджеры).
• Мониторинг и логирование (Prometheus, ELK/EFK или аналог) настроены для контейнеров и хостов.

Роли и задачи: кто что делает

• Администратор (Manager): устанавливает Docker, инициализирует Swarm, управляет менеджерами, выполняет операции обновления и масштабирования.
• Оператор (Ops): следит за состоянием узлов, UFW/сетевой конфигурацией, выполняет откат и восстановление, контролирует резервные копии.
• Разработчик: создаёт и тестирует Docker-образы, описывает сервисы, указывает healthcheck и ограничения ресурсов (CPU/memory) в образах и в сервисах.

Ролевая чек-лист (кратко)

Администратор:

• Инициализация Swarm
• Присвоение меток узлам (docker node update –label-add key=value )
• Управление секретами (docker secret)

Оператор:

• Мониторинг состояния docker node ls
• Управление UFW
• Восстановление из snapshot

Разработчик:

• Подготовка Dockerfile
• Тестирование локально docker compose
• Деплой сервисов в тестовый стек Swarm

Мини-методология развёртывания (SOP)

1. Подготовка: обновление пакетов, установка Docker, проверка сети.
2. Настройка безопасности: UFW, ключи, резервное хранение токенов.
3. Инициализация менеджера с корректным advertise-addr.
4. Добавление рабочих узлов с проверкой node ls.
5. Развёртывание сервисов: images, volumes, constraints.
6. Мониторинг и логирование: настройка SLI/SLO, алертов.

Быстрый набор команд (Cheat sheet)

# Проверка Docker
sudo systemctl status docker

docker info

docker swarm init --advertise-addr 

docker swarm join --token  :2377

docker node ls

docker service create --name mysvc --replicas 3 -p 80:80 nginx:alpine

docker service ls
docker service ps mysvc
docker service update --image nginx:latest mysvc

docker service scale mysvc=5
docker service rm mysvc

Критерии приёмки

• Все узлы в состоянии Ready (docker node ls).
• Созданный тестовый сервис отвечает по назначенному порту с нескольких узлов.
• Резервные копии конфигурации менеджеров и ключей доступны.
• Мониторинг собирает метрики контейнеров и узлов.

Примеры отказов и альтернативные подходы

• Если требуется сложная оркестрация и расширенные возможности (CRD, операторы, более крупная экосистема), рассмотрите Kubernetes.
• Если нужен простой кластер без сложного управления, можно использовать docker-compose для небольших задач, но он не обеспечивает автоматического восстановления и распределения по узлам.

Шаблоны и соглашения (примеры)

Метка узла для размещения сервиса на конкретных хостах:

docker node update --label-add region=eu node1

docker service create --name europe-svc --constraint 'node.labels.region==eu' nginx:alpine

Пример healthcheck в Dockerfile (чтобы Swarm учитывал состояние контейнера):

HEALTHCHECK --interval=30s --timeout=5s --retries=3 CMD curl -f http://localhost/ || exit 1

Decision flow (Mermaid)

flowchart TD
  A[Начать: есть ли Docker на узлах?] -->|Нет| B[Установить Docker]
  A -->|Да| C[Настроить брандмауэр]
  C --> D{Нужно HA?}
  D -->|Да| E[Развернуть 3+ менеджера]
  D -->|Нет| F[Развернуть 1 менеджер]
  E --> G[Добавить worker'ы и deploy сервисы]
  F --> G
  G --> H[Тестирование и мониторинг]

Глоссарий (1 строка)

• Swarm Manager — узел, управляющий состоянием и планировщиком задач.
• Worker — узел, выполняющий контейнеры (tasks).
• Replica — экземпляр задачи сервиса.
• Overlay — сетевой драйвер для соединения контейнеров через узлы Swarm.

Типичные тестовые сценарии и критерии приёмки

• Тест: создать сервис на 3 реплики; Критерий: docker service ps показывает 3 задачи, каждая в Running.
• Тест: выключить один worker; Критерий: задачи перезапускаются на других доступных узлах.
• Тест: обновление образа; Критерий: сервис обновляется без одновременной остановки всех реплик (rolling update).

Заключение

Вы настроили Docker Swarm на Debian 11: установили Docker, настроили UFW, инициализировали менеджер, присоединили рабочие узлы и развернули тестовый сервис. Из этой точки можно расширять кластер (добавлять менеджеры для HA), интегрировать мониторинг и систему логирования, внедрять CI/CD-процессы и хранение секретов.

Рекомендуемые дальнейшие шаги:

• Настроить резервное копирование данных менеджеров и volumes.
• Интегрировать Prometheus/Grafana и централизованную систему логирования.
• Внедрить автоматизированные сценарии развёртывания и отката (CI/CD).

Конец руководства.