Installare un cluster Apache ZooKeeper a nodo singolo su Ubuntu 18.04

Perché usare ZooKeeper

Apache ZooKeeper è un servizio centralizzato open source per la gestione di informazioni di configurazione, naming, sincronizzazione distribuita e provisioning di servizi di gruppo. È pensato per memorizzare dati di stato, configurazioni e informazioni di localizzazione in una struttura gerarchica di nodi (Znodes). Progettato per alta disponibilità, throughput elevato e bassa latenza, ZooKeeper è spesso usato come coordinatore per sistemi distribuiti.

Nota: in produzione è raccomandato usare un cluster con un numero dispari di nodi (di solito 3 o 5) per garantire tolleranza ai guasti. Questa guida copre la configurazione iniziale su un singolo nodo utile per test e sviluppo.

Requisiti

• Un server con Ubuntu 18.04.
• Accesso root o un account con privilegi sudo e password impostata.
• Connessione internet per scaricare pacchetti.

Sommario dei passaggi

1. Aggiornare il sistema.
2. Installare Java (Oracle Java 11 in questo esempio).
3. Creare l’utente zookeeper.
4. Scaricare ed estrarre ZooKeeper.
5. Creare la configurazione e avviare il servizio.
6. Creare un’unità systemd per la gestione del servizio.

Aggiornare il sistema

Aggiorna i repository e i pacchetti di sistema:

apt-get update -y  
 apt-get upgrade -y

Dopo l’aggiornamento, riavvia il server se necessario per applicare le modifiche.

Installare Java

ZooKeeper è scritto in Java, quindi è necessario installare Java 11. In Ubuntu 18.04 la versione Oracle non è sempre presente nei repository predefiniti; la guida originale usa il PPA linuxuprising per Oracle Java:

add-apt-repository ppa:linuxuprising/java

Aggiorna e installa Java:

apt-get update -y  
 apt-get install oracle-java11-set-default

Verifica l’installazione:

java --version

Output atteso (esempio):

java 11.0.2 2018-10-16 LTS
Java(TM) SE Runtime Environment 18.9 (build 11.0.2+7-LTS)
Java HotSpot(TM) 64-Bit Server VM 18.9 (build 11.0.2+7-LTS, mixed mode)

Se preferisci una variante OpenJDK, puoi installare openjdk-11-jdk invece di Oracle Java con: apt-get install openjdk-11-jdk

Creare l’utente ZooKeeper

Per eseguire ZooKeeper con privilegi limitati, crea un utente dedicato:

useradd zookeeper -m  
 usermod --shell /bin/bash zookeeper

Imposta la password:

passwd zookeeper

Aggiungi l’utente al gruppo sudo se necessario:

usermod -aG sudo zookeeper

Installare ZooKeeper

Crea la struttura per i dati di ZooKeeper:

mkdir -p /data/zookeeper

Imposta proprietà e permessi:

chown -R zookeeper:zookeeper /data/zookeeper

Scarica e installa ZooKeeper (l’esempio utilizza la versione 3.4.9 dall’archivio Apache):

cd /opt  
 wget https://archive.apache.org/dist/zookeeper/zookeeper-3.4.9/zookeeper-3.4.9.tar.gz

Estrai e rinomina la directory:

tar -xvzf zookeeper-3.4.9.tar.gz
mv zookeeper-3.4.9 zookeeper

Imposta l’ownership:

chown -R zookeeper:zookeeper /opt/zookeeper

Nota: puoi scegliere una versione più recente di ZooKeeper; verifica le note di rilascio per eventuali modifiche di configurazione o requisiti.

Configurare ZooKeeper

Crea il file di configurazione principale:

nano /opt/zookeeper/conf/zoo.cfg

Aggiungi queste righe:

tickTime=2500
dataDir=/data/zookeeper
clientPort=2181
maxClientCnxns=80

Salva e chiudi il file.

Avviare ZooKeeper manualmente

Avvia il server ZooKeeper dalla directory di installazione:

cd /opt/zookeeper  
 bin/zkServer.sh start

Output atteso:

ZooKeeper JMX enabled by default
Using config: /opt/zookeeper/bin/../conf/zoo.cfg
Starting zookeeper ... STARTED

Collega il client locale:

bin/zkCli.sh -server 127.0.0.1:2181

Prompt di esempio quando connesso:

[zk: 127.0.0.1:2181(CONNECTED) 1]

Digita help per vedere i comandi disponibili:

help
ZooKeeper -server host:port cmd args
    stat path [watch]
    set path data [version]
    ls path [watch]
    delquota [-n|-b] path
    ls2 path [watch]
    setAcl path acl
    setquota -n|-b val path
    history 
    redo cmdno
    printwatches on|off
    delete path [version]
    sync path
    listquota path
    rmr path
    get path [watch]
    create [-s] [-e] path data acl
    addauth scheme auth
    quit 
    getAcl path
    close 
    connect host:port

Esci con quit. Per fermare il server manualmente:

bin/zkServer.sh stop

Output di esempio:

ZooKeeper JMX enabled by default
Using config: /opt/zookeeper/bin/../conf/zoo.cfg
Stopping zookeeper ... STOPPED

Creare un’unità systemd per ZooKeeper

Per gestire ZooKeeper come servizio di sistema crea il file:

nano /etc/systemd/system/zookeeper.service

Inserisci:

[Unit]
Description=Zookeeper Daemon
Documentation=http://zookeeper.apache.org
Requires=network.target
After=network.target

[Service]    
Type=forking
WorkingDirectory=/opt/zookeeper
User=zookeeper
Group=zookeeper
ExecStart=/opt/zookeeper/bin/zkServer.sh start /opt/zookeeper/conf/zoo.cfg
ExecStop=/opt/zookeeper/bin/zkServer.sh stop /opt/zookeeper/conf/zoo.cfg
ExecReload=/opt/zookeeper/bin/zkServer.sh restart /opt/zookeeper/conf/zoo.cfg
TimeoutSec=30
Restart=on-failure

[Install]
WantedBy=default.target

Ricarica systemd e abilita il servizio:

systemctl daemon-reload
systemctl start zookeeper  
 systemctl enable zookeeper

Verifica lo stato:

systemctl status zookeeper

Esempio di output:

? zookeeper.service - Zookeeper Daemon
   Loaded: loaded (/etc/systemd/system/zookeeper.service; disabled; vendor preset: enabled)
   Active: active (running) since Wed 2019-03-06 15:03:01 UTC; 5s ago
     Docs: http://zookeeper.apache.org
  Process: 3909 ExecStart=/opt/zookeeper/bin/zkServer.sh start /opt/zookeeper/conf/zoo.cfg (code=exited, status=0/SUCCESS)
 Main PID: 3926 (java)
    Tasks: 17 (limit: 1113)
   CGroup: /system.slice/zookeeper.service
           ??3926 java -Dzookeeper.log.dir=. -Dzookeeper.root.logger=INFO,CONSOLE -cp /opt/zookeeper/bin/../build/classes:/opt/zookeeper/bin/..

Mar 06 15:03:00 ubuntu1804 systemd[1]: Starting Zookeeper Daemon...
Mar 06 15:03:00 ubuntu1804 zkServer.sh[3909]: ZooKeeper JMX enabled by default
Mar 06 15:03:00 ubuntu1804 zkServer.sh[3909]: Using config: /opt/zookeeper/conf/zoo.cfg
Mar 06 15:03:01 ubuntu1804 zkServer.sh[3909]: Starting zookeeper ... STARTED
Mar 06 15:03:01 ubuntu1804 systemd[1]: Started Zookeeper Daemon.

Controlli e verifica post-installazione

• Connetti il client e crea un nodo di prova:

create /test-node "hello"
get /test-node

• Controlla i permessi della directory dei dati:

`` ls -ld /data/zookeeper ``` - Verifica che il processo Java del server sia attivo: ps aux | grep -i zookeeper ## Criteri di accettazione - Il servizio systemd zookeeper è attivo e abilitato: systemctl is-active zookeeper → active - Il client zkCli.sh si connette correttamente e può creare/leggere nodi - I file di dati sono scritti in /data/zookeeper con ownership zookeeper:zookeeper - I log di ZooKeeper non presentano errori critici all’avvio ## Check-list operativa (Ruoli) - Amministratore di sistema: - [ ] Aggiornare pacchetti e kernel (se necessario) - [ ] Installare Java e verificare versione - [ ] Creare utente zookeeper e impostare permessi - [ ] Configurare systemd e policy di log rotation - SRE/DevOps: - [ ] Integrare monitoraggio (JMX, metriche) e backup dei dati - [ ] Testare failover in ambiente staging con cluster multi-nodo - [ ] Automatizzare installazione con Ansible/Terraform - Sviluppatori: - [ ] Usare client API per leggere/scrivere Znodes in ambiente di test - [ ] Evitare dipendenze troppo strette alla struttura dei path ## Migrare a un cluster multi-nodo (note rapide) - Per HA creare almeno 3 nodi (o 5) con tickTime, dataDir, clientPort e aggiungere le linee server.X=host:peerPort:leaderPort nel file zoo.cfg. - Assicurati che i nodi abbiano orologi sincronizzati (NTP) e connettività di rete affidabile. - Esegui test di quorum e failover in ambiente non produttivo prima della migrazione. ## Sicurezza e hardening (punti chiave) - Limitare l’accesso alla porta 2181 tramite firewall (UFW/iptables). - Abilitare l’autenticazione (SASL) e ACL per Znodes se i client lo richiedono. - Eseguire ZooKeeper dietro una rete privata/VPC in produzione. - Abilitare rotazione dei log e backup periodico della directory dataDir. Important: non esporre direttamente la porta client di ZooKeeper su internet pubblico. ## Troubleshooting comuni - Problema: zkCli.sh non si connette → verificare che il servizio sia in ascolto su 127.0.0.1:2181 e che non ci siano firewall che blocchino la porta. - Problema: Permessi su /data/zookeeper → assicurarsi che ownership sia zookeeper:zookeeper e che il processo sia eseguito dall’utente zookeeper. - Problema: Errore di porta già in uso → controllare altri processi su 2181 con netstat -tulpn. ## Esempio di runbook per arresto d’emergenza e rollback 1. Se ZooKeeper non risponde e impatta il cluster applicativo, notificare le parti interessate. 2. Verificare i log in /opt/zookeeper/logs o dove sono configurati. 3. Se necessario, fermare il servizio: systemctl stop zookeeper. 4. Ripristinare il file di configurazione valido da backup e riavviare: systemctl start zookeeper. 5. Se il nodo è parte di un cluster, valutare se deve essere isolato fino alla risoluzione. ## Test di accettazione (minimo) - Test 1: Avvio - Azione: systemctl start zookeeper - Risultato atteso: servizio attivo, PID Java attivo - Test 2: Creazione nodo - Azione: bin/zkCli.sh create /ci-test “ok” - Risultato atteso: nodo creato e lettura con bin/zkCli.sh get /ci-test restituisce “ok” - Test 3: Permessi - Azione: ls -la /data/zookeeper - Risultato atteso: proprietà zookeeper:zookeeper ## Piccola metodologia per deploy ripetibili - Automatizza: crea playbook Ansible per: - Installare Java - Creare utente e directory - Scaricare versione specifica di ZooKeeper - Configurare zoo.cfg e systemd - Versiona: mantieni in repository la versione usata e i template di configurazione. - Testa: esegui test di integrazione in ambiente CI prima del deploy in produzione. ## Glossario rapido - Znode: unità dati in ZooKeeper, simile a un file o directory in un namespace gerarchico. - tickTime: unità di tempo base (ms) usata da ZooKeeper per heartbeat e timeout. - quorum: numero minimo di nodi necessari per prendere decisioni nel cluster. ## Annuncio breve (per comunicazione interna, 100–200 parole) Ho installato e configurato un’istanza Apache ZooKeeper a nodo singolo su Ubuntu 18.04 per scopi di test e sviluppo. La procedura comprende aggiornamento sistema, installazione di Java 11, creazione dell’utente zookeeper, installazione di ZooKeeper 3.4.9, configurazione di base (clientPort 2181, dataDir /data/zookeeper) e registrazione del servizio in systemd. Il servizio è avviato e verificato tramite zkCli.sh. Per l’ambiente di produzione raccomando la migrazione a un cluster con almeno tre nodi, NTP sincronizzato, controlli di sicurezza sulle porte e monitoraggio JMX. ## Riepilogo - Hai installato ZooKeeper e verificato il funzionamento locale. - In produzione serve un cluster multi-nodo per alta disponibilità. - Automatizza l’installazione e integra monitoraggio e backup. Se vuoi, posso generare un playbook Ansible per automatizzare tutti i passaggi, o una versione aggiornata della guida per Ubuntu 20.04/22.04 e ZooKeeper più recente.