Google は AI 技術を使用して、コンテンツをご希望の言語に翻訳しています。AI 翻訳には誤りが含まれる場合があります。

Spanner Omni デプロイをアップグレードする

このドキュメントでは、Spanner Omni デプロイを以前のバージョンから新しいバージョンにアップグレードする方法について説明します。

Spanner Omni は、非同期の段階的ロールアウト状態マシンを使用して、サービスの中断のない安全なアップグレードを実現します。段階的にアップグレードすると、次のことが可能になります。

データベーススキーマの更新を適用する。
ローリング再起動中にバイナリの互換性を確認します。
最終処理前にエラーが検出された場合は、以前のバージョンにロールバックします。

アップグレードワークフロー

Spanner Omni のアップグレードプロセスは、複数の連続したフェーズで構成されます。

スキーマフェーズ: ターゲットバイナリバージョンを使用して内部データベーススキーマの移行を実行し、デプロイを準備します。スキーマの移行はロールバックできませんが、以前のバイナリバージョンとの下位互換性があります。
バイナリフェーズ: ローリング再起動を使用して、デプロイ内のすべてのサーバーでサーバーバイナリまたはコンテナイメージを更新します。エラーが検出された場合は、ファイナライズが開始される前の任意の時点で、バイナリまたはコンテナイメージを以前のバージョンにロールバックできます。
機能の有効化フェーズ: バージョン互換性のある機能を有効にします。すべてのサーバーでバイナリをアップグレードした後に開始されます。アップグレードにバージョン互換の機能が含まれていない場合、このフェーズは適用されないことがあります。また、機能が相互に依存している場合は、複数回のラウンドが必要になることがあります。ロールバックをサポートするオプションのフェーズでは、Spanner Omni CLI を使用してロールバックを開始できます。
ファイナライズフェーズ: ロールアウトを完了し、ターゲットバージョンを確定します。ファイナライズフェーズが開始されると、ロールバックはできません。

始める前に

Spanner Omni デプロイをアップグレードする前に、次の前提条件を満たしていることを確認してください。

Spanner Omni のデプロイが実行されている。詳細については、Kubernetes にデプロイを作成するまたは VM にデプロイを作成するをご覧ください。
Spanner Omni CLI をダウンロードしてインストールした。
CLI コマンドを実行するマシンからすべての Spanner Omni 内部ポート（TCP 15000 ～ 15027）へのネットワークアクセス権があるか、デプロイエンドポイントへのネットワークアクセス権がある。
デプロイで Transport Layer Security（TLS）または相互 TLS（mTLS）暗号化を使用している場合は、BASE_DIR/tls の下のベースディレクトリに有効な証明書があるか、クラスタにマウントされていることを確認します。
ターゲットリリースを特定しました。
- VM デプロイの場合: ターゲットリリースパッケージ spanner-omni-server-TARGET_VERSION.tar.gz をダウンロードします。
- Helm と Kubernetes のデプロイの場合: Artifact Registry でターゲットコンテナイメージ（us-docker.pkg.dev/spanner-omni/images/spanner-omni:TARGET_VERSION など）を特定します。

ステップ 1: スキーマのアップグレードを準備する

アップグレードを開始するには、ターゲットバージョンのロールアウトを準備します。このフェーズでは、既存のサーバーがトラフィックの処理を継続している間に、Spanner Omni が内部データベーススキーマの移行を実行します。

デプロイ環境のタブを選択します。

VM

VM デプロイでは、ターゲットリリースパッケージをダウンロードして解凍し、解凍した Spanner Omni CLI を使用してロールアウトの準備を開始します。

すべての Spanner Omni 内部ポート（TCP 15000 ～ 15027）にネットワークアクセスできるデプロイ内のサーバーにログインします。
ターゲットリリースパッケージをダウンロードして解凍します。
```
tar -xzf spanner-omni-server-TARGET_VERSION.tar.gz -C EXTRACT_DIR
```
次のように置き換えます。
- TARGET_VERSION: アップグレード先のターゲットバージョン（2026.r4-lts など）。
- EXTRACT_DIR: リリースパッケージを抽出するディレクトリ（例: /tmp/target_spanner/）。
抽出した CLI から rollouts prepare コマンドを実行して、ロールアウトの準備を開始します。
```
EXTRACT_DIR/bin/spanner deployment rollouts prepare \
  --target-server-binary=EXTRACT_DIR/bin/spanner_server \
  --root-server=ROOT_SERVERS \
  --base-dir=BASE_DIR
```
次のように置き換えます。
- EXTRACT_DIR: ターゲットの bin/spanner CLI と bin/spanner_server バイナリを含む抽出ディレクトリ。
- ROOT_SERVERS: 1 つのルートサーバーエンドポイント、または複数のルートサーバーのカンマ区切りのリスト（例: localhost:15000、server1:15000,server2:15000,server3:15000）。
- BASE_DIR: Spanner Omni のベースディレクトリ（例: /spanner）。
- デプロイで TLS または mTLS 暗号化を使用する場合は、有効な証明書を指す --ca-certificate-file=CA_CERT_FILE と --client-certificate-directory=CERT_DIR を追加します。

Helm

Helm デプロイでは、スキーマの準備はマルチサーバーデプロイとシングルサーバーデプロイのどちらを実行するかによって異なります。

マルチサーバーデプロイ（高可用性 / 本番環境）: Helm がスキーマの準備を自動的に処理します。ステップ 3: バイナリまたはコンテナイメージを更新するで helm upgrade を実行すると、Helm チャートは spanner-prepare-for-upgrade アップグレード前フックジョブをトリガーして、StatefulSet を更新する前にスキーマ移行を実行します。ステップ 2: アクティブなロールアウトの状態を確認するに直接進みます。
単一サーバーのデプロイ（deployment.singleServer=true）: 単一サーバーモードでは、内部サービスがループバックインターフェース（127.0.0.1）に厳密にバインドされるため、ネットワークジョブはこれらのサービスにアクセスできません。ターゲットコンテナイメージを含むエフェメラルデバッグコンテナを使用して、実行中の Pod 内でスキーマ移行をローカルで実行します。
```
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
```
次のように置き換えます。
- POD_NAME: サーバー Pod の名前（例: spanner-a-0）。
- NAMESPACE: デプロイの Kubernetes Namespace（例: spanner-ns）。
- TARGET_VERSION: アップグレード先のターゲットバージョン（2026.r4-lts など）。

スタンドアロン Kubernetes

Helm を使用せずに Kubernetes に Spanner Omni をデプロイする場合は、スタンドアロンの Kubernetes バッチジョブを実行して、ターゲットイメージを使用してアクティブなルートサーバーに対してスキーマ移行を実行します。

次のジョブマニフェストを含む spanner-prepare-upgrade.yaml という名前のファイルを作成します。

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

次のように置き換えます。

NAMESPACE: デプロイの Kubernetes Namespace（例: spanner-ns）。
TARGET_VERSION: アップグレード先のターゲットバージョン（2026.r4-lts など）。
ROOT_SERVER_ENDPOINT: アクティブなルートサーバー Pod のエンドポイント（例: spanner-a-0.pod.spanner-ns）。

マニフェストを適用して準備ジョブを実行します。
```
kubectl apply -f spanner-prepare-upgrade.yaml
```

ステップ 2: アクティブなロールアウトの状態を確認する

準備手順が完了したら、ロールアウトが作成されたことを確認し、フェーズのステータスを調べます。

アクティブなロールアウトを一覧表示して、ロールアウト ID を取得します。
```
spanner deployment rollouts list \
  --deployment-endpoint=DEPLOYMENT_ENDPOINT
```
DEPLOYMENT_ENDPOINT は、デプロイ内のサーバーのエンドポイント（localhost:15000、spanner-a-0.pod.spanner-ns:15000 など）に置き換えます。

出力は次のようになります。
```
NAME                         STATE          TARGET_VERSION    START_TIME                     END_TIME
rollouts/1788942172101727    IN_PROGRESS    2026.r3-beta      2026-09-09T08:22:52.101727Z    -
```
ロールアウトフェーズの詳細なステータスを確認します。
```
spanner deployment rollouts describe ROLLOUT_ID \
  --deployment-endpoint=DEPLOYMENT_ENDPOINT
```
次のように置き換えます。
- ROLLOUT_ID: 数値のロールアウト ID（例: 1788942172101727）。
- DEPLOYMENT_ENDPOINT: デプロイ内のサーバーのエンドポイント。
出力は次のようになります。
```
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
```
続行する前に、次のフェーズのステータスを確認します。
- schema: 内部データベーススキーマの移行が完了したことを示す SUCCEEDED が表示されます。
- binary: IN_PROGRESS が表示されます。これは、ロールアウトエンジンがバイナリアップデートの準備ができていることを示します。
- finalize: PENDING を示します。バイナリフェーズの完了を待機しています。

ステップ 3: バイナリまたはコンテナイメージを更新する

スキーマフェーズが成功したら、デプロイ内のすべてのノードで実行中のサーバーバイナリまたはコンテナイメージをターゲットバージョンに更新します。

デプロイ環境のタブを選択します。

VM

VM デプロイでは、ローリング再起動を使用して、すべての VM で spanner_server バイナリを更新します。

一度に 1 つの障害発生ドメインまたはゾーンを更新する: マルチゾーンデプロイでは、1 つのゾーンのサーバーを更新し、安定性を確認してから次のゾーンを更新します。これにより、Paxos コンセンサスグループがクォーラムを保持します。
段階的に再起動する: 継続的クエリの可用性を維持するために、同時に再起動するサーバーの割合を 5% 以下にします。
サーバーの健全性を確認する: 次の障害発生ドメインを更新する前に、再起動されたすべてのサーバーが正常で、クラスタに再参加していることを確認します。

Helm

Helm デプロイでは、--reuse-values を渡すか、値ファイルを提供して、既存の構成値を保持しながら helm upgrade を実行します。

マルチサーバーデプロイ（本番環境 / 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 は、アップグレード前のフックを使用してフェーズ 1 を自動的に実行し、StatefulSet（rollout.staggered: true）のゾーンごとのローリングアップデートを順番に開始します。
単一サーバーのデプロイ（deployment.singleServer=true）:

フェーズ 1 はすでにローカルで完了しているため、Helm がアップグレード前のフックジョブをスキップするように、--set skipPrepareUpgrade=true を明示的に渡します。
```
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
```

次のように置き換えます。

CHART_VERSION: ターゲット Helm チャートのバージョン（例: 1.0.0）。
NAMESPACE: デプロイの Kubernetes Namespace（例: spanner-ns）。
TARGET_VERSION: ターゲットコンテナイメージのタグ（2026.r4-lts など）。

スタンドアロン Kubernetes

Helm を使用しないカスタム Kubernetes デプロイでは、StatefulSet または Deployment 仕様のコンテナイメージを TARGET_VERSION に更新します。

障害ドメイン全体でローリングアップデートを実行し、一度に 1 つのゾーンを更新して、同時に再起動する Pod の数を 5% 以下に抑えてクォーラムを維持します。

ステップ 4: バイナリフェーズの進行状況を確認する

すべてのサーバーまたは Pod をターゲットバージョンに更新したら、バイナリフェーズが正常に完了したことを確認します。

ロールアウトフェーズのステータスを確認します。

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

次のように置き換えます。

ROLLOUT_ID: 数値のロールアウト ID（例: 1788942172101727）。
DEPLOYMENT_ENDPOINT: デプロイ内のサーバーのエンドポイント。

出力は次のようになります。

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

binary フェーズのステータスが SUCCEEDED に変わったことを確認します。残りのすべてのフェーズが完了するまで、全体的なロールアウト状態は IN_PROGRESS のままです。phases/binary が SUCCEEDED に移行すると、デプロイは残りのフェーズに進む準備が整います。

ステップ 5: 残りのフェーズのスケジュールを設定して実行する

バイナリフェーズが成功し、デプロイが安定していることを確認したら、finalize フェーズまでのロールアウトの残りのフェーズをスケジュールします。finalize フェーズ（ロールアウトの最後のフェーズ）では、デプロイ全体で新しいバージョンが確定されます。このコマンドは、--deployment-endpoint を指定することで、Spanner Omni サービスにネットワークアクセスできる任意のマシンから実行できます。

PENDING 状態の残りのフェーズ（enable_features が存在する場合は、次に finalize など）ごとに、次の手順を完了します。

フェーズのスケジュールを設定します。

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

次のように置き換えます。

PHASE_NAME: スケジュールするフェーズの名前（finalize、enable_features など）。
ROLLOUT_ID: 数値のロールアウト ID（例: 1788942172101727）。
DEPLOYMENT_ENDPOINT: デプロイ内のサーバーのエンドポイント。

出力には、スケジュールされたフェーズが 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

フェーズが成功するまで待って、ステータスを確認します。

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

finalize までのすべてのフェーズが完了するまで、残りのフェーズごとにこの手順を繰り返します。

最終フェーズ（finalize）が完了すると、すべてのフェーズと全体的なロールアウト状態が 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

ロールアウトリストで完了ステータスを確認します。

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

出力で、ロールアウトが完了したことを確認します。

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

アップグレードをロールバックする

アップグレード中に問題が発生した場合、アップグレードをロールバックできるかどうかは、現在のロールアウトフェーズによって異なります。

スキーマフェーズ: ロールバックできません。準備中に適用される内部データベーススキーマの移行は前方のみであり、元に戻すことはできません。ただし、スキーマ移行はソースバージョンと下位互換性があるため、以前のサーバーバイナリは引き続き正常に動作します。
バイナリフェーズ: 最終処理が開始される前であれば、いつでも以前のバージョンにロールバックできます。詳細については、バイナリまたはコンテナイメージをロールバックするをご覧ください。
省略可能なロールアウトフェーズ: 自動ロールバックをサポートする省略可能なフェーズ（機能の有効化など）では、Spanner Omni CLI を使用してロールバックを開始します。
最終フェーズ: ロールバックできません。ファイナライズが開始されると、ターゲットバージョンはデプロイ全体で完全に封印され、ロールバックはできなくなります。

バイナリまたはコンテナイメージをロールバックする

ファイナライズが開始される前にバイナリフェーズをロールバックするには、すべてのサーバーまたは Pod でローリング再起動を実行して、以前の（ソース）バージョンを復元します。

VM

VM デプロイでは、すべての VM で spanner_server バイナリをロールバックします。

以前の spanner_server バイナリバージョンをホストにデプロイします。
障害ドメイン全体でサーバーを段階的に再起動し、一度に 1 つのゾーンを更新して、同時に再起動するサーバーの数を 5% 以下に抑え、Paxos クォーラムを維持します。
次の障害発生ドメインに進む前に、再起動されたすべてのサーバーが正常で、クラスタに再参加していることを確認します。

Helm

Helm デプロイで、コンテナイメージタグを以前のバージョンに戻します。

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

次のように置き換えます。

CHART_VERSION: Helm チャートのバージョン（例: 1.0.0）。
NAMESPACE: デプロイの Kubernetes Namespace（例: spanner-ns）。
SOURCE_VERSION: 以前のコンテナイメージタグ（2026.r2-beta.3 など）。

スタンドアロン Kubernetes

Helm を使用しないカスタム Kubernetes デプロイでは、StatefulSet または Deployment 仕様のコンテナイメージを SOURCE_VERSION に戻します。

オプションのロールアウトフェーズをロールバックする

ロールバックをサポートするオプションのロールアウトフェーズ（機能の有効化フェーズなど）では、rollouts rollback コマンドを実行してロールバックを開始します。

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

次のように置き換えます。

ROLLOUT_ID: ロールアウトの数値 ID。
DEPLOYMENT_ENDPOINT: デプロイ内のサーバーのエンドポイント。

次のステップ

デプロイを維持する方法を確認する。
Kubernetes Deployment をスケーリングする方法または VM Deployment をスケーリングする方法を確認する。
モニタリングの概要について学習する。

Spanner Omni デプロイをアップグレードする コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

アップグレード ワークフロー

始める前に

ステップ 1: スキーマのアップグレードを準備する

VM

Helm

スタンドアロン Kubernetes

ステップ 2: アクティブなロールアウトの状態を確認する

ステップ 3: バイナリまたはコンテナ イメージを更新する

VM

Helm

スタンドアロン Kubernetes

ステップ 4: バイナリ フェーズの進行状況を確認する

ステップ 5: 残りのフェーズのスケジュールを設定して実行する

アップグレードをロールバックする

バイナリまたはコンテナ イメージをロールバックする

VM

Helm

スタンドアロン Kubernetes

オプションのロールアウト フェーズをロールバックする

次のステップ

Spanner Omni デプロイをアップグレードする

アップグレードワークフロー

ステップ 3: バイナリまたはコンテナイメージを更新する

ステップ 4: バイナリフェーズの進行状況を確認する

バイナリまたはコンテナイメージをロールバックする

オプションのロールアウトフェーズをロールバックする