Questo documento descrive come eseguire l'upgrade di un deployment di Spanner Omni da una versione precedente a una successiva.
Spanner Omni utilizza una macchina a stati di implementazione asincrona e in fasi per garantire upgrade sicuri senza interruzioni del servizio. L'upgrade in fasi ti consente di:
- Applica gli aggiornamenti dello schema del database.
- Verifica la compatibilità binaria durante un riavvio graduale.
- Esegui il rollback alla versione precedente se rilevi errori prima della finalizzazione.
Percorsi di upgrade supportati
Puoi aggiornare una versione LTS solo alla versione LTS successiva. Non puoi saltare una versione quando esegui l'aggiornamento a una versione LTS più recente.
Puoi saltare una versione quando esegui l'upgrade da una versione di assistenza a breve termine (STS) a un'altra versione STS se non esiste una release LTS tra le relative date di rilascio.
Per saperne di più, consulta le policy di assistenza per le versioni.
Esegui l'upgrade del workflow
Il processo di upgrade di Spanner Omni è costituito da più fasi sequenziali:
- Fase di schema: prepara il deployment eseguendo migrazioni interne dello schema del database utilizzando la versione binaria di destinazione. Non è possibile eseguire il rollback delle migrazioni dello schema, ma sono compatibili con le versioni precedenti del programma binario.
- Fase binaria: aggiorna il file binario del server o l'immagine container su tutti i server del deployment utilizzando un riavvio graduale. Se rilevi errori, puoi eseguire il rollback del file binario o dell'immagine container alla versione precedente in qualsiasi momento prima dell'inizio della finalizzazione.
- Fase di attivazione delle funzionalità: attiva le funzionalità compatibili con la versione e inizia dopo l'upgrade del file binario su tutti i server. Questa fase potrebbe non essere applicabile se l'upgrade non include funzionalità compatibili con la versione e può richiedere più cicli se le funzionalità sono interdipendenti. Per le fasi facoltative che supportano il rollback, puoi avviarlo utilizzando l'interfaccia a riga di comando di Spanner Omni.
- Fase di finalizzazione: finalizza l'implementazione, sigillando la versione di destinazione. Una volta iniziata la fase di finalizzazione, i rollback non sono possibili.
Prima di iniziare
Prima di eseguire l'upgrade del deployment di Spanner Omni, assicurati di soddisfare i seguenti prerequisiti:
- Hai un deployment Spanner Omni in esecuzione. Per saperne di più, consulta Crea un deployment su Kubernetes o Crea un deployment su VM.
- Hai scaricato e installato l'interfaccia a riga di comando di Spanner Omni.
- Hai accesso di rete a tutte le porte interne di Spanner Omni (TCP da 15000 a 15027) dalla macchina su cui esegui i comandi dell'interfaccia a riga di comando o accesso di rete all'endpoint di deployment.
- Se il tuo deployment utilizza la crittografia Transport Layer Security (TLS) o mutual TLS (mTLS), assicurati che i certificati validi siano disponibili nella directory di base in
BASE_DIR/tlso montati nel cluster. - Hai identificato la release di destinazione:
- Per i deployment delle VM: scarica il pacchetto della release di destinazione
spanner-omni-server-TARGET_VERSION.tar.gz. - Per i deployment Helm e Kubernetes: identifica l'immagine container di destinazione in Artifact Registry, ad esempio
us-docker.pkg.dev/spanner-omni/images/spanner-omni:TARGET_VERSION.
- Per i deployment delle VM: scarica il pacchetto della release di destinazione
- Gli amministratori dei deployment di Spanner Omni devono pianificare periodi di manutenzione per gli upgrade. La tua organizzazione dovrebbe evitare i deployment durante i periodi di manutenzione per l'upgrade.
Passaggio 1: prepara l'upgrade dello schema
Per avviare l'upgrade, prepara l'implementazione per la versione di destinazione. In questa fase, Spanner Omni esegue le migrazioni interne dello schema del database, mentre i server esistenti continuano a gestire il traffico.
Seleziona la scheda relativa al tuo ambiente di deployment:
VM
Nei deployment delle VM, scarica ed estrai il pacchetto della release di destinazione, quindi utilizza l'interfaccia a riga di comando di Spanner Omni estratta per avviare la preparazione del lancio.
Accedi a un server del tuo deployment che dispone dell'accesso di rete a tutte le porte interne di Spanner Omni (TCP da 15000 a 15027).
Scarica ed estrai il pacchetto della release di destinazione:
tar -xzf spanner-omni-server-TARGET_VERSION.tar.gz -C EXTRACT_DIRSostituisci quanto segue:
TARGET_VERSION: la versione di destinazione di cui eseguire l'upgrade, ad esempio2026.r5.EXTRACT_DIR: la directory in cui estrai il pacchetto di release, ad esempio/tmp/target_spanner/.
Avvia la preparazione dell'implementazione eseguendo il comando
rollouts preparedalla CLI estratta:EXTRACT_DIR/bin/spanner deployment rollouts prepare \ --target-server-binary=EXTRACT_DIR/bin/spanner_server \ --root-server=ROOT_SERVERS \ --base-dir=BASE_DIRSostituisci quanto segue:
EXTRACT_DIR: la directory di estrazione contenente l'interfaccia a riga di comandobin/spannere il file binariobin/spanner_serverdi destinazione.ROOT_SERVERS: un endpoint del server root o un elenco separato da virgole di più server root, ad esempiolocalhost:15000oserver1:15000,server2:15000,server3:15000.BASE_DIR: la directory di base per Spanner Omni, ad esempio/spanner.- Se il tuo deployment utilizza la crittografia TLS o mTLS, aggiungi
--ca-certificate-file=CA_CERT_FILEe--client-certificate-directory=CERT_DIRche puntano a certificati validi.
Helm
Nei deployment Helm, la preparazione dello schema dipende dal fatto che tu esegua un deployment multi-server o single-server:
Deployment su più server (alta affidabilità/produzione): Helm gestisce automaticamente la preparazione dello schema. Quando esegui
helm upgradenel Passaggio 3: aggiorna il file binario o l'immagine container, il grafico Helm attiva il job hook di pre-upgradespanner-prepare-for-upgradeper eseguire le migrazioni dello schema prima di aggiornare qualsiasi StatefulSet. Passa direttamente al Passaggio 2: verifica lo stato di implementazione attivo.Deployment su un singolo server (
deployment.singleServer=true): poiché la modalità su un singolo server associa i servizi interni rigorosamente all'interfaccia di loopback (127.0.0.1), i job di rete non possono raggiungerli. Esegui la migrazione dello schema localmente all'interno del pod in esecuzione utilizzando un container di debug temporaneo con l'immagine container di destinazione:kubectl debug pod/POD_NAME -n NAMESPACE \ --image=us-docker.pkg.dev/spanner-omni/images/spanner-omni:TARGET_VERSION \ --container=upgrade-prepare -i \ -- /google/spanner/bin/spanner_server prepare_for_upgrade --root_server=127.0.0.1Sostituisci quanto segue:
POD_NAME: il nome del pod del server, ad esempiospanner-a-0.NAMESPACE: lo spazio dei nomi Kubernetes del deployment, ad esempiospanner-ns.TARGET_VERSION: la versione di destinazione dell'upgrade, ad esempio2026.r5.
Kubernetes autonomo
Se esegui il deployment di Spanner Omni su Kubernetes senza Helm, esegui un job batch Kubernetes autonomo per eseguire le migrazioni dello schema sul server root attivo utilizzando l'immagine di destinazione.
Crea un file denominato
spanner-prepare-upgrade.yamlcon il seguente manifest del job:apiVersion: batch/v1 kind: Job metadata: namespace: NAMESPACE name: spanner-prepare-for-upgrade spec: # Fail fast on the first error to stop the rollout immediately. backoffLimit: 0 template: metadata: namespace: NAMESPACE spec: restartPolicy: Never containers: - name: spanner-upgrade image: us-docker.pkg.dev/spanner-omni/images/spanner-omni:TARGET_VERSION command: ["/google/spanner/bin/spanner_server"] args: - "prepare_for_upgrade" - "--root_server=ROOT_SERVER_ENDPOINT" volumeMounts: - name: tls-certs mountPath: "/spanner/tls" readOnly: true - name: spanner-data mountPath: /spanner volumes: - name: tls-certs secret: secretName: tls-certs optional: true defaultMode: 256 - name: spanner-data emptyDir: {}Sostituisci quanto segue:
NAMESPACE: lo spazio dei nomi Kubernetes del deployment, ad esempiospanner-ns.TARGET_VERSION: la versione di destinazione dell'upgrade, ad esempio2026.r5.ROOT_SERVER_ENDPOINT: l'endpoint di un pod del server root attivo, ad esempiospanner-a-0.pod.spanner-ns.
Applica il manifest per eseguire il job di preparazione:
kubectl apply -f spanner-prepare-upgrade.yaml
Passaggio 2: verifica lo stato dell'implementazione attiva
Al termine della fase di preparazione, verifica che l'implementazione sia stata creata e controlla lo stato della fase.
Elenca le implementazioni attive per recuperare l'ID implementazione:
spanner deployment rollouts list \ --deployment-endpoint=DEPLOYMENT_ENDPOINTSostituisci
DEPLOYMENT_ENDPOINTcon l'endpoint di un server nel tuo deployment, ad esempiolocalhost:15000ospanner-a-0.pod.spanner-ns:15000.L'output è simile al seguente:
NAME STATE TARGET_VERSION START_TIME END_TIME rollouts/1788942172101727 IN_PROGRESS 2026.r3-beta 2026-09-09T08:22:52.101727Z -Controlla lo stato dettagliato della fase di implementazione:
spanner deployment rollouts describe ROLLOUT_ID \ --deployment-endpoint=DEPLOYMENT_ENDPOINTSostituisci quanto segue:
ROLLOUT_ID: l'ID numerico dell'implementazione, ad esempio1788942172101727.DEPLOYMENT_ENDPOINT: l'endpoint di un server nel tuo deployment.
L'output è simile al seguente:
name: rollouts/1788942172101727 phases: - name: rollouts/1788942172101727/phases/schema startTime: "2026-09-09T08:22:52.101727Z" state: SUCCEEDED - name: rollouts/1788942172101727/phases/binary startTime: "2026-09-09T08:23:29.585375Z" state: IN_PROGRESS - name: rollouts/1788942172101727/phases/finalize state: PENDING sourceVersion: 2026.r2-beta.3 startTime: "2026-09-09T08:22:52.101727Z" state: IN_PROGRESS targetVersion: 2026.r3-betaPrima di procedere, verifica i seguenti stati delle fasi:
schema: mostraSUCCEEDED, a indicare che le migrazioni dello schema del database interno sono state completate.binary: mostraIN_PROGRESS, che indica che il motore di implementazione è pronto per gli aggiornamenti binari.finalize: mostraPENDING, in attesa del completamento della fase binaria.
Passaggio 3: aggiorna l'immagine binaria o container
Una volta completata la fase dello schema, aggiorna il file binario del server in esecuzione o l'immagine container in tutti i nodi del deployment alla versione di destinazione.
Seleziona la scheda relativa al tuo ambiente di deployment:
VM
Nei deployment di VM, aggiorna il programma binario spanner_server in tutte le VM utilizzando
un riavvio graduale:
- Aggiorna un dominio o una zona in errore alla volta: nei deployment multizona, aggiorna i server in una zona e verifica la stabilità prima di aggiornare la zona successiva. In questo modo, il gruppo di consenso Paxos mantiene il quorum.
- Riavvia progressivamente: riavvia non più del 5% dei server contemporaneamente per mantenere la disponibilità delle query continue.
- Verifica l'integrità dei server: assicurati che tutti i server riavviati siano integri e che siano stati aggiunti nuovamente al cluster prima di aggiornare il dominio in errore successivo.
Helm
Nei deployment Helm, esegui helm upgrade conservando i valori di configurazione esistenti passando --reuse-values o fornendo un file di valori:
Implementazioni multi-server (produzione/HA):
helm upgrade spanner-omni oci://us-docker.pkg.dev/spanner-omni/charts/spanner-omni \ --version CHART_VERSION \ -n NAMESPACE \ --reuse-values \ --set image.tag=TARGET_VERSION \ --timeout 30mHelm esegue automaticamente la Fase 1 utilizzando l'hook pre-upgrade, quindi avvia un aggiornamento in sequenza, zona per zona, degli StatefulSet (
rollout.staggered: true).Deployment su un singolo server (
deployment.singleServer=true):Passa esplicitamente
--set skipPrepareUpgrade=truein modo che Helm ignori il job hook pre-upgrade, perché hai già completato la Fase 1 localmente:helm upgrade spanner-omni oci://us-docker.pkg.dev/spanner-omni/charts/spanner-omni \ --version CHART_VERSION \ -n NAMESPACE \ --reuse-values \ --set skipPrepareUpgrade=true \ --set image.tag=TARGET_VERSION \ --timeout 30m
Sostituisci quanto segue:
CHART_VERSION: la versione del grafico Helm di destinazione, ad esempio1.1.0.NAMESPACE: lo spazio dei nomi Kubernetes del deployment, ad esempiospanner-ns.TARGET_VERSION: il tag dell'immagine container di destinazione, ad esempio2026.r5.
Kubernetes autonomo
Nei deployment Kubernetes personalizzati senza Helm, aggiorna l'immagine container nelle specifiche del deployment StatefulSet o Deployment in
TARGET_VERSION.
Esegui un aggiornamento in sequenza tra i domini in errore, aggiornando una zona alla volta e riavviando non più del 5% dei pod contemporaneamente per preservare il quorum.
Passaggio 4: verifica l'avanzamento della fase binaria
Dopo aver aggiornato tutti i server o i pod alla versione di destinazione, verifica che la fase binaria venga completata correttamente.
Controlla lo stato della fase di implementazione:
spanner deployment rollouts describe ROLLOUT_ID \
--deployment-endpoint=DEPLOYMENT_ENDPOINT
Sostituisci quanto segue:
ROLLOUT_ID: l'ID numerico dell'implementazione, ad esempio1788942172101727.DEPLOYMENT_ENDPOINT: l'endpoint di un server nel tuo deployment.
L'output è simile al seguente:
name: rollouts/1788942172101727
phases:
- name: rollouts/1788942172101727/phases/schema
startTime: "2026-09-09T08:22:52.101727Z"
state: SUCCEEDED
- name: rollouts/1788942172101727/phases/binary
startTime: "2026-09-09T08:23:29.585375Z"
state: SUCCEEDED
- name: rollouts/1788942172101727/phases/finalize
state: PENDING
sourceVersion: 2026.r2-beta.3
startTime: "2026-09-09T08:22:52.101727Z"
state: IN_PROGRESS
targetVersion: 2026.r3-beta
Verifica che lo stato della fase binary cambi in SUCCEEDED. Lo stato complessivo dell'implementazione rimane IN_PROGRESS fino al completamento di tutte le fasi rimanenti. Dopo la transizione di phases/binary a SUCCEEDED, il deployment è pronto per procedere alle fasi rimanenti.
Passaggio 5: pianifica ed esegui le fasi rimanenti
Quando la fase binaria ha esito positivo e verifichi che il deployment è stabile, pianifica le fasi rimanenti per l'implementazione fino alla fase finalize.
La fase finalize (l'ultima fase di un'implementazione) sigilla la nuova versione nel deployment. Puoi eseguire questo comando da qualsiasi macchina che abbia accesso di rete al servizio Spanner Omni specificando --deployment-endpoint.
Per ogni fase rimanente nello stato PENDING (ad esempio enable_features se presente, seguita da finalize), completa i seguenti passaggi:
Pianifica la fase:
spanner deployment rollouts phases schedule PHASE_NAME \ --rollout=ROLLOUT_ID \ --deployment-endpoint=DEPLOYMENT_ENDPOINTSostituisci quanto segue:
PHASE_NAME: il nome della fase da pianificare, ad esempiofinalizeoenable_features.ROLLOUT_ID: l'ID numerico dell'implementazione, ad esempio1788942172101727.DEPLOYMENT_ENDPOINT: l'endpoint di un server nel tuo deployment.
L'output indica che la fase pianificata è
IN_PROGRESS:name: rollouts/1788942172101727 phases: - name: rollouts/1788942172101727/phases/schema startTime: "2026-09-09T08:22:52.101727Z" state: SUCCEEDED - name: rollouts/1788942172101727/phases/binary startTime: "2026-09-09T08:23:29.585375Z" state: SUCCEEDED - name: rollouts/1788942172101727/phases/finalize state: IN_PROGRESS sourceVersion: 2026.r2-beta.3 startTime: "2026-09-09T08:22:52.101727Z" state: IN_PROGRESS targetVersion: 2026.r3-betaAttendi che la fase venga completata e verifica lo stato:
spanner deployment rollouts describe ROLLOUT_ID \ --deployment-endpoint=DEPLOYMENT_ENDPOINTRipeti questi passaggi per ogni fase rimanente fino a completare tutte le fasi fino alla
finalizeinclusa.Al termine della fase finale (
finalize), tutte le fasi e lo stato di implementazione complessivo passano aSUCCEEDED:endTime: "2026-09-09T08:45:43.949702Z" name: rollouts/1788942172101727 phases: - name: rollouts/1788942172101727/phases/schema startTime: "2026-09-09T08:22:52.101727Z" state: SUCCEEDED - name: rollouts/1788942172101727/phases/binary startTime: "2026-09-09T08:23:29.585375Z" state: SUCCEEDED - name: rollouts/1788942172101727/phases/finalize startTime: "2026-09-09T08:45:43.898111Z" state: SUCCEEDED sourceVersion: 2026.r2-beta.3 startTime: "2026-09-09T08:22:52.101727Z" state: SUCCEEDED targetVersion: 2026.r3-betaConferma lo stato di completamento nell'elenco delle implementazioni:
spanner deployment rollouts list \ --deployment-endpoint=DEPLOYMENT_ENDPOINTL'output conferma che l'implementazione è stata completata:
NAME STATE TARGET_VERSION START_TIME END_TIME rollouts/1788942172101727 SUCCEEDED 2026.r3-beta 2026-09-09T08:22:52.101727Z 2026-09-09T08:45:43.949702Z
Esegui il rollback di un upgrade
Se riscontri problemi durante un upgrade, la possibilità di eseguire il rollback dell'upgrade dipende dalla fase di implementazione attuale:
- Fase dello schema: non è possibile eseguire il rollback. Le migrazioni dello schema del database interno applicate durante la preparazione sono di tipo forward-only e non possono essere annullate. Tuttavia, le migrazioni dello schema sono compatibili con le versioni precedenti, consentendo ai file binari del server precedenti di continuare a funzionare normalmente.
- Fase binaria: è possibile eseguire il rollback alla versione precedente in qualsiasi momento prima dell'inizio della finalizzazione. Per saperne di più, consulta Esegui il rollback del file binario o dell'immagine container.
- Fasi di implementazione facoltative: per le fasi facoltative che supportano il rollback automatico (come l'attivazione delle funzionalità), avvia il rollback utilizzando l'interfaccia a riga di comando di Spanner Omni.
- Fase di finalizzazione: non è possibile eseguire il rollback. Una volta avviata la finalizzazione, la versione di destinazione viene bloccata in modo permanente nel deployment e i rollback non sono possibili.
Esegui il rollback del file binario o dell'immagine container
Per eseguire il rollback della fase binaria prima dell'inizio della finalizzazione, esegui un riavvio graduale su tutti i server o i pod per ripristinare la versione precedente (origine).
VM
Nei deployment di VM, esegui il rollback del programma binario spanner_server su tutte le VM:
- Esegui il deployment della versione binaria
spanner_serverprecedente sui tuoi host. - Riavvia i server progressivamente nei domini in errore, aggiornando una zona alla volta e riavviando non più del 5% dei server contemporaneamente per preservare il quorum Paxos.
- Verifica che tutti i server riavviati siano integri e che siano stati aggiunti nuovamente al cluster prima di procedere al dominio in errore successivo.
Helm
Nei deployment Helm, aggiorna il tag dell'immagine container alla versione precedente:
helm upgrade spanner-omni oci://us-docker.pkg.dev/spanner-omni/charts/spanner-omni \
--version CHART_VERSION \
-n NAMESPACE \
--reuse-values \
--set image.tag=SOURCE_VERSION \
--timeout 30m
Sostituisci quanto segue:
CHART_VERSION: la versione del grafico Helm, ad esempio1.1.0.NAMESPACE: lo spazio dei nomi Kubernetes del deployment, ad esempiospanner-ns.SOURCE_VERSION: il tag dell'immagine container precedente a cui eseguire il ripristino, ad esempio2026.r2-beta.3.
Kubernetes autonomo
Nei deployment Kubernetes personalizzati senza Helm, aggiorna l'immagine container
nelle specifiche di StatefulSet o Deployment riportandola a
SOURCE_VERSION.
Esegui un aggiornamento in sequenza tra i domini in errore, aggiornando una zona alla volta e riavviando non più del 5% dei pod contemporaneamente per preservare il quorum.
Esegui il rollback delle fasi di implementazione facoltative
Per le fasi di implementazione facoltative che supportano il rollback (ad esempio le fasi di attivazione delle funzionalità), avvia il rollback eseguendo il comando rollouts rollback:
spanner deployment rollouts rollback ROLLOUT_ID \
--deployment-endpoint=DEPLOYMENT_ENDPOINT
Sostituisci quanto segue:
ROLLOUT_ID: l'ID numerico dell'implementazione.DEPLOYMENT_ENDPOINT: l'endpoint di un server nel tuo deployment.
Passaggi successivi
- Scopri come eseguire la manutenzione di un deployment.
- Scopri come scalare un deployment Kubernetes o scalare un deployment di VM.
- Scopri di più sulla panoramica di Monitoring.