Fazer upgrade de uma implantação do Spanner Omni

Neste documento, descrevemos como fazer upgrade de uma implantação do Spanner Omni de uma versão anterior para uma mais recente.

O Spanner Omni usa uma máquina de estado de lançamento gradual assíncrona para ajudar a garantir upgrades seguros sem interrupção do serviço. O upgrade em fases permite fazer o seguinte:

• Aplique atualizações no esquema do banco de dados.
• Verifique a compatibilidade binária durante uma reinicialização gradual.
• Reverta para a versão anterior se detectar erros antes da finalização.

Fluxo de trabalho de upgrade

O processo de upgrade do Spanner Omni consiste em várias fases sequenciais:

1. Fase de esquema: prepara a implantação executando migrações internas de esquema de banco de dados usando a versão binária de destino. Não é possível reverter as migrações de esquema, mas elas são compatíveis com versões anteriores do binário.
2. Fase binária: atualiza o binário do servidor ou a imagem do contêiner em todos os servidores na implantação usando uma reinicialização gradual. Se você detectar erros, poderá reverter o binário ou a imagem do contêiner para a versão anterior a qualquer momento antes do início da finalização.
3. Fase de ativação de recursos: ativa recursos compatíveis com a versão e começa depois que você atualiza o binário em todos os servidores. Essa fase pode não se aplicar se o upgrade não incluir recursos compatíveis com a versão, e pode exigir várias rodadas se os recursos forem interdependentes. Para fases opcionais que aceitam reversão, inicie uma reversão usando a CLI do Spanner Omni.
4. Fase de finalização: conclui o lançamento, selando a versão de destino. Depois que a fase de finalização começa, não é possível fazer rollbacks.

Antes de começar

Antes de fazer upgrade da implantação do Spanner Omni, verifique se você atende aos seguintes pré-requisitos:

• Você tem uma implantação do Spanner Omni em execução. Para mais informações, consulte Criar uma implantação no Kubernetes ou Criar uma implantação em VMs.
• Você fez o download e instalou a CLI do Spanner Omni.
• Você tem acesso à rede a todas as portas internas do Spanner Omni (TCP 15000 a 15027) na máquina em que executa os comandos da CLI ou acesso à rede ao endpoint de implantação.
• Se a implantação usar criptografia Transport Layer Security (TLS) ou TLS mútuo (mTLS), verifique se há certificados válidos disponíveis no diretório base em BASE_DIR/tls ou montados no cluster.
• Você identificou a versão de destino:
  • Para implantações de VM: faça o download do pacote de lançamento de destino spanner-omni-server-TARGET_VERSION.tar.gz.
  • Para implantações do Helm e do Kubernetes, identifique a imagem do contêiner de destino no Artifact Registry, como us-docker.pkg.dev/spanner-omni/images/spanner-omni:TARGET_VERSION.

Etapa 1: preparar o upgrade do esquema

Para iniciar o upgrade, prepare o lançamento para a versão de destino. Nesta fase, o Spanner Omni executa migrações internas de esquema de banco de dados enquanto os servidores atuais continuam atendendo ao tráfego.

Selecione a guia do seu ambiente de implantação:

VM

Em implantações de VM, faça o download e extraia o pacote de lançamento de destino e use a CLI do Spanner Omni extraída para iniciar a preparação do lançamento.

Importante: o pacote de lançamento do Spanner Omni de destino inclui a CLI spanner e o binário spanner_server (normalmente em bin/). Faça o download e extraia o pacote de lançamento de destino no host antes de executar a fase de preparação.

1. Faça login em um servidor na sua implantação que tenha acesso à rede a todas as portas internas do Spanner Omni (TCP 15000 a 15027).

2. Faça o download e extraia o pacote de lançamento de destino:

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

   Substitua:

   • TARGET_VERSION: a versão de destino para fazer upgrade, por exemplo, 2026.r4-lts.
   • EXTRACT_DIR: o diretório em que você extrai o pacote de lançamento, por exemplo, /tmp/target_spanner/.

3. Inicie a preparação do lançamento executando o comando rollouts prepare na CLI extraída:

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

   Substitua:

   • EXTRACT_DIR: o diretório de extração que contém a CLI bin/spanner de destino e o binário bin/spanner_server.
   • ROOT_SERVERS: um endpoint de servidor raiz ou uma lista separada por vírgulas de vários servidores raiz, por exemplo, localhost:15000 ou server1:15000,server2:15000,server3:15000.
   • BASE_DIR: o diretório base do Spanner Omni. Por exemplo, /spanner.
   • Se a implantação usar criptografia TLS ou mTLS, adicione --ca-certificate-file=CA_CERT_FILE e --client-certificate-directory=CERT_DIR apontando para certificados válidos.

Helm

Em implantações do Helm, a preparação do esquema depende de você executar uma implantação de vários servidores ou de um único servidor:

• Implantações de vários servidores (alta disponibilidade / Production): o Helm processa automaticamente a preparação do esquema. Ao executar helm upgrade na Etapa 3: atualizar o binário ou a imagem do contêiner, o gráfico do Helm aciona o job de hook pré-upgrade spanner-prepare-for-upgrade para executar migrações de esquema antes de atualizar qualquer StatefulSet. Vá direto para Etapa 2: verificar o estado ativo do lançamento.

• Implantações de servidor único (deployment.singleServer=true): como o modo de servidor único vincula os serviços internos estritamente à interface de loopback (127.0.0.1), os jobs de rede não podem alcançá-los. Execute a migração de esquema localmente dentro do pod em execução usando um contêiner de depuração efêmero com a imagem do contêiner de destino:

  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
  

  Substitua:

  • POD_NAME: o nome do pod do servidor, por exemplo, spanner-a-0.
  • NAMESPACE: o namespace do Kubernetes da implantação. Por exemplo, spanner-ns.
  • TARGET_VERSION: a versão de destino para fazer upgrade, por exemplo, 2026.r4-lts.

Kubernetes independente

Se você implantar o Spanner Omni no Kubernetes sem o Helm, execute um job em lote independente do Kubernetes para executar migrações de esquema no servidor raiz ativo usando a imagem de destino.

1. Crie um arquivo chamado spanner-prepare-upgrade.yaml com o seguinte manifesto de 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: {}
   

   Substitua:

   • NAMESPACE: o namespace do Kubernetes da implantação. Por exemplo, spanner-ns.
   • TARGET_VERSION: a versão de destino para fazer upgrade, por exemplo, 2026.r4-lts.
   • ROOT_SERVER_ENDPOINT: o endpoint de um pod de servidor raiz ativo, por exemplo, spanner-a-0.pod.spanner-ns.

2. Aplique o manifesto para executar o job de preparação:

   kubectl apply -f spanner-prepare-upgrade.yaml
   

Etapa 2: verificar o estado ativo do lançamento

Depois que a etapa de preparação for concluída, verifique se o lançamento foi criado e inspecione o status da fase.

Observação: em implantações do Helm com vários servidores, o Helm cria o rollout durante helm upgrade na etapa 3. É possível verificar o estado do lançamento durante ou após a execução dessa etapa.

1. Liste os lançamentos ativos para recuperar o ID:

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

   Substitua DEPLOYMENT_ENDPOINT pelo endpoint de um servidor na sua implantação, por exemplo, localhost:15000 ou spanner-a-0.pod.spanner-ns:15000.

   O resultado será o seguinte:

   NAME                         STATE          TARGET_VERSION    START_TIME                     END_TIME
   rollouts/1788942172101727    IN_PROGRESS    2026.r3-beta      2026-09-09T08:22:52.101727Z    -
   

2. Inspecione o status detalhado da fase de lançamento:

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

   Substitua:

   • ROLLOUT_ID: o ID numérico do lançamento, por exemplo, 1788942172101727.
   • DEPLOYMENT_ENDPOINT: o endpoint de um servidor na implantação.

   O resultado será o seguinte:

   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
   

   Verifique os seguintes status de fase antes de continuar:

   • schema: mostra SUCCEEDED, indicando que as migrações internas do esquema do banco de dados foram concluídas.
   • binary: mostra IN_PROGRESS, indicando que o mecanismo de lançamento está pronto para atualizações binárias.
   • finalize: mostra PENDING, aguardando a conclusão da fase binária.

Etapa 3: atualizar o binário ou a imagem do contêiner

Depois que a fase de esquema for concluída, atualize o binário ou a imagem do contêiner do servidor em execução em todos os nós da implantação para a versão de destino.

Dica: se você notar erros ou degradação de performance, reverta o binário ou a imagem do contêiner para a versão anterior a qualquer momento antes da finalização. Para mais informações, consulte Reverter um upgrade.

Selecione a guia do seu ambiente de implantação:

VM

Em implantações de VM, atualize o binário spanner_server em todas as VMs usando uma reinicialização gradual:

• Atualize um domínio de falha ou zona por vez: em implantações multizonais, atualize os servidores em uma zona e verifique a estabilidade antes de atualizar a próxima zona. Isso garante que o grupo de consenso do Paxos mantenha o quorum.
• Reinicie progressivamente: reinicie no máximo 5% dos servidores simultaneamente para manter a disponibilidade contínua de consultas.
• Verifique a integridade do servidor: confira se todos os servidores reiniciados estão íntegros e se reconectaram ao cluster antes de atualizar o próximo domínio de falha.

Helm

Em implantações do Helm, execute helm upgrade preservando os valores de configuração atuais transmitindo --reuse-values ou fornecendo um arquivo de valores:

• Implantações em vários servidores (Production / alta disponibilidade):

  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
  

  O Helm executa automaticamente a Fase 1 usando o hook de pré-upgrade e inicia uma atualização gradual sequencial, zona por zona, dos StatefulSets (rollout.staggered: true).

• Implantações de servidor único (deployment.singleServer=true):

  Transmita explicitamente --set skipPrepareUpgrade=true para que o Helm pule o job de hook pre-upgrade, porque você já concluiu a 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
  

Substitua:

• CHART_VERSION: a versão de gráfico Helm de destino, por exemplo, 1.0.0.
• NAMESPACE: o namespace do Kubernetes da implantação. Por exemplo, spanner-ns.
• TARGET_VERSION: a tag de imagem do contêiner de destino, por exemplo, 2026.r4-lts.

Kubernetes independente

Em implantações personalizadas do Kubernetes sem o Helm, atualize a imagem do contêiner nas especificações do StatefulSet ou da implantação para TARGET_VERSION.

Faça uma atualização gradual em todos os domínios de falha, atualizando uma zona por vez e reiniciando no máximo 5% dos pods simultaneamente para preservar o quorum.

Etapa 4: verificar a progressão da fase binária

Depois de atualizar todos os servidores ou pods para a versão de destino, verifique se a fase binária foi concluída com sucesso.

Observação: depois que todos os servidores na implantação são atualizados, o Spanner Omni rastreia a integridade do servidor em uma janela de observação de até 15 minutos antes de marcar a fase binary como SUCCEEDED.

Verifique o status da fase de lançamento:

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

Substitua:

• ROLLOUT_ID: o ID numérico do lançamento, por exemplo, 1788942172101727.
• DEPLOYMENT_ENDPOINT: o endpoint de um servidor na sua implantação.

O resultado será o seguinte:

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

Confirme se o status da fase binary mudou para SUCCEEDED. O estado geral do lançamento permanece IN_PROGRESS até que todas as fases restantes sejam concluídas. Depois que phases/binary passa para SUCCEEDED, a implantação está pronta para prosseguir para as fases restantes.

Etapa 5: programar e executar as fases restantes

Quando a fase binária for concluída e você verificar que a implantação está estável, programe as fases restantes para o lançamento até a fase finalize. A fase finalize (a última fase de um lançamento) sela a nova versão em toda a implantação. É possível executar esse comando em qualquer máquina com acesso à rede ao serviço do Spanner Omni especificando --deployment-endpoint.

Atenção: não é possível fazer o rollback depois que a finalização começa. Conclua o lançamento somente depois de observar a implantação por tempo suficiente e validar que ela está íntegra e estável em cargas de trabalho típicas. Para mais informações, consulte Reverter um upgrade.

Para cada fase restante no estado PENDING (como enable_features, se presente, seguido de finalize), siga estas etapas:

1. Programe a fase:

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

   Substitua:

   • PHASE_NAME: o nome da fase a ser programada, por exemplo, finalize ou enable_features.
   • ROLLOUT_ID: o ID numérico do lançamento, por exemplo, 1788942172101727.
   • DEPLOYMENT_ENDPOINT: o endpoint de um servidor na implantação.

   A saída indica que a fase programada é 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. Aguarde a conclusão da fase e verifique o status dela:

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

   Repita essas etapas para cada fase restante até que todas as fases até finalize (inclusive) sejam concluídas.

   Depois que a fase final (finalize) for concluída, todas as fases e o estado geral de lançamento vão passar para 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. Confirme o status "Concluído" na lista de lançamentos:

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

   A saída confirma que o lançamento foi concluído:

   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
   

Reverter um upgrade

Se você encontrar problemas durante um upgrade, a possibilidade de reverter o upgrade vai depender da fase de lançamento atual:

• Fase de esquema: não pode ser revertida. As migrações de esquema de banco de dados interno aplicadas durante a preparação são somente para frente e não podem ser revertidas. No entanto, as migrações de esquema são compatíveis com versões anteriores da versão de origem, permitindo que os binários de servidor anteriores continuem operando normalmente.
• Fase binária: pode ser revertida para a versão anterior a qualquer momento antes do início da finalização. Para mais informações, consulte Reverter o binário ou a imagem do contêiner.
• Fases de lançamento opcionais: para fases opcionais que oferecem suporte à reversão automática (como ativação de recursos), inicie a reversão usando a CLI do Spanner Omni.
• Fase de finalização: não pode ser revertida. Depois que a finalização começa, a versão de destino é permanentemente selada em toda a implantação e não é possível fazer rollbacks.

Reverter o binário ou a imagem do contêiner

Para reverter a fase binária antes do início da finalização, faça uma reinicialização contínua em todos os servidores ou pods para restaurar a versão anterior (de origem).

VM

Em implantações de VM, reverter o binário spanner_server em todas as VMs:

1. Implante a versão binária spanner_server anterior nos seus hosts.
2. Reinicie os servidores progressivamente em todos os domínios de falha, atualizando uma zona por vez e reiniciando não mais que 5% dos servidores simultaneamente para preservar o quorum do Paxos.
3. Verifique se todos os servidores reiniciados estão íntegros e se reconectaram ao cluster antes de passar para o próximo domínio de falha.

Helm

Em implantações do Helm, atualize a tag da imagem do contêiner para a versão anterior:

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

Substitua:

• CHART_VERSION: a versão do gráfico Helm. Por exemplo, 1.0.0.
• NAMESPACE: o namespace do Kubernetes da implantação. Por exemplo, spanner-ns.
• SOURCE_VERSION: a tag de imagem do contêiner anterior a ser revertida. Por exemplo, 2026.r2-beta.3.

Kubernetes independente

Em implantações personalizadas do Kubernetes sem o Helm, atualize a imagem do contêiner nas especificações do StatefulSet ou da implantação de volta para SOURCE_VERSION.

Faça uma atualização gradual em todos os domínios de falha, atualizando uma zona por vez e reiniciando no máximo 5% dos pods simultaneamente para preservar o quorum.

Reverter fases opcionais de lançamento

Para fases de lançamento opcionais que aceitam reversão (como fases de ativação de recursos), inicie a reversão executando o comando rollouts rollback:

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

Substitua:

• ROLLOUT_ID: o ID numérico do lançamento.
• DEPLOYMENT_ENDPOINT: o endpoint de um servidor na sua implantação.

A seguir

• Saiba como manter uma implantação.
• Saiba como escalonar uma implantação do Kubernetes ou escalonar uma implantação de VM.
• Saiba mais sobre a visão geral do Monitoring.