Mettre à niveau un déploiement Spanner Omni

Ce document explique comment mettre à niveau un déploiement Spanner Omni d'une version antérieure vers une version ultérieure.

Spanner Omni utilise une machine à états de déploiement progressif et asynchrone pour garantir des mises à niveau sécurisées sans interruption de service. La mise à niveau par phases vous permet d'effectuer les opérations suivantes :

Workflow de mise à niveau

Le processus de mise à niveau de Spanner Omni comporte plusieurs phases séquentielles :

  1. Phase de schéma : prépare le déploiement en exécutant des migrations de schéma de base de données internes à l'aide de la version binaire cible. Les migrations de schéma ne peuvent pas être annulées, mais elles sont rétrocompatibles avec la version binaire antérieure.
  2. Phase binaire : met à jour le fichier binaire du serveur ou l'image de conteneur sur tous les serveurs du déploiement à l'aide d'un redémarrage progressif. Si vous détectez des erreurs, vous pouvez effectuer un rollback du fichier binaire ou de l'image de conteneur à la version précédente à tout moment avant le début de la finalisation.
  3. Phase d'activation des fonctionnalités : active les fonctionnalités compatibles avec la version et commence après la mise à niveau du binaire sur tous les serveurs. Cette phase peut ne pas s'appliquer si la mise à niveau n'inclut pas de fonctionnalités compatibles avec la version. Elle peut nécessiter plusieurs cycles si les fonctionnalités sont interdépendantes. Pour les phases facultatives qui acceptent le rollback, vous pouvez lancer un rollback à l'aide de la CLI Spanner Omni.
  4. Phase de finalisation : finalise le déploiement et scelle la version cible. Une fois la phase de finalisation commencée, les annulations ne sont plus possibles.

Avant de commencer

Avant de mettre à niveau votre déploiement Spanner Omni, assurez-vous de remplir les conditions préalables suivantes :

  • Vous disposez d'un déploiement Spanner Omni en cours d'exécution. Pour en savoir plus, consultez Créer un déploiement sur Kubernetes ou Créer un déploiement sur des VM.
  • Vous avez téléchargé et installé la CLI Spanner Omni.
  • Vous avez accès au réseau pour tous les ports internes Spanner Omni (TCP 15000 à 15027) depuis la machine sur laquelle vous exécutez les commandes CLI, ou vous avez accès au réseau pour le point de terminaison de votre déploiement.
  • Si votre déploiement utilise le chiffrement TLS (Transport Layer Security) ou mTLS (mutual TLS), assurez-vous que des certificats valides sont disponibles dans votre répertoire de base sous BASE_DIR/tls ou montés dans votre cluster.
  • Vous avez identifié votre version cible :
    • Pour les déploiements de VM : téléchargez le package de version cible spanner-omni-server-TARGET_VERSION.tar.gz.
    • Pour les déploiements Helm et Kubernetes : identifiez l'image de conteneur cible dans Artifact Registry, par exemple us-docker.pkg.dev/spanner-omni/images/spanner-omni:TARGET_VERSION.

Étape 1 : Préparez la mise à niveau du schéma

Pour lancer la mise à niveau, préparez le déploiement pour la version cible. Au cours de cette phase, Spanner Omni exécute des migrations de schéma de base de données internes tandis que les serveurs existants continuent de diffuser du trafic.

Sélectionnez l'onglet correspondant à votre environnement de déploiement :

VM

Dans les déploiements de VM, téléchargez et extrayez le package de version cible, puis utilisez la CLI Spanner Omni extraite pour lancer la préparation du déploiement.

  1. Connectez-vous à un serveur de votre déploiement qui dispose d'un accès réseau à tous les ports internes de Spanner Omni (TCP 15000 à 15027).

  2. Téléchargez et extrayez le package de version cible :

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

    Remplacez les éléments suivants :

    • TARGET_VERSION : version cible vers laquelle effectuer la mise à niveau, par exemple 2026.r4-lts.
    • EXTRACT_DIR : répertoire dans lequel vous extrayez le package de version, par exemple /tmp/target_spanner/.

  3. Lancez la préparation du déploiement en exécutant la commande rollouts prepare à partir de la CLI extraite :

    EXTRACT_DIR/bin/spanner deployment rollouts prepare \
  --target-server-binary=EXTRACT_DIR/bin/spanner_server \
  --root-server=ROOT_SERVERS \
  --base-dir=BASE_DIR

    Remplacez les éléments suivants :

    • EXTRACT_DIR : répertoire d'extraction contenant la CLI bin/spanner cible et le binaire bin/spanner_server.
    • ROOT_SERVERS : un point de terminaison de serveur racine ou une liste de plusieurs serveurs racines séparés par une virgule, par exemple localhost:15000 ou server1:15000,server2:15000,server3:15000.
    • BASE_DIR : répertoire de base pour Spanner Omni, par exemple /spanner.
    • Si votre déploiement utilise le chiffrement TLS ou mTLS, ajoutez --ca-certificate-file=CA_CERT_FILE et --client-certificate-directory=CERT_DIR pointant vers des certificats valides.

Helm

Dans les déploiements Helm, la préparation du schéma dépend du type de déploiement que vous exécutez (multiserveur ou monoserveur) :

  • Déploiements multiserveurs (haute disponibilité / production) : Helm gère automatiquement la préparation du schéma. Lorsque vous exécutez helm upgrade dans Étape 3 : Mettez à jour l'image binaire ou l'image de conteneur, le chart Helm déclenche l'exécution du job de hook de pré-mise à niveau spanner-prepare-for-upgrade pour exécuter les migrations de schéma avant de mettre à jour les StatefulSets. Passez directement à l'étape 2 : Vérifiez l'état du déploiement actif.

  • Déploiements sur un seul serveur (deployment.singleServer=true) : étant donné que le mode à serveur unique lie les services internes strictement à l'interface de bouclage (127.0.0.1), les jobs réseau ne peuvent pas les atteindre. Exécutez la migration du schéma localement à l'intérieur du pod en cours d'exécution à l'aide d'un conteneur de débogage éphémère avec l'image de conteneur cible :

    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

    Remplacez les éléments suivants :

    • POD_NAME : nom du pod de serveur, par exemple spanner-a-0.
    • NAMESPACE : espace de noms Kubernetes du déploiement (par exemple, spanner-ns).
    • TARGET_VERSION : version cible vers laquelle effectuer la mise à niveau, par exemple 2026.r4-lts.

Kubernetes autonome

Si vous déployez Spanner Omni sur Kubernetes sans Helm, exécutez un job par lot Kubernetes autonome pour exécuter les migrations de schéma sur le serveur racine actif à l'aide de l'image cible.

  1. Créez un fichier nommé spanner-prepare-upgrade.yaml avec le fichier manifeste du job suivant :

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

    Remplacez les éléments suivants :

    • NAMESPACE : espace de noms Kubernetes du déploiement (par exemple, spanner-ns).
    • TARGET_VERSION : version cible vers laquelle effectuer la mise à niveau, par exemple 2026.r4-lts.
    • ROOT_SERVER_ENDPOINT : point de terminaison d'un pod de serveur racine actif, par exemple spanner-a-0.pod.spanner-ns.

  2. Appliquez le fichier manifeste pour exécuter le job de préparation :

    kubectl apply -f spanner-prepare-upgrade.yaml

Étape 2 : Vérifiez l'état du déploiement actif

Une fois l'étape de préparation terminée, vérifiez que le déploiement a été créé et examinez l'état de ses phases.

  1. Listez les déploiements actifs pour récupérer l'ID de déploiement :

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

    Remplacez DEPLOYMENT_ENDPOINT par le point de terminaison d'un serveur de votre déploiement, par exemple localhost:15000 ou spanner-a-0.pod.spanner-ns:15000.

    Le résultat ressemble à ce qui suit :

    NAME                         STATE          TARGET_VERSION    START_TIME                     END_TIME
rollouts/1788942172101727    IN_PROGRESS    2026.r3-beta      2026-09-09T08:22:52.101727Z    -

  2. Inspectez l'état détaillé de la phase de déploiement :

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

    Remplacez les éléments suivants :

    • ROLLOUT_ID : ID numérique du déploiement, par exemple 1788942172101727.
    • DEPLOYMENT_ENDPOINT : point de terminaison d'un serveur dans votre déploiement.

    Le résultat ressemble à ce qui suit :

    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

    Avant de continuer, vérifiez les états suivants des phases :

    • schema : affiche SUCCEEDED, ce qui indique que les migrations internes du schéma de base de données sont terminées.
    • binary : affiche IN_PROGRESS, ce qui indique que le moteur de déploiement est prêt pour les mises à jour binaires.
    • finalize : affiche PENDING, en attente de la fin de la phase binaire.

Étape 3 : Mettez à jour l'image binaire ou de conteneur

Une fois la phase de schéma réussie, mettez à jour l'image binaire ou de conteneur du serveur en cours d'exécution sur tous les nœuds du déploiement vers la version cible.

Sélectionnez l'onglet correspondant à votre environnement de déploiement :

VM

Dans les déploiements de VM, mettez à jour le binaire spanner_server sur toutes les VM à l'aide d'un redémarrage progressif :

  • Mettez à jour un domaine ou une zone de défaillance à la fois : dans les déploiements multizones, mettez à jour les serveurs d'une zone et vérifiez la stabilité avant de mettre à jour la zone suivante. Cela permet de s'assurer que le groupe de consensus Paxos conserve le quorum.
  • Redémarrage progressif : redémarrez au maximum 5% des serveurs simultanément pour maintenir la disponibilité continue des requêtes.
  • Vérifiez l'état du serveur : assurez-vous que tous les serveurs redémarrés sont opérationnels et ont rejoint le cluster avant de mettre à jour le prochain domaine de défaillance.

Helm

Dans les déploiements Helm, exécutez helm upgrade tout en conservant vos valeurs de configuration existantes en transmettant --reuse-values ou en fournissant un fichier de valeurs :

  • Déploiements multiserveurs (production / haute disponibilité) :

    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 exécute automatiquement la phase 1 à l'aide du hook de pré-mise à niveau, puis lance une mise à jour progressive séquentielle, zone par zone, des StatefulSets (rollout.staggered: true).

  • Déploiements sur un seul serveur (deployment.singleServer=true) :

    Transmettez explicitement --set skipPrepareUpgrade=true pour que Helm ignore le job de hook de pré-mise à niveau, car vous avez déjà terminé la phase 1 en 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

Remplacez les éléments suivants :

  • CHART_VERSION : version cible du chart Helm, par exemple 1.0.0.
  • NAMESPACE : espace de noms Kubernetes du déploiement (par exemple, spanner-ns).
  • TARGET_VERSION : tag de l'image de conteneur cible, par exemple 2026.r4-lts.

Kubernetes autonome

Dans les déploiements Kubernetes personnalisés sans Helm, mettez à jour l'image de conteneur dans vos spécifications StatefulSet ou Deployment sur TARGET_VERSION.

Effectuez une mise à jour progressive dans les domaines de défaillance, en mettant à jour une zone à la fois et en redémarrant au maximum 5% des pods simultanément pour préserver le quorum.

Étape 4 : Vérifier la progression de la phase binaire

Une fois que vous avez mis à jour tous les serveurs ou pods vers la version cible, vérifiez que la phase binaire s'est terminée avec succès.

Vérifiez l'état de la phase de déploiement :

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

Remplacez les éléments suivants :

  • ROLLOUT_ID : ID numérique du déploiement, par exemple 1788942172101727.
  • DEPLOYMENT_ENDPOINT : point de terminaison d'un serveur dans votre déploiement.

Le résultat ressemble à ce qui suit :

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

Vérifiez que l'état de la phase binary passe à SUCCEEDED. L'état global du déploiement reste IN_PROGRESS jusqu'à ce que toutes les phases restantes soient terminées. Une fois que phases/binary passe à SUCCEEDED, le déploiement est prêt à passer aux phases restantes.

Étape 5 : Planifier et exécuter les phases restantes

Une fois la phase binaire terminée et la stabilité de votre déploiement vérifiée, planifiez les phases restantes du déploiement jusqu'à la phase finalize. La phase finalize (dernière phase d'un déploiement) scelle la nouvelle version dans le déploiement. Vous pouvez exécuter cette commande à partir de n'importe quelle machine ayant un accès réseau au service Spanner Omni en spécifiant --deployment-endpoint.

Pour chaque phase restante à l'état PENDING (par exemple, enable_features si elle est présente, suivie de finalize), procédez comme suit :

  1. Planifiez la phase :

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

    Remplacez les éléments suivants :

    • PHASE_NAME : nom de la phase à planifier (par exemple, finalize ou enable_features).
    • ROLLOUT_ID : ID numérique du déploiement, par exemple 1788942172101727.
    • DEPLOYMENT_ENDPOINT : point de terminaison d'un serveur dans votre déploiement.

    Le résultat indique que la phase planifiée est 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. Attendez que la phase réussisse, puis vérifiez son état :

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

    Répétez ces étapes pour chaque phase restante jusqu'à ce que toutes les phases jusqu'à finalize (inclus) soient terminées.

    Une fois la dernière phase (finalize) terminée, toutes les phases et l'état global du déploiement passent à 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. Vérifiez que l'état "Terminé" s'affiche dans la liste des déploiements :

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

    Le résultat confirme que le déploiement est terminé :

    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

Effectuer le rollback d'une mise à niveau

Si vous rencontrez des problèmes lors d'une mise à niveau, la possibilité d'effectuer un rollback dépend de la phase de déploiement actuelle :

  • Phase de schéma : impossible d'effectuer un rollback. Les migrations de schéma de base de données interne appliquées lors de la préparation sont uniquement en avant et ne peuvent pas être annulées. Toutefois, les migrations de schéma sont rétrocompatibles avec la version source, ce qui permet aux anciens binaires de serveur de continuer à fonctionner normalement.
  • Phase binaire : vous pouvez revenir à la version antérieure à tout moment avant le début de la finalisation. Pour en savoir plus, consultez Restaurer l'image binaire ou de conteneur.
  • Phases de déploiement facultatives : pour les phases facultatives qui acceptent le rollback automatique (comme l'activation de fonctionnalités), lancez le rollback à l'aide de Spanner Omni CLI.
  • Phase de finalisation : irréversible. Une fois la finalisation commencée, la version cible est définitivement scellée pour le déploiement et les rollbacks ne sont plus possibles.

Effectuer un rollback du binaire ou de l'image de conteneur

Pour effectuer un rollback de la phase binaire avant le début de la finalisation, effectuez un redémarrage progressif sur tous les serveurs ou pods afin de restaurer la version précédente (source).

VM

Dans les déploiements de VM, effectuez un rollback du binaire spanner_server sur toutes les VM :

  1. Déployez la version antérieure du binaire spanner_server sur vos hôtes.
  2. Redémarrez les serveurs de manière progressive dans les domaines de défaillance, en mettant à jour une zone à la fois et en ne redémarrant pas plus de 5% des serveurs simultanément pour préserver le quorum Paxos.
  3. Vérifiez que tous les serveurs redémarrés sont opérationnels et ont rejoint le cluster avant de passer au domaine de défaillance suivant.

Helm

Dans les déploiements Helm, remplacez le tag de l'image de conteneur par la version précédente :

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

Remplacez les éléments suivants :

  • CHART_VERSION : version du graphique Helm, par exemple 1.0.0.
  • NAMESPACE : espace de noms Kubernetes du déploiement (par exemple, spanner-ns).
  • SOURCE_VERSION : tag de l'image de conteneur antérieure à laquelle revenir, par exemple 2026.r2-beta.3.

Kubernetes autonome

Dans les déploiements Kubernetes personnalisés sans Helm, remplacez l'image de conteneur dans vos spécifications StatefulSet ou Deployment par SOURCE_VERSION.

Effectuez une mise à jour progressive dans les domaines de défaillance, en mettant à jour une zone à la fois et en redémarrant au maximum 5% des pods simultanément pour préserver le quorum.

Effectuer un rollback des phases de déploiement facultatives

Pour les phases de déploiement facultatives qui acceptent le rollback (comme les phases d'activation de fonctionnalités), lancez le rollback en exécutant la commande rollouts rollback :

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

Remplacez les éléments suivants :

  • ROLLOUT_ID : ID numérique du déploiement.
  • DEPLOYMENT_ENDPOINT : point de terminaison d'un serveur dans votre déploiement.

Étapes suivantes