Come installare OpenSearch su Ubuntu 20.04

OpenSearch su Ubuntu 20.04 si installa in modo pulito se tratti subito tre aspetti: repository ufficiale, parametri del kernel richiesti da Elasticsearch-compatible stack e bootstrap del servizio. L’errore tipico non è l’installazione in sé, ma partire con una configurazione che funziona in locale e poi fallisce quando il nodo prova ad alzarsi come servizio systemd, soprattutto per memoria, file descriptor e network binding.

In questa guida parto da una macchina Ubuntu 20.04 aggiornata, con accesso sudo e nessun OpenSearch già presente. Se hai un cluster esistente, non copiare questi passaggi alla cieca: prima verifica compatibilità di versione, plugin già installati e policy di sicurezza del nodo.

Prerequisiti reali prima del pacchetto

OpenSearch è sensibile a risorse e tuning di sistema. Prima di installare, controlla che il nodo abbia spazio disco sufficiente, RAM adeguata e una versione recente del kernel. Su una singola VM di test puoi anche partire con risorse modeste, ma per un uso serio conviene ragionare almeno su 4 GB di RAM, meglio 8 GB o più, e su disco SSD.

Verifica la base della macchina con questi comandi:

lsb_release -a
uname -r
free -h
df -h

Atteso: Ubuntu 20.04, kernel supportato, spazio libero sul filesystem che ospiterà i dati e memoria sufficiente per assegnare almeno 1 GB di heap iniziale senza soffocare il sistema. Se il disco è già pieno o quasi, fermati qui: OpenSearch non è il punto da cui partire.

Importare il repository ufficiale OpenSearch

La via corretta è usare il repository ufficiale, non pacchetti sparsi o mirror non verificati. Questo riduce il rischio di versioni incoerenti con plugin e dipendenze. Su Ubuntu 20.04 servono i pacchetti per HTTPS e il repository GPG.

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

Ora importa la chiave e definisci il repository. Se stai lavorando in un ambiente con policy strette, conserva il fingerprint della chiave e verifica che coincida con quello pubblicato da OpenSearch prima di fidarti del pacchetto.

curl -fsSL https://artifacts.opensearch.org/publickeys/opensearch.pgp.key | sudo gpg --dearmor -o /usr/share/keyrings/opensearch-keyring.gpg

echo 'deb [signed-by=/usr/share/keyrings/opensearch-keyring.gpg] https://artifacts.opensearch.org/releases/bundle/opensearch/2.x/apt stable main' | sudo tee /etc/apt/sources.list.d/opensearch-2.x.list
sudo apt update

Se `apt update` restituisce errori di firma o di connessione, non andare avanti: prima risolvi DNS, proxy o ispezione TLS del tuo ambiente. Il risultato atteso è la presenza del repository senza warning di chiave scaduta o non verificata.

Installare OpenSearch con apt

A questo punto il pacchetto si installa in modo standard. La versione del ramo 2.x è quella più comune per installazioni recenti su Ubuntu 20.04, ma in ambienti esistenti devi allinearti alla tua baseline interna, non alla “ultima disponibile” per principio.

sudo apt install -y opensearch

Durante l’installazione il pacchetto crea l’utente di servizio, la directory dati e la configurazione in /etc/opensearch. Il binario e i file del servizio vengono registrati per systemd, quindi non serve creare manualmente unit file custom se non hai requisiti particolari.

Verifica subito che il pacchetto sia presente e che il servizio esista:

dpkg -l | grep opensearch
systemctl status opensearch --no-pager

Se il servizio risulta inattivo dopo l’installazione, è normale finché non hai completato il bootstrap. L’importante è che non compaiano errori di dipendenze mancanti o file non trovati.

Configurazione minima per un nodo singolo

Per un’installazione standalone, la configurazione più semplice è quella di un singolo nodo che non cerca altri peer. Questo evita di spendere tempo in discovery, seed hosts e quorum quando l’obiettivo è far partire il motore e verificare la catena base: servizio, API, storage e accesso HTTP.

Apri il file /etc/opensearch/opensearch.yml e imposta almeno questi valori. Prima di modificare, fai una copia del file: è il rollback minimo e più veloce.

sudo cp /etc/opensearch/opensearch.yml /etc/opensearch/opensearch.yml.bak.$(date +%F-%H%M)
sudo nano /etc/opensearch/opensearch.yml

Per un singolo nodo, una base sensata è questa:

cluster.name: opensearch-lab
node.name: node-1
network.host: 0.0.0.0
http.port: 9200
discovery.type: single-node
plugins.security.disabled: true

La riga plugins.security.disabled: true semplifica il primo avvio in laboratorio, ma non è una scelta da tenere in produzione esposta in rete. Se il nodo deve essere accessibile da altri host o da Internet, devi attivare la sicurezza, configurare TLS e credenziali, e non lasciare l’API HTTP aperta senza controllo.

Se invece vuoi partire con il plugin di sicurezza attivo, la procedura cambia: servono certificati, account iniziali e configurazione più lunga. In questo articolo il focus è l’installazione base, quindi mantengo il percorso più lineare e segnalo il punto di svolta dove la semplificazione non è più accettabile.

Impostare memoria e limiti di sistema

OpenSearch usa la JVM, quindi la heap va dimensionata con criterio. La regola pratica è non esagerare: metà della RAM disponibile è un tetto teorico, non un invito a usarla tutta. Su una VM piccola, 1 GB o 2 GB di heap sono spesso sufficienti per test e carichi leggeri.

Modifica il file /etc/opensearch/jvm.options oppure, se presente la directory delle opzioni aggiuntive, crea un file dedicato. Il vantaggio dello snippet separato è che non tocchi il file base e riduci il rischio di conflitti in aggiornamento.

sudo mkdir -p /etc/opensearch/jvm.options.d
sudo tee /etc/opensearch/jvm.options.d/heap.options > /dev/null <<'EOF'
-Xms1g
-Xmx1g
EOF

Controlla anche il requisito di memory locking e i limiti file descriptor. Se il servizio parte ma poi degrada o crasha sotto carico, spesso il problema è qui, non nella configurazione del cluster.

ulimit -n
ulimit -l

Per un setup robusto, verifica che systemd non applichi limiti troppo bassi. Puoi ispezionare l’unit del servizio con:

systemctl cat opensearch

Se devi intervenire, usa un drop-in invece di editare l’unit file principale. Così il rollback è immediato e non perdi le modifiche in caso di aggiornamento del pacchetto.

Avviare il servizio e leggere i log giusti

Con la configurazione minima pronta, avvia il servizio e osserva lo stato reale, non solo il fatto che il comando sia tornato senza errori. La prima lettura utile è sempre quella di systemd, seguita dai log applicativi.

sudo systemctl daemon-reload
sudo systemctl enable --now opensearch
systemctl status opensearch --no-pager
journalctl -u opensearch -n 100 --no-pager

Se il servizio non parte, guarda la coda dei log e non fare ipotesi a vuoto. Gli errori più frequenti sono: permessi sulla directory dati, heap troppo alta, rete legata a un indirizzo non presente, o security plugin non coerente con la configurazione scelta.

Una macchina ben configurata, al primo avvio, deve mostrare il servizio in stato active (running) e l’ascolto sulla porta 9200. Se il processo si avvia e poi muore, il problema è quasi sempre leggibile nei log delle prime decine di righe.

Verificare l’API HTTP locale

Il test minimo è una richiesta HTTP verso il nodo. Se hai disabilitato la sicurezza per il laboratorio, il controllo è semplice; se la sicurezza è attiva, dovrai usare HTTPS e credenziali adeguate. Qui assumo il caso base senza TLS.

curl -s http://127.0.0.1:9200/

Atteso: un JSON con nome del cluster, nome del nodo, versione e tag di build. Puoi anche controllare lo stato del cluster:

curl -s http://127.0.0.1:9200/_cluster/health?pretty

Per un single node, lo stato iniziale può essere yellow se non ci sono repliche assegnabili. Non è automaticamente un errore. L’errore vero è red persistente o una risposta vuota/timeout, che indica un problema di avvio, binding o storage.

Aprire la porta verso l’esterno senza fare danni

Se il nodo deve essere raggiungibile da un host remoto, non limitarti a cambiare network.host. Devi anche controllare firewall, security group e, se presente, reverse proxy o bilanciamento. Esporre la porta 9200 direttamente su Internet senza controllo è una cattiva idea, anche in laboratorio.

Per un accesso controllato su LAN, verifica prima che il servizio ascolti davvero sull’interfaccia corretta:

ss -lntp | grep 9200

Se usi UFW, abilita la porta solo dall’IP o dalla subnet necessaria. Esempio su rete privata:

sudo ufw allow from 192.168.1.0/24 to any port 9200 proto tcp
sudo ufw status verbose

Il controllo finale non è il firewall in sé, ma una prova da un client autorizzato con curl. Se il nodo risponde solo in locale e non da remoto, il problema è quasi sempre nella catena rete/firewall, non nel demone OpenSearch.

Plugin utili e installazione post-pacchetto

OpenSearch supporta plugin installabili dopo il pacchetto base. La gestione dipende dal caso d’uso: alerting, index management, SQL, dashboards integration e altro. Il punto operativo è che ogni plugin va trattato come parte della baseline del nodo, quindi documentato e versionato insieme alla configurazione.

Per vedere i plugin già presenti:

sudo /usr/share/opensearch/bin/opensearch-plugin list

Per installarne uno, la sintassi tipica è questa, ma cambia in base al plugin scelto:

sudo /usr/share/opensearch/bin/opensearch-plugin install <nome-plugin>

Ogni installazione di plugin va seguita da un riavvio del servizio e da una verifica dei log. Se un plugin rompe l’avvio, il rollback minimo è la sua rimozione e il ripristino del file di configurazione precedente.

Hardening minimo da non rimandare

Anche in un’installazione di base conviene impostare subito alcune misure minime: non esporre l’API senza necessità, limitare l’accesso alla porta 9200, tenere il servizio aggiornato e usare credenziali o TLS quando il nodo non è confinato a localhost.

Se hai lasciato la sicurezza disabilitata per il bootstrap, trattala come una condizione temporanea. Il nodo non dovrebbe rimanere in quello stato se riceve traffico da altri segmenti di rete. Il passaggio successivo, in un ambiente reale, è configurare il security plugin con certificati, admin password gestite in modo sicuro e policy coerenti.

Evita di salvare segreti in chiaro dentro script di deploy o note operative. Se devi automatizzare, usa variabili d’ambiente protette, vault o meccanismi equivalenti del tuo stack. La differenza tra un setup pulito e uno fragile spesso è tutta qui.

Percorso di troubleshooting quando il nodo non sale

Se l’installazione è andata a buon fine ma il servizio resta fermo, la sequenza di controllo più rapida è sempre la stessa: stato systemd, log recenti, binding di rete, permessi filesystem, heap. In pratica: prima osservi, poi cambi. Non ha senso toccare cinque file alla cieca.

I controlli più utili sono questi:

systemctl status opensearch --no-pager
journalctl -u opensearch -n 200 --no-pager
sudo ls -ld /var/lib/opensearch /var/log/opensearch /etc/opensearch
sudo ss -lntp | grep -E '9200|9300'

Se vedi errori di permesso, correggi ownership e verifica che il servizio giri come utente opensearch. Se vedi errori di memoria, abbassa la heap. Se il nodo non riesce a fare bind su 0.0.0.0, controlla che non ci siano conflitti di rete o configurazioni residue di installazioni precedenti.

Verifica finale dell’installazione

Un’installazione riuscita non è solo “pacchetto presente”. Devi vedere il servizio attivo, l’endpoint HTTP rispondere, il cluster in stato coerente con il tipo di installazione e i log puliti. Solo allora puoi considerare la macchina pronta per il passo successivo: dati reali, ingestion, snapshot o integrazione con OpenSearch Dashboards.

Checklist minima:

• Servizio: systemctl is-active opensearch deve restituire active.

• API: curl -s http://127.0.0.1:9200/ deve tornare JSON valido.

• Log: journalctl -u opensearch -n 50 non deve mostrare stack trace persistenti.

• Porta: ss -lntp | grep 9200 deve mostrare il processo in ascolto.

Se uno di questi punti fallisce, non andare avanti con l’installazione di componenti sopra OpenSearch. Prima chiudi il problema di base: il motore deve alzarsi in modo ripetibile e prevedibile. Solo dopo ha senso costruire dashboard, pipeline e automazioni intorno.

Con questa procedura hai un’installazione pulita su Ubuntu 20.04, con un percorso di rollback semplice: ripristino di /etc/opensearch/opensearch.yml, rimozione di eventuali snippet heap personalizzati, disinstallazione del pacchetto e pulizia del repository se necessario. L’assunzione operativa è un nodo singolo di laboratorio o pre-produzione; per ambienti esposti o multi-nodo, il salto di complessità riguarda soprattutto sicurezza, discovery e sizing, non il solo comando di installazione.