En este documento, se describe cómo actualizar una implementación de Spanner Omni de una versión anterior a una posterior.
Spanner Omni usa una máquina de estado de lanzamiento asíncrona y por fases para garantizar actualizaciones seguras sin interrupciones del servicio. La actualización por fases te permite hacer lo siguiente:
- Aplica actualizaciones del esquema de la base de datos.
- Verifica la compatibilidad binaria durante un reinicio progresivo.
- Revierte a la versión anterior si detectas errores antes de la finalización.
Rutas de actualización compatibles
Solo puedes actualizar una versión de LTS a la siguiente versión de LTS. No puedes omitir una versión cuando actualizas a una versión de LTS más reciente.
Puedes omitir una versión cuando actualizas de una versión de asistencia a corto plazo (STS) a otra versión de STS si no hay una versión de LTS entre sus fechas de lanzamiento.
Para obtener más información, consulta la política de asistencia de la versión.
Flujo de trabajo de actualización
El proceso de actualización de Spanner Omni consta de varias fases secuenciales:
- Fase de esquema: Prepara la implementación ejecutando migraciones internas del esquema de la base de datos con la versión binaria de destino. Las migraciones de esquemas no se pueden revertir, pero son retrocompatibles con la versión binaria anterior.
- Fase binaria: Actualiza el objeto binario del servidor o la imagen de contenedor en todos los servidores de la implementación con un reinicio progresivo. Si detectas errores, puedes revertir el objeto binario o la imagen de contenedor a la versión anterior en cualquier momento antes de que comience la finalización.
- Fase de habilitación de funciones: Habilita las funciones compatibles con la versión y comienza después de actualizar el objeto binario en todos los servidores. Es posible que esta fase no se aplique si la actualización no incluye funciones compatibles con la versión, y puede requerir varias rondas si las funciones son interdependientes. En el caso de las fases opcionales que admiten la reversión, puedes iniciar una reversión con la CLI de Spanner Omni.
- Fase de finalización: Finaliza el lanzamiento y sella la versión de destino. Después de que comienza la fase de finalización, no es posible realizar reversiones.
Antes de comenzar
Antes de actualizar tu implementación de Spanner Omni, asegúrate de cumplir con los siguientes requisitos:
- Tienes una implementación de Spanner Omni en ejecución. Para obtener más información, consulta Crea una implementación en Kubernetes o Crea una implementación en VMs.
- Descargaste y, luego, instalaste la CLI de Spanner Omni.
- Tienes acceso de red a todos los puertos internos de Spanner Omni (TCP 15000 a 15027) desde la máquina en la que ejecutas los comandos de la CLI o acceso de red al extremo de implementación.
- Si tu implementación usa la encriptación de seguridad de la capa de transporte (TLS) o TLS mutua (mTLS),
asegúrate de que haya certificados válidos disponibles en tu directorio base
en
BASE_DIR/tlso que estén activados en tu clúster. - Identificaste tu versión de destino:
- Para las implementaciones de VM, descarga el paquete de la versión de destino
spanner-omni-server-TARGET_VERSION.tar.gz. - Para las implementaciones de Helm y Kubernetes, identifica la imagen de contenedor de destino en Artifact Registry, como
us-docker.pkg.dev/spanner-omni/images/spanner-omni:TARGET_VERSION.
- Para las implementaciones de VM, descarga el paquete de la versión de destino
- Los administradores de las implementaciones de Spanner Omni deben programar períodos de mantenimiento para las actualizaciones. Tu organización debe evitar las implementaciones durante los períodos de mantenimiento de actualización.
Paso 1: Prepara la actualización del esquema
Para iniciar la actualización, prepara el lanzamiento de la versión de destino. En esta fase, Spanner Omni ejecuta migraciones internas del esquema de la base de datos mientras los servidores existentes siguen entregando tráfico.
Selecciona la pestaña correspondiente a tu entorno de implementación:
VM
En las implementaciones de VM, descarga y extrae el paquete de la versión de destino y, luego, usa la CLI de Spanner Omni extraída para iniciar la preparación del lanzamiento.
Accede a un servidor de tu implementación que tenga acceso de red a todos los puertos internos de Spanner Omni (TCP 15000 a 15027).
Descarga y extrae el paquete de lanzamiento de destino:
tar -xzf spanner-omni-server-TARGET_VERSION.tar.gz -C EXTRACT_DIRReemplaza lo siguiente:
TARGET_VERSION: Es la versión de destino a la que se actualizará, por ejemplo,2026.r5.EXTRACT_DIR: Es el directorio en el que extraes el paquete de la versión, por ejemplo,/tmp/target_spanner/.
Inicia la preparación del lanzamiento ejecutando el comando
rollouts preparedesde la 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_DIRReemplaza lo siguiente:
EXTRACT_DIR: Es el directorio de extracción que contiene la CLI debin/spannery el objeto binario debin/spanner_serverde destino.ROOT_SERVERS: Es un extremo de servidor raíz o una lista separada por comas de varios servidores raíz, por ejemplo,localhost:15000oserver1:15000,server2:15000,server3:15000.BASE_DIR: Es el directorio base de Spanner Omni, por ejemplo,/spanner.- Si tu implementación usa la encriptación TLS o mTLS, agrega
--ca-certificate-file=CA_CERT_FILEy--client-certificate-directory=CERT_DIRque apunten a certificados válidos.
Helm
En las implementaciones de Helm, la preparación del esquema depende de si ejecutas una implementación de varios servidores o de un solo servidor:
Implementaciones de varios servidores (alta disponibilidad/producción): Helm controla automáticamente la preparación del esquema. Cuando ejecutas
helm upgradeen el Paso 3: Actualiza la imagen de contenedor o el objeto binario, el gráfico de Helm activa el trabajo de hook de actualización previaspanner-prepare-for-upgradepara ejecutar migraciones de esquemas antes de actualizar cualquier StatefulSet. Continúa directamente con el Paso 2: Verifica el estado de la actualización progresiva activa.Implementaciones de un solo servidor (
deployment.singleServer=true): Debido a que el modo de un solo servidor vincula los servicios internos estrictamente a la interfaz de bucle invertido (127.0.0.1), los trabajos de red no pueden alcanzarlos. Ejecuta la migración de esquemas de forma local dentro del Pod en ejecución con un contenedor de depuración efímero con la imagen de contenedor 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.1Reemplaza lo siguiente:
POD_NAME: Es el nombre del Pod del servidor, por ejemplo,spanner-a-0.NAMESPACE: Es el espacio de nombres de Kubernetes de la implementación, por ejemplo,spanner-ns.TARGET_VERSION: Es la versión de destino a la que se actualizará, por ejemplo,2026.r5.
Kubernetes independiente
Si implementas Spanner Omni en Kubernetes sin Helm, ejecuta un trabajo por lotes de Kubernetes independiente para ejecutar migraciones de esquemas en el servidor raíz activo con la imagen de destino.
Crea un archivo llamado
spanner-prepare-upgrade.yamlcon el siguiente manifiesto de trabajo: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: {}Reemplaza lo siguiente:
NAMESPACE: Es el espacio de nombres de Kubernetes de la implementación, por ejemplo,spanner-ns.TARGET_VERSION: Es la versión de destino a la que se actualizará, por ejemplo,2026.r5.ROOT_SERVER_ENDPOINT: Es el extremo de un Pod de servidor raíz activo, por ejemplo,spanner-a-0.pod.spanner-ns.
Aplica el manifiesto para ejecutar el trabajo de preparación:
kubectl apply -f spanner-prepare-upgrade.yaml
Paso 2: Verifica el estado de la actualización progresiva activa
Una vez que se complete el paso de preparación, verifica que se haya creado el lanzamiento y revisa el estado de su fase.
Enumera los lanzamientos activos para recuperar el ID de lanzamiento:
spanner deployment rollouts list \ --deployment-endpoint=DEPLOYMENT_ENDPOINTReemplaza
DEPLOYMENT_ENDPOINTpor el extremo de un servidor en tu implementación, por ejemplo,localhost:15000ospanner-a-0.pod.spanner-ns:15000.El resultado es similar a lo siguiente:
NAME STATE TARGET_VERSION START_TIME END_TIME rollouts/1788942172101727 IN_PROGRESS 2026.r3-beta 2026-09-09T08:22:52.101727Z -Inspecciona el estado detallado de la fase de lanzamiento:
spanner deployment rollouts describe ROLLOUT_ID \ --deployment-endpoint=DEPLOYMENT_ENDPOINTReemplaza lo siguiente:
ROLLOUT_ID: Es el ID numérico del lanzamiento, por ejemplo,1788942172101727.DEPLOYMENT_ENDPOINT: Es el extremo de un servidor en tu implementación.
El resultado es similar a lo siguiente:
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-betaVerifica los siguientes estados de fase antes de continuar:
schema: MuestraSUCCEEDED, lo que indica que se completaron las migraciones internas del esquema de la base de datos.binary: MuestraIN_PROGRESS, lo que indica que el motor de lanzamiento está listo para las actualizaciones de objetos binarios.finalize: MuestraPENDING, que espera que se complete la fase binaria.
Paso 3: Actualiza el objeto binario o la imagen de contenedor
Después de que la fase de esquema se complete correctamente, actualiza el objeto binario del servidor en ejecución o la imagen de contenedor en todos los nodos de la implementación a la versión de destino.
Selecciona la pestaña correspondiente a tu entorno de implementación:
VM
En las implementaciones de VM, actualiza el objeto binario spanner_server en todas las VMs con
un reinicio progresivo:
- Actualiza un dominio con fallas o una zona a la vez: En las implementaciones multizonales, actualiza los servidores en una zona y verifica la estabilidad antes de actualizar la siguiente. Esto garantiza que el grupo de consenso de Paxos conserve el quórum.
- Reinicia de forma progresiva: No reinicies más del 5% de los servidores de forma simultánea para mantener la disponibilidad continua de las consultas.
- Verifica el estado del servidor: Asegúrate de que todos los servidores reiniciados estén en buen estado y se hayan vuelto a unir al clúster antes de actualizar el siguiente dominio con fallas.
Helm
En las implementaciones de Helm, ejecuta helm upgrade mientras conservas los valores de configuración existentes pasando --reuse-values o proporcionando un archivo de valores:
Implementaciones de varios servidores (producción/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 30mHelm ejecuta automáticamente la fase 1 con el hook previo a la actualización y, luego, inicia una actualización progresiva secuencial, zona por zona, de los StatefulSets (
rollout.staggered: true).Implementaciones de un solo servidor (
deployment.singleServer=true):Pasa
--set skipPrepareUpgrade=truede forma explícita para que Helm omita el trabajo de hook previo a la actualización, ya que completaste la fase 1 de forma local: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
Reemplaza lo siguiente:
CHART_VERSION: Es la versión de destino del gráfico de Helm, por ejemplo,1.1.0.NAMESPACE: Es el espacio de nombres de Kubernetes de la implementación, por ejemplo,spanner-ns.TARGET_VERSION: Es la etiqueta de la imagen de contenedor de destino, por ejemplo,2026.r5.
Kubernetes independiente
En las implementaciones de Kubernetes personalizadas sin Helm, actualiza la imagen de contenedor
en las especificaciones de StatefulSet o Deployment a
TARGET_VERSION.
Realiza una actualización progresiva en los dominios con fallas, actualiza una zona a la vez y reinicia no más del 5% de los Pods de forma simultánea para preservar el quórum.
Paso 4: Verifica la progresión de la fase binaria
Después de actualizar todos los servidores o Pods a la versión de destino, verifica que la fase binaria se complete de forma correcta.
Verifica el estado de la fase de lanzamiento:
spanner deployment rollouts describe ROLLOUT_ID \
--deployment-endpoint=DEPLOYMENT_ENDPOINT
Reemplaza lo siguiente:
ROLLOUT_ID: Es el ID numérico del lanzamiento, por ejemplo,1788942172101727.DEPLOYMENT_ENDPOINT: Es el extremo de un servidor en tu implementación.
El resultado es similar a lo siguiente:
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
Confirma que el estado de la fase binary cambie a SUCCEEDED. El estado general
del lanzamiento sigue siendo IN_PROGRESS hasta que se completen todas las fases restantes. Después de que
phases/binary cambie a SUCCEEDED, la implementación estará lista para continuar
con las fases restantes.
Paso 5: Programa y ejecuta las fases restantes
Cuando la fase binaria se complete correctamente y verifiques que tu implementación es estable,
programa las fases restantes para el lanzamiento hasta la fase finalize.
La fase finalize (la última fase de un lanzamiento) sella la versión nueva en toda
la implementación. Puedes ejecutar este comando desde cualquier máquina que tenga acceso de red
al servicio de Spanner Omni especificando
--deployment-endpoint.
Para cada fase restante en el estado PENDING (como enable_features si
está presente, seguido de finalize), completa los siguientes pasos:
Programa la fase:
spanner deployment rollouts phases schedule PHASE_NAME \ --rollout=ROLLOUT_ID \ --deployment-endpoint=DEPLOYMENT_ENDPOINTReemplaza lo siguiente:
PHASE_NAME: Es el nombre de la fase que se programará, por ejemplo,finalizeoenable_features.ROLLOUT_ID: Es el ID numérico del lanzamiento, por ejemplo,1788942172101727.DEPLOYMENT_ENDPOINT: Es el extremo de un servidor en tu implementación.
El resultado indica que la fase programada es
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-betaEspera a que la fase se complete correctamente y verifica su estado:
spanner deployment rollouts describe ROLLOUT_ID \ --deployment-endpoint=DEPLOYMENT_ENDPOINTRepite estos pasos para cada fase restante hasta que se completen todas las fases, incluida
finalize.Una vez que se completa la fase final (
finalize), todas las fases y el estado general del lanzamiento pasan aSUCCEEDED: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-betaConfirma el estado completado en la lista de lanzamientos:
spanner deployment rollouts list \ --deployment-endpoint=DEPLOYMENT_ENDPOINTEl resultado confirma que se completó el lanzamiento:
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
Revierte una actualización
Si tienes problemas durante una actualización, la posibilidad de revertirla depende de su fase de lanzamiento actual:
- Fase de esquema: No se puede revertir. Las migraciones internas del esquema de la base de datos que se aplican durante la preparación son solo de avance y no se pueden revertir. Sin embargo, las migraciones de esquemas son retrocompatibles con la versión de origen, lo que permite que los objetos binarios del servidor anteriores sigan funcionando con normalidad.
- Fase binaria: Se puede revertir a la versión anterior en cualquier momento antes de que comience la finalización. Para obtener más información, consulta Revierte la imagen de contenedor o el objeto binario.
- Fases de lanzamiento opcionales: Para las fases opcionales que admiten la reversión automática (como la habilitación de funciones), inicia la reversión con la CLI de Spanner Omni.
- Fase de finalización: No se puede revertir. Una vez que comienza la finalización, la versión de destino se sella de forma permanente en toda la implementación y no es posible revertirla.
Revierte el objeto binario o la imagen de contenedor
Para revertir la fase binaria antes de que comience la finalización, realiza un reinicio progresivo en todos los servidores o Pods para restablecer la versión anterior (de origen).
VM
En las implementaciones de VM, revierte el objeto binario spanner_server en todas las VMs:
- Implementa la versión anterior del objeto binario de
spanner_serveren tus hosts. - Reinicia los servidores de forma progresiva en los dominios con fallas, actualiza una zona a la vez y reinicia no más del 5% de los servidores de forma simultánea para preservar el quórum de Paxos.
- Verifica que todos los servidores reiniciados estén en buen estado y se hayan vuelto a unir al clúster antes de continuar con el siguiente dominio con fallas.
Helm
En las implementaciones de Helm, actualiza la etiqueta de la imagen de contenedor a la versión 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
Reemplaza lo siguiente:
CHART_VERSION: Es la versión del gráfico de Helm, por ejemplo,1.1.0.NAMESPACE: Es el espacio de nombres de Kubernetes de la implementación, por ejemplo,spanner-ns.SOURCE_VERSION: Es la etiqueta de imagen de contenedor anterior a la que se debe revertir, por ejemplo,2026.r2-beta.3.
Kubernetes independiente
En las implementaciones personalizadas de Kubernetes sin Helm, actualiza la imagen de contenedor
en las especificaciones de StatefulSet o Deployment de nuevo a
SOURCE_VERSION.
Realiza una actualización progresiva en los dominios con fallas, actualiza una zona a la vez y reinicia no más del 5% de los Pods de forma simultánea para preservar el quórum.
Revierte las fases de lanzamiento opcionales
Para las fases de lanzamiento opcionales que admiten la reversión (como las fases de habilitación de funciones), inicia la reversión ejecutando el comando rollouts rollback:
spanner deployment rollouts rollback ROLLOUT_ID \
--deployment-endpoint=DEPLOYMENT_ENDPOINT
Reemplaza lo siguiente:
ROLLOUT_ID: Es el ID numérico del lanzamiento.DEPLOYMENT_ENDPOINT: Es el extremo de un servidor en tu implementación.
¿Qué sigue?
- Obtén información para mantener una implementación.
- Obtén más información para escalar una implementación de Kubernetes o escalar una implementación de VM.
- Obtén más información sobre la descripción general de Monitoring.