Come eseguire il backup e ripristinare la tua istanza Jenkins

Jenkins diventa spesso il piano di controllo per le tue build, distribuzioni, credenziali e cronologia delle release. Se perdi $JENKINS_HOME durante un guasto del disco o una migrazione errata, le tue pipeline CI/CD potrebbero fermarsi anche se il pacchetto Jenkins stesso è facile da reinstallare.

Questa guida mostra cosa eseguire il backup, come creare un archivio del filesystem in modo sicuro e come ripristinare Jenkins senza rompere le credenziali o la proprietà dei file.

Comprendere il nucleo: la directory $JENKINS_HOME

Ogni istanza Jenkins si basa su un'unica directory root, denominata $JENKINS_HOME. Questa directory contiene tutti i file di configurazione, plugin, log e dati dei job. Eseguire il backup di Jenkins significa fondamentalmente eseguire il backup del contenuto di questa directory.

A seconda del metodo di installazione (ad esempio, pacchetto Linux, container Docker), la posizione di $JENKINS_HOME varia tipicamente:

• Linux (Installazione tramite pacchetto): /var/lib/jenkins
• Docker: Spesso montato su un volume, ad esempio /var/jenkins_home
• JAR standalone: La directory in cui è stato avviato il processo Jenkins, a meno che non sia specificata tramite variabili d'ambiente.

Identificazione dei componenti critici dei dati

Sebbene eseguire il backup dell'intera directory $JENKINS_HOME sia l'approccio più semplice, può portare ad archivi estremamente grandi se vengono inclusi la cronologia delle build e i dati dell'area di lavoro. Per un backup di ripristino di emergenza rapido ed efficiente, è necessario assicurarsi che le seguenti directory e file vengano catturati:

Componente	Percorso all'interno di $JENKINS_HOME	Scopo
Configurazione globale	config.xml	File di configurazione primario per l'istanza root di Jenkins.
Definizioni dei job	jobs/	Contiene sottodirectory per ogni job configurato, ciascuna con il proprio config.xml.
Utenti e credenziali	users/ e credentials.xml	Account utente, impostazioni del realm di sicurezza e segreti memorizzati.
Chiavi di sicurezza	secrets/	Chiavi di crittografia essenziali per decrittografare dati sensibili come le credenziali memorizzate.
Elenco plugin	plugins/	Contiene i file .hpi per tutti i plugin installati.
Definizioni dei nodi	nodes/	Configurazioni per tutti gli agent di build connessi (se definiti).

---

Metodo 1: Il backup del filesystem (Consigliato)

Il metodo più affidabile per eseguire il backup di Jenkins è creare un archivio coerente e compresso dei file necessari mentre il servizio viene momentaneamente arrestato.

Passo 1: Arrestare il servizio Jenkins

Per garantire la coerenza dei dati e prevenire scritture parziali dei file durante il processo di backup, il processo Jenkins deve essere arrestato. Non riuscire ad arrestare il servizio rischia un backup incompleto o corrotto.

# Per sistemi che utilizzano systemd (la maggior parte delle distribuzioni Linux moderne)
sudo systemctl stop jenkins

# Oppure, per sistemi che utilizzano il comando service
sudo service jenkins stop

Passo 2: Creare l'archivio di backup

Naviga nella directory padre di $JENKINS_HOME e usa tar per creare un archivio compresso. Si consiglia vivamente di escludere i grandi artefatti di build per risparmiare spazio e tempo.

Supponendo che $JENKINS_HOME sia /var/lib/jenkins:

JENKINS_HOME="/var/lib/jenkins"
BACKUP_TARGET="/mnt/backups/jenkins"
TIMESTAMP=$(date +%Y%m%d_%H%M%S)
ARCHIVE_NAME="jenkins_backup_${TIMESTAMP}.tar.gz"

# Crea la directory di destinazione se non esiste
mkdir -p $BACKUP_TARGET

# Crea l'archivio, escludendo la cronologia delle build e le aree di lavoro
sudo tar -czvf "${BACKUP_TARGET}/${ARCHIVE_NAME}" \
    --exclude="${JENKINS_HOME}/workspace" \
    --exclude="${JENKINS_HOME}/caches" \
    --exclude="${JENKINS_HOME}/jobs/*/builds" \
    "${JENKINS_HOME}"

Suggerimento: Includere la cronologia delle build

Se conservare la cronologia delle build (jobs/*/builds) è fondamentale, puoi rimuovere il flag --exclude corrispondente. Tuttavia, preparati a dimensioni dell'archivio potenzialmente fino a centinaia di gigabyte.

Passo 3: Verificare e archiviare fuori sede

Una volta creato l'archivio, verifica che possa essere letto prima di fidarti:

tar -tzf "${BACKUP_TARGET}/${ARCHIVE_NAME}" >/dev/null

Quindi trasferiscilo in una posizione di archiviazione esterna, come un bucket S3 o un sistema di backup di rete, in modo che un guasto del disco locale non distrugga sia Jenkins che il suo backup.

Passo 4: Riavviare Jenkins

sudo systemctl start jenkins

Metodo 2: Utilizzare il plugin di backup di Jenkins (Soluzione parziale)

Sebbene esistano plugin come ThinBackup o Backup Plugin, spesso catturano solo i file di configurazione (config.xml) e potrebbero non gestire in modo robusto file di grandi dimensioni o tutti gli elementi di sicurezza necessari. Questi sono generalmente adatti per eseguire il backup delle configurazioni dei job solo e non dovrebbero essere utilizzati per una strategia di ripristino di emergenza completa e sicura.

Ripristinare la tua istanza Jenkins

Il ripristino comporta la copia dei dati di backup nella directory $JENKINS_HOME della macchina di destinazione e la garanzia che i permessi dei file siano corretti prima di avviare il servizio.

Passo 1: Preparare l'ambiente di destinazione

Assicurati che il sistema di destinazione (o il sistema riparato) abbia Jenkins installato, ma mantieni il servizio arrestato.

sudo systemctl stop jenkins

Passo 2: Cancellare i dati Jenkins esistenti (Opzionale ma consigliato)

Se stai ripristinando su una macchina che ospitava in precedenza Jenkins, cancella il contenuto esistente di $JENKINS_HOME per garantire un ambiente pulito.

# Usa cautela con il comando 'rm -rf'!
sudo rm -rf /var/lib/jenkins/*

Passo 3: Estrarre l'archivio di backup

Copia l'archivio compresso (jenkins_backup_latest.tar.gz) sulla macchina di destinazione ed estrailo nella directory $JENKINS_HOME. Il flag -C specifica la directory di destinazione per l'estrazione.

# Supponendo che l'archivio sia in /tmp e JENKINS_HOME sia /var/lib/jenkins
sudo tar -xzvf /tmp/jenkins_backup_latest.tar.gz -C /var/lib/

# Nota: Se il comando tar includeva la directory padre nell'archivio, regola il percorso.
# Il risultato dovrebbe essere che il contenuto dell'archivio sostituisce il contenuto di /var/lib/jenkins

Passo 4: Verificare e correggere i permessi

Questo è il passo più critico dopo il ripristino. Se la proprietà del file non è corretta, Jenkins non si avvierà o non funzionerà in modo sicuro. Devi impostare la proprietà ricorsivamente all'utente e al gruppo con cui viene eseguito il servizio Jenkins (spesso jenkins:jenkins).

JENKINS_HOME="/var/lib/jenkins"
JENKINS_USER="jenkins"
JENKINS_GROUP="jenkins"

sudo chown -R $JENKINS_USER:$JENKINS_GROUP $JENKINS_HOME
sudo find "$JENKINS_HOME" -type d -exec chmod 755 {} \;
sudo find "$JENKINS_HOME" -type f -exec chmod 644 {} \;
sudo chmod -R go-rwx "$JENKINS_HOME/secrets" "$JENKINS_HOME/users" 2>/dev/null || true

Passo 5: Avviare Jenkins e verificare

Avvia il servizio e monitora i log per garantire un avvio riuscito.

sudo systemctl start jenkins

# Monitora i log di avvio
sudo tail -f /var/log/jenkins/jenkins.log

Dopo un avvio riuscito, verifica che tutti i job, gli utenti e i plugin installati siano presenti e funzionino correttamente.

Best practice per i backup automatizzati

Per andare oltre i backup manuali, implementa l'automazione utilizzando strumenti di sistema e gestione della configurazione esterna.

1. Sfruttare i cron job

Pianifica lo script di backup (Passi 1 e 2 del Metodo 1) per essere eseguito quotidianamente o nottetempo utilizzando cron o un pianificatore simile. Assicurati che il cron job venga eseguito come un utente con i permessi appropriati per arrestare e avviare il servizio Jenkins e leggere/scrivere nella directory $JENKINS_HOME.

2. Configurazione come codice (CasC)

Considera l'adozione di Jenkins Configuration as Code (CasC). CasC definisce le impostazioni di Jenkins, i job e i plugin utilizzando file YAML dichiarativi. Archiviando questi file YAML in un repository di controllo del codice sorgente separato (come Git), la tua configurazione diventa portatile e con controllo di versione, semplificando drasticamente il requisito di backup principale.

Conclusione

Considera un backup di Jenkins utile solo dopo aver testato un ripristino. Un buon piano di ripristino preserva config.xml, jobs/, plugins/, users/, credentials.xml e secrets/, quindi verifica che i job possano essere eseguiti su un'istanza pulita.

Avvertenza: Proteggere le credenziali

Quando si ripristina un'istanza, assicurati che la directory secrets/ sia presente e corretta. Se Jenkins non riesce a trovare le chiavi utilizzate per crittografare le credenziali (come chiavi API o password), quelle credenziali diventeranno inutilizzabili e dovranno essere reinserite manualmente.