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 versão mais recente.

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

Caminhos de upgrade compatíveis

  • Só é possível atualizar uma versão LTS para a próxima versão LTS. Não é possível pular uma versão ao atualizar para uma versão LTS mais recente.

  • É possível pular uma versão ao fazer upgrade de uma versão de suporte de curto prazo (STS) para outra versão de STS se não houver uma versão de LTS entre as datas de lançamento.

Para mais informações, consulte a Política de suporte de versões.

Fazer upgrade do fluxo de trabalho

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

  1. Fase de esquema: prepara a implantação executando migrações de esquema de banco de dados interno usando a versão binária de destino. As migrações de esquema não podem ser revertidas, mas 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ê faz upgrade do 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 oferecem suporte à reversão, é possível iniciar uma reversão usando a CLI do Spanner Omni.
  4. Fase de finalização: finaliza o lançamento, selando a versão de destino. Depois que a fase de finalização começa, não é possível fazer reversões.

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 de 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 de rede ao endpoint de implantação.
  • Se a implantação usar a 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.
  • Os administradores de implantações do Spanner Omni precisam programar janelas de manutenção para upgrades. Sua organização deve evitar implantações durante as janelas de manutenção de upgrade.

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, em seguida, use a CLI do Spanner Omni extraída para iniciar a preparação do lançamento.

  1. Faça login em um servidor na sua implantação que tenha acesso de 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 o upgrade, por exemplo, 2026.r5.
    • 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 de destino bin/spanner 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, anexe --ca-certificate-file=CA_CERT_FILE e --client-certificate-directory=CERT_DIR apontando para certificados válidos.

Helm

Nas implantações do Helm, a preparação do esquema depende se você executa 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. Quando você executa 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 de pré-upgrade spanner-prepare-for-upgrade para executar migrações de esquema antes de atualizar qualquer StatefulSet. Vá diretamente para a Etapa 2: verificar o estado de lançamento ativo.

  • Implantações de servidor único (deployment.singleServer=true): como o modo de servidor único vincula serviços internos estritamente à interface de loopback (127.0.0.1), os jobs de rede não podem acessá-los. Execute a migração de esquema localmente dentro do pod em execução usando um contêiner de depuração temporário 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 upgrade, por exemplo, 2026.r5.

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 upgrade, por exemplo, 2026.r5.
    • 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 do lançamento ativo

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

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

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

    Substitua DEPLOYMENT_ENDPOINT pelo endpoint de um servidor na 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 de esquema de banco de dados interno 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 do esquema for concluída, atualize o binário do servidor em execução ou a imagem do contêiner em todos os nós da implantação para a versão de destino.

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 multizonas, 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 quórum.
  • Reiniciar progressivamente: reinicie no máximo 5% dos servidores simultaneamente para manter a disponibilidade contínua de consultas contínuas.
  • Verifique a integridade do servidor: confira se todos os servidores reiniciados estão íntegros e voltaram 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, em seguida, 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 de pré-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 destino do gráfico do Helm, por exemplo, 1.1.0.
  • NAMESPACE: o namespace do Kubernetes da implantação, por exemplo, spanner-ns.
  • TARGET_VERSION: a tag da imagem do contêiner de destino, por exemplo, 2026.r5.

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 nos domínios de falha, atualizando uma zona por vez e reiniciando no máximo 5% dos pods simultaneamente para preservar o quórum.

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.

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 muda para SUCCEEDED. O estado geral do lançamento permanece IN_PROGRESS até que todas as fases restantes sejam concluídas. Depois que phases/binary faz a transição 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 bem-sucedida 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 que tenha acesso de rede ao serviço do Spanner Omni especificando --deployment-endpoint.

Para cada fase restante no estado PENDING (como enable_features, se presente, seguido por 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, incluindo finalize, sejam concluídas.

    Depois que a fase final (finalize) é concluída, todas as fases e o estado geral do lançamento fazem a transição 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 de conclusão 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 do esquema: não pode ser revertida. As migrações de esquema de banco de dados interno aplicadas durante a preparação são somente de encaminhamento 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 a imagem binária ou de contêiner.
  • Fases de lançamento opcionais: para fases opcionais que oferecem suporte à reversão automatizada (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 as reversões não são possíveis.

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 anterior do spanner_server nos hosts.
  2. Reinicie os servidores progressivamente em domínios de falha, atualizando uma zona por vez e reiniciando no máximo 5% dos servidores simultaneamente para preservar o quórum do Paxos.
  3. Verifique se todos os servidores reiniciados estão íntegros e se juntaram novamente ao cluster antes de prosseguir 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 do Helm, por exemplo, 1.1.0.
  • NAMESPACE: o namespace do Kubernetes da implantação, por exemplo, spanner-ns.
  • SOURCE_VERSION: a tag de imagem do contêiner anterior para reverter, 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 nos domínios de falha, atualizando uma zona por vez e reiniciando no máximo 5% dos pods simultaneamente para preservar o quórum.

Reverter fases de lançamento opcionais

Para fases de lançamento opcionais que oferecem suporte à 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