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:
- Aplicar atualizações do esquema do banco de dados.
- Verifique a compatibilidade binária durante uma reinicialização gradual.
- Reverta para a versão anterior se você detectar erros antes da finalização.
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:
- 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.
- 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.
- 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.
- 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/tlsou 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.
- Para implantações de VM: faça o download do pacote de lançamento de destino
- 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.
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).
Faça o download e extraia o pacote de lançamento de destino:
tar -xzf spanner-omni-server-TARGET_VERSION.tar.gz -C EXTRACT_DIRSubstitua:
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/.
Inicie a preparação do lançamento executando o comando
rollouts preparena 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_DIRSubstitua:
EXTRACT_DIR: o diretório de extração que contém a CLI de destinobin/spannere o bináriobin/spanner_server.ROOT_SERVERS: um endpoint de servidor raiz ou uma lista separada por vírgulas de vários servidores raiz, por exemplo,localhost:15000ouserver1: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_FILEe--client-certificate-directory=CERT_DIRapontando 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 upgradena Etapa 3: atualizar o binário ou a imagem do contêiner, o gráfico do Helm aciona o job de hook de pré-upgradespanner-prepare-for-upgradepara 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.1Substitua:
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.
Crie um arquivo chamado
spanner-prepare-upgrade.yamlcom 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.
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.
Liste os lançamentos ativos para recuperar o ID do lançamento:
spanner deployment rollouts list \ --deployment-endpoint=DEPLOYMENT_ENDPOINTSubstitua
DEPLOYMENT_ENDPOINTpelo endpoint de um servidor na implantação, por exemplo,localhost:15000ouspanner-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 -Inspecione o status detalhado da fase de lançamento:
spanner deployment rollouts describe ROLLOUT_ID \ --deployment-endpoint=DEPLOYMENT_ENDPOINTSubstitua:
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-betaVerifique os seguintes status de fase antes de continuar:
schema: mostraSUCCEEDED, indicando que as migrações de esquema de banco de dados interno foram concluídas.binary: mostraIN_PROGRESS, indicando que o mecanismo de lançamento está pronto para atualizações binárias.finalize: mostraPENDING, 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 30mO 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=truepara 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:
Programe a fase:
spanner deployment rollouts phases schedule PHASE_NAME \ --rollout=ROLLOUT_ID \ --deployment-endpoint=DEPLOYMENT_ENDPOINTSubstitua:
PHASE_NAME: o nome da fase a ser programada, por exemplo,finalizeouenable_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-betaAguarde a conclusão da fase e verifique o status dela:
spanner deployment rollouts describe ROLLOUT_ID \ --deployment-endpoint=DEPLOYMENT_ENDPOINTRepita 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 paraSUCCEEDED: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-betaConfirme o status de conclusão na lista de lançamentos:
spanner deployment rollouts list \ --deployment-endpoint=DEPLOYMENT_ENDPOINTA 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:
- Implante a versão binária anterior do
spanner_servernos hosts. - 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.
- 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
- 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.