Aggiornamento, backup e rollback

Aggiornamento

Gli aggiornamenti arrivano come un nuovo archivio di distribuzione. Ci sono due modi per applicarne uno.

Il nodo recupera da solo

sudo scripts/tc-operator/tc-operator update --config operator.yaml

Il nodo recupera il manifest di release, lo confronta con la versione installata e, se ce n’è una più recente, la scarica, ne verifica il checksum, la estrae e riesegue l’installer del nuovo archivio. Non ha bisogno di un terminale, quindi puoi schedularlo.

La connessione è solo in uscita — il nodo recupera, il centro non si connette mai in entrata — quindi funziona da dietro un firewall. La firma del manifest viene verificata prima che qualsiasi campo al suo interno sia considerato attendibile, perché il percorso di aggiornamento estrae un archivio sopra la radice di installazione attiva e riesegue il suo installer come root. --force reinstalla anche quando il nodo è già aggiornato.

Applichi tu un archivio a mano

Ti vengono dati due file: il tarball e un file di checksum a corredo.

# 1. Verifica l'archivio prima di toccare qualsiasi cosa
sha256sum -c trusted-codes-operator-<versione>-<sha>.tar.gz.sha256

# 2. Estrai sopra l'albero esistente, sul posto. Non cancellare prima la
#    cartella — i container in esecuzione montano percorsi al suo interno.
sudo tar -xzf trusted-codes-operator-<versione>-<sha>.tar.gz -C /opt/trusted-codes

# 3. Riesegui l'installazione. --archive conserva questa build così puoi tornare a essa.
cd /opt/trusted-codes
sudo scripts/tc-operator/tc-operator install --config operator.yaml \
  --archive ~/trusted-codes-operator-<versione>-<sha>.tar.gz

Che cosa fa la riesecuzione

Preservati intatti: il tuo operator.yaml, tutto sotto /etc/trusted-codes — segreti, identità mTLS, backup — e tutti i dati nel database. I segreti vengono riusati a ogni riesecuzione, mai ruotati.

Applicati: solo le nuove migrazioni, poiché quelle già applicate vengono saltate; i dati di riferimento riapplicati; il runtime delle function riavviato così serve il nuovo codice; le superfici ricompilate e riposizionate; le informazioni pubblicate del nodo rifirmate; il README sulla macchina rigenerato.

Registrati: la build, visibile in status e in testa al README sulla macchina. Con --archive, il tarball viene conservato sotto /etc/trusted-codes/archives — gli ultimi cinque — così un rollback non ha bisogno di un nuovo download.

Rifiutato: installare un archivio più vecchio sopra un nodo più recente si interrompe, perché riporterebbe indietro il codice. --allow-downgrade procede se è deliberato, e rollback lo imposta per te.

Non necessario: finalize-tls. Il proxy serve i file riposizionati dal disco immediatamente. Eseguilo di nuovo solo se hai cambiato dominio.

Controlla tc-operator status dopo ogni aggiornamento. Stampa la build ora in esecuzione.

Tornare indietro

scripts/tc-operator/tc-operator rollback                    # elenca le build conservate
sudo scripts/tc-operator/tc-operator rollback --to <versione|sha>

Riestrae quella build e riesegue l’installazione, e ti chiede di digitare l’obiettivo per confermare.

Rollback riporta indietro solo il codice — edge function, superfici, script dell’installer. Non riporta indietro lo schema del database. Le migrazioni sono solo in avanti, quindi il codice vecchio gira contro lo schema attuale. Va bene per una release che ha solo aggiunto cose. Non va bene per una che ha eliminato o rinominato qualcosa che il codice vecchio legge.

Un vero rollback completo è un ripristino da un dump del database, non una riestrazione del codice.

Backup

L’installer fa un dump del database automaticamente in un solo caso: quando disinstalli. Un nodo attivo ha bisogno di una tua schedulazione.

Ti servono entrambe le metà

1. Il database — account, connessioni, dati.
2. /etc/trusted-codes/secrets.env — l’identità e le chiavi di cifratura del nodo: la chiave di firma della federazione, il segreto JWT, la chiave di cifratura per i dati personali, la password del database.

I dati ripristinati sono illeggibili senza la chiave di cifratura originale, e un nodo ricostruito senza questo file ottiene un’identità di federazione del tutto nuova. Fanne un backup insieme a ogni dump e tienilo offline. Un dump da solo non è un backup.

Farne uno

source /etc/trusted-codes/secrets.env
docker exec -e PGPASSWORD="$POSTGRES_PASSWORD" tcnode-db \
  pg_dump -U supabase_admin -d postgres \
  | gzip > tc-backup-$(date -u +%Y%m%dT%H%M%SZ).sql.gz

Il container è <progetto>-db; su un’installazione predefinita è tcnode-db, e docker ps lo mostra. È lo stesso dump che uninstall fa. Copia il risultato e un secrets.env aggiornato fuori dalla macchina, e schedulalo per qualsiasi installazione reale.

Ripristinare su una macchina nuova

1. Provisiona la macchina e portaci sopra l’archivio.

2. Ripristina prima il tuo secrets.env salvato, in /etc/trusted-codes/secrets.env, modalità 0600. Questo preserva l’identità del nodo e la chiave che decifra i dati. Senza l’originale, le righe ripristinate sono illeggibili.

3. Ripristina il tuo operator.yaml ed esegui tc-operator install. Lo stack si avvia e riproduce lo schema. Non ci sono ancora dati utente.

4. Carica il dump:

   source /etc/trusted-codes/secrets.env
   gunzip -c tc-backup-<ts>.sql.gz \
     | docker exec -i -e PGPASSWORD="$POSTGRES_PASSWORD" tcnode-db \
         psql -U supabase_admin -d postgres

Il dump è un’istantanea logica completa. Caricarlo sopra lo schema appena migrato stampa avvisi innocui di “already exists” per gli oggetti che anche le migrazioni hanno creato; le righe di dati sono ciò che ripristina i tuoi utenti. Verifica con tc-operator status e un accesso di prova.

Fai una prova su una macchina usa e getta prima di doverlo fare per davvero. Il passaggio che le persone sbagliano è il secondo, e lo scoprono nel momento peggiore possibile.