Esegui l'upgrade di un deployment Spanner Omni

Questo documento descrive come eseguire l'upgrade di un deployment di Spanner Omni da una versione precedente a una versione successiva.

Spanner Omni utilizza una macchina a stati di implementazione asincrona e graduale 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 in sequenza.
• Esegui il rollback alla versione precedente se rilevi errori prima della finalizzazione.

Workflow di upgrade

Il processo di upgrade di Spanner Omni è costituito da più fasi sequenziali:

1. Fase di schema: prepara il deployment eseguendo le migrazioni dello schema del database interno utilizzando la versione binaria di destinazione. Le migrazioni dello schema non possono essere eseguite il rollback, ma sono compatibili con le versioni precedenti del binario.
2. Fase binaria: aggiorna il 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.
3. Fase di attivazione delle funzionalità: attiva le funzionalità compatibili con la versione e inizia dopo l'upgrade del 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 avviare un rollback utilizzando Spanner Omni CLI.
4. Fase di finalizzazione: finalizza l'implementazione, sigillando la versione target. 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 di Spanner Omni in esecuzione. Per saperne di più, consulta Creare un deployment su Kubernetes o Creare un deployment su VM.
• Hai scaricato e installato Spanner Omni CLI.
• Hai accesso alla rete a tutte le porte interne di Spanner Omni (TCP da 15000 a 15027) dalla macchina in cui esegui i comandi della CLI oppure accesso alla rete all'endpoint di deployment.
• Se il deployment utilizza la crittografia Transport Layer Security (TLS) o mutual TLS (mTLS), assicurati che siano disponibili certificati validi nella directory di base in BASE_DIR/tls o montati nel cluster.
• Hai identificato la release di destinazione:
  • Per i deployment di VM: scarica il pacchetto della release di destinazione spanner-omni-server-TARGET_VERSION.tar.gz.
  • Per i deployment di 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.

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 dello schema del database interno 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 di rilascio di destinazione, quindi utilizza Spanner Omni CLI estratto per avviare la preparazione del rollout.

Importante: il pacchetto di rilascio di Spanner Omni di destinazione include sia la CLI spanner sia il binario spanner_server (in genere in bin/). Scarica ed estrai il pacchetto di rilascio di destinazione sull'host prima di eseguire la fase di preparazione.

1. Accedi a un server nella tua implementazione che abbia accesso alla rete a tutte le porte interne di Spanner Omni (TCP 15000-15027).

2. Scarica ed estrai il pacchetto della release di destinazione:

   tar -xzf spanner-omni-server-TARGET_VERSION.tar.gz -C EXTRACT_DIR
   

   Sostituisci quanto segue:

   • TARGET_VERSION: la versione di destinazione a cui eseguire l'upgrade, ad esempio 2026.r4-lts.
   • EXTRACT_DIR: la directory in cui estrai il pacchetto di rilascio, ad esempio /tmp/target_spanner/.

3. Avvia la preparazione dell'implementazione eseguendo il comando rollouts prepare dalla CLI estratta:

   EXTRACT_DIR/bin/spanner deployment rollouts prepare \
     --target-server-binary=EXTRACT_DIR/bin/spanner_server \
     --root-server=ROOT_SERVERS \
     --base-dir=BASE_DIR
   

   Sostituisci quanto segue:

   • EXTRACT_DIR: la directory di estrazione contenente l'interfaccia a riga di comando bin/spanner di destinazione e il binario bin/spanner_server.
   • ROOT_SERVERS: Un endpoint del server radice o un elenco separato da virgole di più server radice, ad esempio localhost:15000 o server1:15000,server2:15000,server3:15000.
   • BASE_DIR: La directory di base per Spanner Omni, ad esempio /spanner.
   • Se il deployment utilizza la crittografia TLS o mTLS, aggiungi --ca-certificate-file=CA_CERT_FILE e --client-certificate-directory=CERT_DIR che 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 multi-server (alta affidabilità / produzione): Helm gestisce automaticamente la preparazione dello schema. Quando esegui helm upgrade nel passaggio 3: aggiorna il binario o l'immagine container, il grafico Helm attiva il job hook pre-upgrade spanner-prepare-for-upgrade per eseguire le migrazioni dello schema prima di aggiornare qualsiasi StatefulSet. Passa direttamente al passaggio 2: verifica lo stato di implementazione attivo.

• Implementazioni su un singolo server (deployment.singleServer=true): Poiché la modalità a 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.1
  

  Sostituisci quanto segue:

  • POD_NAME: il nome del pod del server, ad esempio spanner-a-0.
  • NAMESPACE: lo spazio dei nomi Kubernetes del deployment, ad esempio spanner-ns.
  • TARGET_VERSION: la versione di destinazione a cui eseguire l'upgrade, ad esempio 2026.r4-lts.

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.

1. Crea un file denominato spanner-prepare-upgrade.yaml con 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 esempio spanner-ns.
   • TARGET_VERSION: la versione di destinazione a cui eseguire l'upgrade, ad esempio 2026.r4-lts.
   • ROOT_SERVER_ENDPOINT: l'endpoint di un pod di server radice attivo, ad esempio spanner-a-0.pod.spanner-ns.

2. Applica il manifest per eseguire il job di preparazione:

   kubectl apply -f spanner-prepare-upgrade.yaml
   

Passaggio 2: verifica lo stato di implementazione attivo

Al termine del passaggio di preparazione, verifica che l'implementazione sia stata creata e controlla lo stato della fase.

Nota: nelle implementazioni Helm multi-server, Helm crea il rollout durante helm upgrade nel passaggio 3. Puoi verificare lo stato dell'implementazione durante o dopo l'esecuzione di questo passaggio.

1. Elenca le implementazioni attive per recuperare l'ID implementazione:

   spanner deployment rollouts list \
     --deployment-endpoint=DEPLOYMENT_ENDPOINT
   

   Sostituisci DEPLOYMENT_ENDPOINT con l'endpoint di un server nel tuo deployment, ad esempio localhost:15000 o spanner-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    -
   

2. Ispeziona lo stato dettagliato 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 esempio 1788942172101727.
   • 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-beta
   

   Prima di procedere, verifica i seguenti stati delle fasi:

   • schema: mostra SUCCEEDED, a indicare che le migrazioni dello schema del database interno sono state completate.
   • binary: mostra IN_PROGRESS, a indicare che il motore di implementazione è pronto per gli aggiornamenti binari.
   • finalize: mostra PENDING, in attesa del completamento della fase binaria.

Passaggio 3: aggiorna l'immagine binaria o del contenitore

Una volta completata la fase dello schema, aggiorna il binario o l'immagine del container del server in esecuzione su tutti i nodi del deployment alla versione di destinazione.

Suggerimento: se noti errori o un peggioramento delle prestazioni, puoi eseguire il rollback del file binario o dell'immagine container alla versione precedente in qualsiasi momento prima della finalizzazione. Per ulteriori informazioni, vedi Rollback di un upgrade.

Seleziona la scheda relativa al tuo ambiente di deployment:

VM

Nei deployment di VM, aggiorna il binario spanner_server su tutte le VM utilizzando un riavvio in sequenza:

• Aggiorna un dominio in errore o una zona 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 in modo progressivo: riavvia non più del 5% dei server contemporaneamente per mantenere la disponibilità della query continua.
• Verifica lo stato del server: assicurati che tutti i server riavviati siano integri e che si siano uniti di nuovo al cluster prima di aggiornare il successivo dominio in errore.

Helm

Nei deployment Helm, esegui helm upgrade mantenendo i valori di configurazione esistenti passando --reuse-values o fornendo un file di valori:

• Deployment multi-server (produzione / alta disponibilità):

  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 30m
  

  Helm esegue automaticamente la fase 1 utilizzando l'hook pre-upgrade, quindi avvia un aggiornamento in sequenza, zona per zona, degli StatefulSet (rollout.staggered: true).

• Implementazioni su un singolo server (deployment.singleServer=true):

  Passa esplicitamente --set skipPrepareUpgrade=true in modo che Helm ignori il job hook pre-upgrade, perché hai già completato la fase 1 in locale:

  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 esempio 1.0.0.
• NAMESPACE: lo spazio dei nomi Kubernetes del deployment, ad esempio spanner-ns.
• TARGET_VERSION: il tag dell'immagine container di destinazione, ad esempio 2026.r4-lts.

Kubernetes autonomo

Nei deployment Kubernetes personalizzati senza Helm, aggiorna l'immagine container nelle specifiche di StatefulSet o Deployment a TARGET_VERSION.

Esegui un aggiornamento in sequenza nei domini di errore, aggiornando una zona alla volta e riavviando non più del 5% dei pod contemporaneamente per mantenere 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.

Nota: dopo l'aggiornamento di tutti i server nel deployment, Spanner Omni monitora lo stato del server in un periodo di osservazione di fino a 15 minuti prima di contrassegnare la fase binary come SUCCEEDED.

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 esempio 1788942172101727.
• 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 di implementazione generale rimane IN_PROGRESS finché non vengono completate tutte le fasi rimanenti. Dopo che phases/binary passa 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 rollout) sigilla la nuova versione nel deployment. Puoi eseguire questo comando da qualsiasi macchina che abbia accesso alla rete al servizio Spanner Omni specificando --deployment-endpoint.

Attenzione: il rollback non è possibile dopo l'inizio della finalizzazione. Finalizza l'implementazione solo dopo aver osservato il deployment per un periodo di tempo sufficiente e aver verificato che sia integro e stabile in condizioni di carichi di lavoro tipici. Per ulteriori informazioni, vedi Rollback di un upgrade.

Per ogni fase rimanente nello stato PENDING (ad esempio enable_features se presente, seguito da finalize), completa i seguenti passaggi:

1. Pianifica la fase:

   spanner deployment rollouts phases schedule PHASE_NAME \
     --rollout=ROLLOUT_ID \
     --deployment-endpoint=DEPLOYMENT_ENDPOINT
   

   Sostituisci quanto segue:

   • PHASE_NAME: il nome della fase da pianificare, ad esempio finalize o enable_features.
   • ROLLOUT_ID: l'ID numerico dell'implementazione, ad esempio 1788942172101727.
   • 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-beta
   

2. Attendi che la fase vada a buon fine e verifica il suo stato:

   spanner deployment rollouts describe ROLLOUT_ID \
     --deployment-endpoint=DEPLOYMENT_ENDPOINT
   

   Ripeti questi passaggi per ogni fase rimanente finché non avrai completato tutte le fasi fino a finalize incluso.

   Al termine della fase finale (finalize), tutte le fasi e lo stato di implementazione complessivo passano a SUCCEEDED:

   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-beta
   

3. Conferma lo stato Completato nell'elenco delle implementazioni:

   spanner deployment rollouts list \
     --deployment-endpoint=DEPLOYMENT_ENDPOINT
   

   L'output conferma che l'implementazione è 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 dipende dalla fase di implementazione attuale:

• Fase dello schema: non può essere eseguito il rollback. Le migrazioni dello schema del database interno applicate durante la preparazione sono solo in avanti e non possono essere ripristinate. Tuttavia, le migrazioni dello schema sono compatibili con le versioni precedenti della versione di origine, consentendo ai binari del server precedenti di continuare a funzionare normalmente.
• Fase binaria: può essere eseguito il rollback alla versione precedente in qualsiasi momento prima dell'inizio della finalizzazione. Per saperne di più, consulta Rollback del file binario o dell'immagine container.
• Fasi di implementazione facoltative: per le fasi facoltative che supportano il rollback automatico (ad esempio l'attivazione delle funzionalità), avvia il rollback utilizzando la CLI Spanner Omni.
• Fase di finalizzazione: non può essere eseguito il rollback. Una volta avviata la finalizzazione, la versione di destinazione viene sigillata in modo permanente nel deployment e i rollback non sono possibili.

Esegui il rollback del binario o dell'immagine container

Per eseguire il rollback della fase binaria prima dell'inizio della finalizzazione, esegui un riavvio in sequenza su tutti i server o i pod per ripristinare la versione precedente (origine).

VM

Nei deployment di VM, esegui il rollback del binario spanner_server su tutte le VM:

1. Esegui il deployment della versione binaria spanner_server precedente sugli host.
2. Riavvia i server in modo progressivo nei domini di errore, aggiornando una zona alla volta e riavviando non più del 5% dei server contemporaneamente per mantenere il quorum Paxos.
3. Verifica che tutti i server riavviati siano integri e si siano uniti 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 esempio 1.0.0.
• NAMESPACE: lo spazio dei nomi Kubernetes del deployment, ad esempio spanner-ns.
• SOURCE_VERSION: Il tag dell'immagine container precedente a cui ripristinare lo stato, ad esempio 2026.r2-beta.3.

Kubernetes autonomo

Nei deployment Kubernetes personalizzati senza Helm, aggiorna l'immagine container nelle specifiche di StatefulSet o Deployment a SOURCE_VERSION.

Esegui un aggiornamento in sequenza nei domini di errore, aggiornando una zona alla volta e riavviando non più del 5% dei pod contemporaneamente per mantenere il quorum.

Eseguire 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 del rollout.
• DEPLOYMENT_ENDPOINT: l'endpoint di un server nel tuo deployment.

Passaggi successivi

• Scopri come mantenere un deployment.
• Scopri come scalare un deployment Kubernetes o scalare un deployment di VM.
• Scopri di più sulla panoramica di Monitoring.