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 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:

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:

  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 esquemas 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 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.
  3. 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.
  4. 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/tls o 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.
  • 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.

  1. 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).

  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.r5.
    • EXTRACT_DIR: Es el directorio en el que extraes el paquete de la versión, por ejemplo, /tmp/target_spanner/.
  3. Inicia la preparación del lanzamiento ejecutando 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 objeto binario de bin/spanner_server de destino.
    • ROOT_SERVERS: Es 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 la 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 de contenedor o el objeto binario, el gráfico de Helm activa el trabajo de hook de actualización previa spanner-prepare-for-upgrade para 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.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.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.

  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.r5.
    • 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

Una vez 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 de 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 de objetos binarios.
    • finalize: Muestra PENDING, 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 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 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:

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

    Una vez 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 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:

  1. Implementa la versión anterior del objeto binario de spanner_server en tus hosts.
  2. 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.
  3. 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?