Actualiza una implementación de Spanner Omni

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 estados de lanzamiento progresivo asíncrono para garantizar actualizaciones seguras sin interrupciones del servicio. La actualización por fases te permite hacer lo siguiente:

Flujo de trabajo de actualización

El proceso de actualización de Spanner Omni consta de varias fases secuenciales:

  1. 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 esquema no se pueden revertir, pero son retrocompatibles con la versión binaria anterior.
  2. Fase binaria: Actualiza el objeto binario del servidor o la imagen de contenedor en todos los servidores del Deployment 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.
  3. Fase de habilitación de funciones: Habilita las funciones compatibles con la versión y comienza después de que actualizas el archivo 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.
  4. Fase de finalización: Finaliza el lanzamiento y sella la versión de destino. Una vez 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 previos:

  • 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 e instalaste la CLI de Spanner Omni.
  • Tienes acceso a la red para 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 a la red para el extremo de implementación.
  • Si tu implementación usa 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/tls o montados en tu clúster.
  • Identificaste la versión de destino:
    • Para las implementaciones de VM, descarga el paquete de lanzamiento de destino spanner-omni-server-TARGET_VERSION.tar.gz.
    • Para las implementaciones de Helm y Kubernetes, identifica la imagen del contenedor de destino en Artifact Registry, como us-docker.pkg.dev/spanner-omni/images/spanner-omni:TARGET_VERSION.

Paso 1: Prepara la actualización del esquema

Para iniciar la actualización, prepara el lanzamiento para 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 de 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.

  1. Accede a un servidor de tu implementación que tenga acceso a la red a todos los puertos internos de Spanner Omni (TCP 15000 a 15027).

  2. Descarga y extrae el paquete de lanzamiento de destino:

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

    Reemplaza lo siguiente:

    • TARGET_VERSION: Es la versión de destino a la que se actualizará, por ejemplo, 2026.r4-lts.
    • EXTRACT_DIR: Es el directorio en el que extraes el paquete de lanzamiento, por ejemplo, /tmp/target_spanner/.

  3. Para iniciar la preparación del lanzamiento, ejecuta el comando rollouts prepare desde 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_DIR

    Reemplaza lo siguiente:

    • EXTRACT_DIR: Es el directorio de extracción que contiene la CLI de bin/spanner y el binario de bin/spanner_server de destino.
    • ROOT_SERVERS: Un extremo de servidor raíz o una lista separada por comas de varios servidores raíz, por ejemplo, localhost:15000 o server1:15000,server2:15000,server3:15000.
    • BASE_DIR: Es el directorio base de Spanner Omni, por ejemplo, /spanner.
    • Si tu implementación usa encriptación TLS o mTLS, agrega --ca-certificate-file=CA_CERT_FILE y --client-certificate-directory=CERT_DIR que 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 upgrade en el paso 3: Actualiza la imagen binaria o de contenedor, el gráfico de Helm activa el trabajo de hook previo a la actualización spanner-prepare-for-upgrade para ejecutar migraciones de esquemas antes de actualizar cualquier StatefulSet. Ve directamente al paso 2: Verifica el estado de la actualización progresiva activa.

  • Implementaciones de un solo servidor (deployment.singleServer=true): Dado 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 acceder a ellos. Ejecuta la migración del esquema de forma local dentro del pod en ejecución con un contenedor de depuración efímero que tenga 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.1

    Reemplaza 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.r4-lts.

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.

  1. Crea un archivo llamado spanner-prepare-upgrade.yaml con 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.r4-lts.
    • ROOT_SERVER_ENDPOINT: Es el extremo de un pod de servidor raíz activo, por ejemplo, spanner-a-0.pod.spanner-ns.

  2. 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

Después de que se complete el paso de preparación, verifica que se haya creado el lanzamiento y revisa el estado de su fase.

  1. Enumera los lanzamientos activos para recuperar el ID del lanzamiento:

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

    Reemplaza DEPLOYMENT_ENDPOINT por el extremo de un servidor en tu implementación, por ejemplo, localhost:15000 o spanner-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    -

  2. Inspecciona el estado detallado 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: 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

    Verifica los siguientes estados de fase antes de continuar:

    • schema: Muestra SUCCEEDED, lo que indica que se completaron las migraciones internas del esquema de la base de datos.
    • binary: Muestra IN_PROGRESS, lo que indica que el motor de lanzamiento está listo para las actualizaciones binarias.
    • finalize: Muestra PENDING, a la espera de que se complete la fase binaria.

Paso 3: Actualiza la imagen binaria o de contenedor

Después de que la fase de esquema se complete correctamente, actualiza el archivo binario del servidor en ejecución o la imagen del contenedor en todos los nodos de la implementación a la versión de destino.

Selecciona la pestaña de 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 o una zona de falla a la vez: En las implementaciones multizonales, actualiza los servidores en una zona y verifica la estabilidad antes de actualizar la siguiente zona. Esto garantiza que el grupo de consenso de Paxos conserve el quórum.
  • Reinicio progresivo: No reinicies más del 5% de los servidores de forma simultánea para mantener la disponibilidad continua de las consultas continuas.
  • Verifica el estado del servidor: Asegúrate de que todos los servidores reiniciados estén en buen estado y se hayan unido al clúster antes de actualizar el siguiente dominio de falla.

Helm

En las implementaciones de Helm, ejecuta helm upgrade y conserva 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 30m

    Helm 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=true de forma explícita para que Helm omita el trabajo del hook previo a la actualización, ya que ya 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 del gráfico de Helm de destino, por ejemplo, 1.0.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 del contenedor de destino, por ejemplo, 2026.r4-lts.

Kubernetes independiente

En las implementaciones personalizadas de Kubernetes sin Helm, actualiza la imagen del contenedor en las especificaciones de StatefulSet o Deployment a TARGET_VERSION.

Realiza una actualización progresiva en los dominios de falla, actualiza una zona a la vez y no reinicies más del 5% de los Pods de forma simultánea para conservar 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 correctamente.

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 de la implementación permanece en IN_PROGRESS hasta que se completen todas las fases restantes. Después de que phases/binary pasa a SUCCEEDED, la implementación está 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 del lanzamiento hasta la fase finalize. La fase finalize (la última fase de un lanzamiento) sella la nueva versión en toda la implementación. Puedes ejecutar este comando desde cualquier máquina que tenga acceso a la red del 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:

  1. Programa la fase:

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

    Reemplaza lo siguiente:

    • PHASE_NAME: Es el nombre de la fase que se programará, por ejemplo, finalize o enable_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-beta

  2. Espera a que la fase se complete correctamente y verifica su estado:

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

    Repite estos pasos para cada fase restante hasta que se completen todas las fases, incluida la fase finalize.

    Después de que se completa la fase final (finalize), todas las fases y el estado general del lanzamiento pasan 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. Confirma el estado completado en la lista de lanzamientos:

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

    El 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 dependerá de la 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 hacia adelante y no se pueden revertir. Sin embargo, las migraciones de esquemas son retrocompatibles con la versión de origen, lo que permite que los archivos 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 Cómo revertir el objeto binario o la imagen de contenedor.
  • 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 revertir los cambios.

Cómo revertir la imagen binaria o 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 VMs, revierte el archivo binario spanner_server en todas las VMs:

  1. Implementa la versión anterior del objeto binario spanner_server en tus hosts.
  2. Reinicia los servidores de forma progresiva en todos los dominios de falla, actualiza una zona a la vez y reinicia no más del 5% de los servidores de forma simultánea para conservar el quórum de Paxos.
  3. Verifica que todos los servidores reiniciados estén en buen estado y se hayan unido al clúster antes de continuar con el siguiente dominio de falla.

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.0.0.
  • NAMESPACE: Es el espacio de nombres de Kubernetes de la implementación, por ejemplo, spanner-ns.
  • SOURCE_VERSION: Es la etiqueta anterior de la imagen del contenedor a la que se revertirá, por ejemplo, 2026.r2-beta.3.

Kubernetes independiente

En las implementaciones personalizadas de Kubernetes sin Helm, actualiza la imagen del contenedor en las especificaciones de StatefulSet o Deployment a SOURCE_VERSION.

Realiza una actualización progresiva en los dominios de falla, actualiza una zona a la vez y no reinicies más del 5% de los Pods de forma simultánea para conservar el quórum.

Cómo revertir 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: ID numérico del lanzamiento.
  • DEPLOYMENT_ENDPOINT: Es el extremo de un servidor en tu implementación.

¿Qué sigue?