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

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:

  1. 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.
  2. 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.
  3. 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.
  4. 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/tls o 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.
  • 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.

  1. 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).

  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 di cui eseguire l'upgrade, ad esempio 2026.r5.
    • EXTRACT_DIR: la directory in cui estrai il pacchetto di release, 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 e il file binario bin/spanner_server di destinazione.
    • ROOT_SERVERS: un endpoint del server root o un elenco separato da virgole di più server root, 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 tuo 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 su più server (alta affidabilità/produzione): Helm gestisce automaticamente la preparazione dello schema. Quando esegui helm upgrade nel Passaggio 3: aggiorna il file binario o l'immagine container, il grafico Helm attiva il job hook di 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.

  • 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.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 dell'upgrade, ad esempio 2026.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.

  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 dell'upgrade, ad esempio 2026.r5.
    • ROOT_SERVER_ENDPOINT: l'endpoint di un pod del server root 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 dell'implementazione attiva

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

  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. Controlla 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, che indica 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 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 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).

  • Deployment 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 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 esempio 1.1.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.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 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 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:

  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 venga completata e verifica lo stato:

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

    Ripeti questi passaggi per ogni fase rimanente fino a completare tutte le fasi fino alla finalize inclusa.

    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 di completamento nell'elenco delle implementazioni:

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

    L'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:

  1. Esegui il deployment della versione binaria spanner_server precedente sui tuoi host.
  2. 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.
  3. 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 esempio 1.1.0.
  • NAMESPACE: lo spazio dei nomi Kubernetes del deployment, ad esempio spanner-ns.
  • SOURCE_VERSION: il tag dell'immagine container precedente a cui eseguire il ripristino, ad esempio 2026.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