Docker Swarm consente di creare un cluster di host Docker (nodi) per distribuire e gestire applicazioni containerizzate. Il cluster è composto da uno o piú nodi manager (Docker consiglia un massimo di sette per cluster), che orchestrano le attività e comunicano con i worker, che eseguono i singoli task. Questo sistema garantisce tolleranza agli errori: se un nodo fallisce, il manager ridistribuisce automaticamente le attività su altri nodi. Se il nodo manager si blocca, lo swarm continua a funzionare normalmente, poiché i worker eseguono ancora i container assegnati. Tuttavia, non sarà possibile interagire con il cluster (ad esempio per monitorarne lo stato o effettuare nuove distribuzioni) fino a quando non verrà ripristinato o sostituito il nodo manager. Per questo motivo, è consigliabile configurare più nodi manager, in modo che in caso di guasto del manager primario, un altro possa assumere il controllo senza interruzioni nel monitoraggio e nella gestione del cluster.

MicroCeph, invece, è il modo più semplice per iniziare a utilizzare Ceph, un sistema di storage distribuito open source. Grazie alla sua architettura decentralizzata e distribuita, Ceph distribuisce il carico su molteplici nodi, offrendo così una robusta tolleranza ai guasti, garantendo la continuità del servizio. Ceph supporta vari tipi di storage, tra cui:

• storage a oggetti
• storage a blocchi
• file system distribuito

Creazione di un cluster Docker Swarm #

Security Group #

Innanzitutto, è necessario creare un security group, definendo le regole da applicare alle varie VM, così da non dover creare le regole per ogni singolo host. Per approfondimenti, consultare l’articolo su come gestire il firewall di PVE. In particolare, occorre consentire il traffico dalle seguenti porte:

• porta 2377 TCP: utilizzata per la comunicazione tra i nodi manager
• porta 7946 TCP/UDP: necessaria per il discovery dei nodi
• porta 4789 UDP: Swarm VXLAN port
• porte 6800-7300 TCP: dedicata agli OSD di Ceph
• porta 3300 TCP: utilizzata dai Ceph clients e dai Ceph daemons per connettersi al Ceph Monitor. Questa porta è la scelta preferita rispetto alla 6789
• porta 6789 TCP: alternativa da utilizzare se la porta 3300 non fosse disponibile
• porta 22 (SSH) dalla LAN: per consente connessioni SSH dalla rete 192.168.0.0/24

Per semplicità, si puo’ decidere di consentire tutto il traffico tra i nodi

Creazione VM #

Si consiglia di creare una VM template con Docker e MicroCeph già installati, da clonare successivamente per realizzare il cluster. Per procedere con la creazione, seguire questi passaggi:

Aggiungere ora Cloud-Init:

Impostare quindi l’utente, la password, la rete, ecc. e cliccare Regenerate Image

Scaricare sulla propria macchina l’immagine disco genericcloud di Debian da Official Cloud Images nel formato qcow2 e, tramite rsync, spostarla sul nodo PVE in /var/lib/vz/template/qcow:

[17:57 Sat Apr 12]dado@dadopc (3230):~
rsync -Pz debian-12-genericcloud-amd64-20250316-2053.qcow2 pve:/var/lib/vz/template/qcow/

root@pve:/var/lib/vz/template/qcow# ll
total 327M
-rw-r--r-- 1 root root 329M Apr  5 17:11 debian-12-genericcloud-amd64-20250316-2053.qcow2

Quindi importare il disco sulla VM appena creata:

qm disk import 202 debian-12-genericcloud-amd64-20250316-2053.qcow2 local-zfs

Assegnare ora il disco alla VM:

Assegnare il security group creato in precedenza:

Infine, possiamo avviare la VM e verificare che la rete funzioni. Si consiglia di installare il pacchetto qemu-guest-agent:

apt install qemu-guest-agent
systemctl enable --now qemu-guest-agent

Assicurarsi che il boot order sia corretto

Se tutto é funziona come previsto, si consiglia di eseguire uno snapshot.

Docker #

Per installare docker su Debian, seguire la guida ufficiale

MicroCeph #

Per installare MicroCeph su Debian, seguire i passaggi indicati da Canonical:

apt install snapd
snap install snapd
snap install microceph

Quindi procedere coi seguenti passaggi:

apt install ceph-common
systemctl enable ceph.target

ln -s /var/snap/microceph/current/conf/ceph.keyring /etc/ceph/ceph.keyring
n -s /var/snap/microceph/current/conf/ceph.conf /etc/ceph/ceph.conf

Infine, dare il comando truncate -s 0 /etc/machine-id.

Creazione dei nodi #

Spegnere la VM e procedere con la clonazione, in modo ottenere il numero di nodi desiderato. Nel nostro caso, creeremo tre nodi:

Ricordarsi di assegnare gli indirizzi IP corretti alle VM da Cloud-Init, cliccando poi il pulsante Regenerate Image. Nel nostro caso:

swarm-master: 10.10.1.10

swarm-worker1: 10.10.1.11

swarm-worker2: 10.10.1.12

Creazione di uno swarm #

Dal nodo manager, dare il comando:

docker swarm init --advertise-addr <MANAGER-IP>

root@swarm-master:~# docker swarm init --advertise-addr 10.10.1.10

L’output dovrebbe essere simile al seguente:

docker swarm init --advertise-addr 10.10.1.10
Swarm initialized: current node (dxn1zf6l61qsb1josjja83ngz) is now a manager.

To add a worker to this swarm, run the following command:

    docker swarm join \
    --token SWMTKN-1-49nj1cmql0jkz5s954yi3oex3nedyz0fb0xx14ie39trti4wxv-8vxv8rssmk743ojnwacrr2e7c \
    10.10.1.10:2377

To add a manager to this swarm, run 'docker swarm join-token manager' and follow the instructions.

Aggiungere nodi al cluster swarm #

Dai due nodi worker:

docker swarm join --token <token-id> 10.10.1.10:2377

Dal nodo manager si dovrebbero vedere tutti i nodi appartenenti al cluster:

root@swarm-master:~# docker node ls
ID                            HOSTNAME        STATUS    AVAILABILITY   MANAGER STATUS   ENGINE VERSION
03g1y59jwfg7cf99w4lt0f662 *   swarm-master    Ready     Active         Leader           28.0.4
9j68exjopxe7wfl6yuxml7a7j     swarm-worker1   Ready     Active                          28.0.4
dxn1zf6l61qsb1josjja83ngz     swarm-worker2   Ready     Active                          28.0.4

Microceph multi-node cluster #

Un cluster Ceph richiede come minimo tre OSD (Object Storage Daemon). Questo significa che, per formare un cluster stabile ed efficiente, ognuna delle tre macchine deve avere un disco dedicato esclusivamente per Ceph.

Iniziamo quindi aggiungendo, su tutte le VM, un secondo disco di storage dedicato a MicroCeph:

Ora bisogna impedire che MicroCeph si aggiorni automaticamente:

snap refresh --hold microceph

Per creare un cluster, ogni nodo deve avere la stessa versione del software installata e non deve essere soggetto ad aggiornamenti automatici che potrebbero introdurre modifiche non controllate. Quindi, è necessario disabilitare gli aggiornamenti su ciascun nodo.

Sul nodo master eseguire il comando per inizializzare il cluster: microceph cluster bootstrap. Si devono quindi generare i token necessari per aggiungere gli altri nodi. Sempre dal master:

microceph cluster add <node-name>

eyJuYW1lIjoibm9kZS0yIiwic2VjcmV0IjoiYmRjMzZlOWJmNmIzNzhiYzMwY2ZjOWVmMzRjNDM5YzNlZTMzMTlmZDIyZjkxNmJhMTI1MzVkZmZiMjA2MTdhNCIsImZpbmdlcnByaW50IjoiMmU0MmEzYjEwYTg1MDcwYTQ1MDcyODQxZjAyNWY5NGE0OTc4NWU5MGViMzZmZGY0ZDRmODhhOGQyYjQ0MmUyMyIsImpvaW5fYWRkcmVzc2VzIjpbIjEwLjI0Ni4xMTQuMTE6NzQ0MyJdfQ==

Aggiunta dei nodi al cluster #

Per effettuare il join, eseguire il comando seguente sui rispettivi nodi:

microceph cluster join <join token>

Aggiunta dello storage #

Su tutti i nodi, eseguire il comando seguente per aggiungere il disco al cluster MicroCeph:

microceph disk add </path/to/device> --wipe

Per vedere la lista dei dischi:

root@master:~# microceph disk list
Disks configured in MicroCeph:
+-----+----------+------------------------------------------------------+
| OSD | LOCATION |                         PATH                         |
+-----+----------+------------------------------------------------------+
| 1   | master   | /dev/disk/by-id/scsi-0QEMU_QEMU_HARDDISK_drive-scsi2 |
+-----+----------+------------------------------------------------------+
| 2   | node1    | /dev/disk/by-id/scsi-0QEMU_QEMU_HARDDISK_drive-scsi2 |
+-----+----------+------------------------------------------------------+
| 3   | node2    | /dev/disk/by-id/scsi-0QEMU_QEMU_HARDDISK_drive-scsi2 |
+-----+----------+------------------------------------------------------+

Controllare lo status di MicroCeph #

Su uno qualsiasi dei tre nodi, si puo’ invocare il seguente comando per controllare lo stato di MicroCeph:

microceph status

root@swarm-master:~# microceph status
MicroCeph deployment summary:
- swarm-master (10.10.1.10)
  Services: mds, mgr, mon, osd
  Disks: 1
- swarm-worker1 (10.10.1.11)
  Services: mds, mgr, mon, osd
  Disks: 1
- swarm-worker2 (10.10.1.12)
  Services: mds, mgr, mon, osd
  Disks: 1

Oltre ai comandi specifici di MicroCeph, è possibile utilizzare gli strumenti nativi di Ceph per compiti amministrativi. Ad esempio, il comando ceph status fornisce informazioni dettagliate sullo stato di salute del cluster e dei servizi (monitor, manager e OSD).

Per maggiori informazioni, leggere la guida Multi-node install.

CephFS #

CephFS è un filesystem distribuito progettato per offrire scalabilità, disponibilità e resilienza. Un filesystem Ceph richiede almeno due pool RADOS: uno per i dati e uno per i metadati. I dati sono i file effettivi, mentre i metadati contengono informazioni sul filesystem, come la struttura delle directory e i permessi dei file.

Dal nodo master, dare i seguenti comandi per creare i due pool:

ceph osd pool create cephfs_data <pg_num>
ceph osd pool create cephfs_metadata <pg_num>

Per creare il filesystem:

ceph fs new <fs_name> <metadata> <data>

ceph fs new cephfs cephfs_metadata cephfs_data

Per vedere i filesystem presenti sul sistema:

root@master:~# ceph fs ls
name: cephfs, metadata pool: cephfs_metadata, data pools: [cephfs_data ]

fstab #

Se si desidera che il filesystem si monti automaticamente al boot, aggiungerlo a /etc/fstab su tutti i nodi del cluster:

{mon-ipaddress}:{port}:/ {mount}/{mountpoint} {filesystem-name} [name=username,secret=secretkey|secretfile=/path/to/secretfile],[{mount.options}]

Nel nostro caso:

10.10.1.10:6789,10.10.1.11:6789,10.10.1.12:6789:/ /mnt/cephfs ceph name=admin,secret=mysecret,noatime,_netdev,x-systemd.automount 0 2

In particolare:

• noatime: impedisce l’aggiornamento dei timestamp di accesso ai file (atime) ogni volta che un file viene letto. È utile per migliorare le prestazioni su filesystem con accessi frequenti
• _netdev: indica che il filesystem dipende dalla rete. Viene utilizzato per evitare che il sistema tenti di montare il filesystem prima che la rete sia completamente attiva
• x-systemd.automount: questa opzione gestisce il montaggio automatico del filesystem tramite systemd

La secret-key si trova in /var/snap/microceph/current/conf/ceph.keyring o in /etc/ceph/ (se é stato creato il link simbolico, come indicato durante la creazione del template).

Su tutti i nodi, dare quindi il comando systemctl daemon-reload e successivamente mount -a in modo che il filesystem sia montato in automatico.

Perform IO #

Un rapido test a filesystem montato:

cd /mnt/mycephfs
dd if=/dev/zero of=random.img count=1 bs=50M

Deploying di una webpage #

Ora che il filesystem é montato, creare da uno qualsiasi dei nodi la directory /mnt/cephfs/html e il file index.html al suo interno, col seguente contenuto:

<!DOCTYPE html>
<html lang="it">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Benvenuto in questa pagina web!</title>
</head>
<body>
    <h1>Benvenuto in questa semplicissima pagina web!</h1>
    <p>Questa pagina è servita tramite Nginx e Docker Compose</p>
</body>
</html>

Sul nodo master creare il file docker-compose.yml:

services:
  webapp:
    image: nginx:latest
    volumes:
      - /mnt/cephfs/html:/usr/share/nginx/html  # Monta la cartella ./html nel container
    ports:
      - "8080:80"
    deploy:
      replicas: 3

Importante: creare la regola per consentire l’accesso alla porta 8080 delle VM dalla rete 192.168.0.0/24 dal Security Group di PVE

Ora possiamo avviare lo stack:

docker stack deploy --compose-file docker-compose.yml mystack

Vediamo che é correttamente replicato:

root@master:~# docker service ls
ID             NAME             MODE         REPLICAS   IMAGE          PORTS
8qtykdiq1y0w   mystack_webapp   replicated   3/3        nginx:latest   *:8080->80/tcp

Accedendo al browser web e collegandosi agli indirizzi http://10.10.1.10:8080/ (master), http://10.10.1.11:8080/ (nodo1) o http://10.10.1.12:8080/ (nodo2), sarà visibile la seguente pagina web:

Nel caso in cui uno dei nodi riscontri problemi, la pagina web rimarrà comunque accessibile tramite gli altri nodi, grazie anche al filesystem distribuito, garantendo così la resilienza e la continuità del servizio.

Per rimuovere lo stack utilizzare il comando: docker stack rm mystack dal master-node dello swarm.

Video #

Un ottimo video che riassume molti passaggi:

Riferimenti #

Docker #

• Create a swarm
• Install
• Deploy the stack to the swarm

MicroCeph #

• Install MicroCeph on Debian
• MicroCeph documentation
• Ceph Firewall Ports
• Try Microceph for an Easy Ceph Install
• How I Deployed a Self-Hosting Stack with Docker Swarm & MicroCeph
• How to mount ceph fs with Microceph?

CephFS #

• Create CephFS
• Mount CephFS
• Mount CephFS in fstab
• CephFS for Docker Container Storage
• Ceph Dashboard Install and Configuration for Microceph

Nginx Proxy Manager #

• Quick Setup