Un backup GitLab che non si può ripristinare è solo un file grande

La maggior parte delle istanze GitLab self-hosted ha un job di backup notturno, e la maggior parte delle persone che lo hanno configurato non ha mai fatto un restore da esso. È un problema, perché l'archivio che GitLab produce è deliberatamente incompleto. Ripristinatelo su un server nuovo senza i file che esclude, e i vostri repository tornano mentre le variabili CI, le impostazioni della two-factor e le registrazioni dei runner diventano dati illeggibili. Ecco cosa contiene un backup GitLab completo, come spostarlo senza indebolire la vostra sicurezza, e come dimostrare che funziona.

Cosa include il task di backup, e cosa esclude

Su un'installazione a pacchetto (Omnibus), il task di backup è:

sudo gitlab-backup create STRATEGY=copy

Scrive un singolo archivio tar nella directory di backup, di solito /var/opt/gitlab/backups. Quell'archivio contiene il database, i repository Git, gli upload, gli oggetti LFS, gli artifact dei job CI, le pages, i package e, se abilitato, il container registry. STRATEGY=copy copia i dati prima di archiviarli, il che evita errori quando i file cambiano durante un backup lungo su un'istanza trafficata.

Cosa non contiene, di proposito:

• /etc/gitlab/gitlab-secrets.json, le chiavi usate per cifrare le colonne sensibili nel database.
• /etc/gitlab/gitlab.rb, la vostra configurazione.
• Certificati e chiavi TLS sotto /etc/gitlab/ssl, se li tenete lì.
• Le host key SSH in /etc/ssh, che i client dei vostri sviluppatori hanno già registrato.

GitLab li esclude perché un singolo archivio rubato non contenga sia i dati cifrati sia la chiave che li decifra. È un ragionamento solido, e mette su di voi il compito di farne il backup separatamente.

Perché il file dei secret conta così tanto

Variabili CI/CD, token di registrazione dei runner, seed della two-factor authentication, password delle integrazioni e diversi altri valori sono cifrati nel database con chiavi provenienti da gitlab-secrets.json. Ripristinate il database senza il file dei secret corrispondente e GitLab parte, i repository ci sono, e poi le pipeline falliscono, gli utenti con la two-factor non riescono ad accedere e i runner vanno registrati di nuovo.

Fate il backup della directory di configurazione come artifact a sé:

sudo gitlab-ctl backup-etc --backup-path /var/opt/gitlab/config-backups

Questo produce un tar di /etc/gitlab, compreso il file dei secret. Tenetelo in un posto diverso dall'archivio dei dati, con accesso più restrittivo, e tenete insieme le coppie corrispondenti nella vostra policy di retention. Un archivio dati di lunedì e un file dei secret di giovedì potrebbero non concordare tra loro se nel frattempo qualcosa è stato ruotato.

Per le installazioni in container i comandi sono gli stessi, eseguiti dentro il container, e /etc/gitlab è il volume che vi avete mappato. Assicuratevi che quel volume faccia parte di ciò di cui fate il backup; è facile fare il backup del solo volume dati.

Tirate il backup, non spingetelo

Lo schema abituale è un cron job sul server GitLab che copia l'archivio verso un host di backup. Questo significa che il server GitLab detiene credenziali che possono scrivere sui vostri backup. Se GitLab è compromesso, lo è anche la via per raggiungere e cancellare i backup.

Girate la direzione. L'host di backup si connette a GitLab e preleva i file. GitLab non detiene credenziali per l'host di backup e non ha alcun percorso di rete verso di lui. Sul lato GitLab, limitate ciò che la chiave dell'host di backup può fare con un forced command in authorized_keys:

command="/usr/local/bin/backup-send",no-port-forwarding,no-X11-forwarding,no-agent-forwarding,no-pty ssh-ed25519 AAAA... backup-puller

dove backup-send è un piccolo script che non fa altro che mandare in streaming l'archivio dati più recente e il suo archivio di configurazione corrispondente. Sull'host di backup, il job preleva entrambi, ne verifica dimensioni e checksum, e avvisa se uno dei due manca o è più vecchio del previsto.

Poi applicate la direzione sul firewall: l'host di backup può aprire connessioni verso GitLab, nulla sulla rete di GitLab può aprire connessioni verso l'host di backup.

Regole di restore da conoscere prima di averne bisogno

Un backup GitLab si ripristina solo sulla stessa versione ed edizione di GitLab che lo ha creato. Scrivete la versione nel nome dell'archivio o in un file a lato al momento del backup:

sudo gitlab-rake gitlab:env:info > gitlab-env-$(date +%F).txt

Se perdete il server e l'unico installer che riuscite a trovare è più nuovo, dovrete prima installare la vecchia versione, ripristinare, e poi aggiornare lungo il percorso supportato. Saperlo in anticipo trasforma una lunga notte in una procedura pianificata.

Il restore vero e proprio, su un'installazione pulita della versione corrispondente:

sudo gitlab-ctl stop puma
sudo gitlab-ctl stop sidekiq
# put gitlab-secrets.json and gitlab.rb back into /etc/gitlab first
sudo gitlab-ctl reconfigure
sudo gitlab-backup restore BACKUP=<archive-id>
sudo gitlab-ctl restart
sudo gitlab-rake gitlab:check SANITIZE=true
sudo gitlab-rake gitlab:doctor:secrets

L'ultimo comando è quello che conta. gitlab:doctor:secrets percorre le colonne cifrate e segnala quelle che non riesce a decifrare. Se segnala fallimenti, il vostro file dei secret e il vostro archivio dati non vanno insieme.

Dimostratelo a calendario

Un restore che non avete testato è una speranza. Rendetelo routine:

• Costruite una VM usa e getta su una rete isolata senza rotta verso la produzione.
• Installate la versione di GitLab registrata con il backup.
• Ripristinate la coppia configurazione e dati più recente.
• Eseguite gitlab:check e gitlab:doctor:secrets.
• Clonate un repository noto, confrontate l'hash dell'ultimo commit con la produzione, e aprite la pagina delle variabili CI di un progetto.
• Registrate il risultato e il tempo impiegato, poi distruggete la VM.

Cronometratelo, anche. La durata del restore è il vostro vero tempo di ripristino, ed è di solito più lunga di quanto si immagini su un'istanza grande.

Una seconda copia indipendente del codice

Il backup completo protegge l'intera applicazione. Per i repository in sé, un semplice mirror vi dà una seconda copia che non dipende affatto dagli strumenti di GitLab:

git clone --mirror git@gitlab.example.com:group/project.git
git -C project.git remote update --prune

Eseguitelo dal lato backup per i repository che non potete permettervi di perdere. Non ripristinerà issue o merge request, ma significa che la storia del vostro sorgente sopravvive anche a un archivio di backup che non riuscite a leggere.

La versione breve

• gitlab-backup create è metà di un backup. gitlab-ctl backup-etc è l'altra metà.
• Tenete secret e dati in coppie corrispondenti, conservate separate, con accesso più restrittivo sui secret.
• Il lato backup tira; GitLab non ha alcun percorso verso i propri backup.
• Registrate la versione di GitLab con ogni archivio.
• Ripristinate a calendario, ed eseguite gitlab:doctor:secrets ogni volta.

È così che proteggiamo le istanze GitLab che gestiamo per i clienti nei nostri datacenter. Se volete far verificare il vostro percorso di restore, siamo lieti di aiutarvi.

Parla con un ingegnere

related line: Correlati: Managed source control su GitLab · Managed Nextcloud per documenti d'ufficio

footer line: Pubblicato il 22 ottobre 2026. Tutte le note dal campo