ワーカーをデプロイして管理する

このドキュメントでは、仮想マシン（VM）と Kubernetes で Spanner Omni ワーカーをデプロイ、スケーリング、廃止、モニタリングする方法について説明します。

ワーカーは、Spanner Omni サーバーからバックグラウンド オペレーションとリソース集約型オペレーションをオフロードするように設計された、専用のステートレス コンピューティング ノードです。ワーカーはユーザーデータをホストしたり、リーダー選出、トランザクション、その他のコア データベース アクティビティに参加したりしません。サーバーとは異なり、ワーカーは特定のゾーンに関連付けられていません。代わりに、ワーカーはロケーションに登録し、そのロケーション内の任意のゾーンのタスクを実行できます。ワーカーはステートレスで、データの移動や再調整を必要としないため、ワーカーの追加と削除は軽量で瞬時に行われます。

近似最近傍（ANN）検索クエリ用に大規模なテーブル（100 万行以上）にベクトル インデックスを構築するには、ワーカーが必要です。詳細については、Spanner Omni ベクトル検索の概要をご覧ください。

ワーカーは Spanner Omni の Commercial エディションでのみ使用できます。Developer エディションではワーカーはサポートされていません。ワーカーのコンピューティングは、デプロイのサーバーと同じレート（vCPU あたり）で課金されます。詳細については、Spanner Omni エディションの概要をご覧ください。

始める前に

既存の Spanner Omni デプロイにワーカーを追加する前に、環境が次の要件を満たしていることを確認してください。

  • Spanner Omni バイナリをダウンロードして設定します。

  • 既存のデプロイ: 商用エディションで構成された、READY 状態の実行中の Spanner Omni デプロイ（単一サーバーのデプロイではない）があることを確認します。Developer エディションはワーカーをサポートしていません。ワーカーのコンピューティングは、デプロイのサーバーと同じレートで課金されます。詳細については、Spanner Omni エディションの概要をご覧ください。次の情報をご用意ください。

    • デプロイ構成で定義されているターゲット ロケーション名（例: us-central1）。
    • クラスタ検出用のデプロイ エンドポイント（HOST:PORT、my-spanner-deployment:15003 など）またはルートサーバー アドレスのリスト（ROOT_HOST_1:PORT、ROOT_HOST_2:PORT、root-server-1:15000、root-server-2:15000 など）。

  • システム リソースとハードウェア リソース: ワーカーに割り当てるコンピューティング リソースが、必要なオペレーションを許容可能な時間内に実行するのに十分であることを確認します。

  • vSphere 構成: vSphere 仮想化プラットフォームで Spanner Omni を実行する場合は、タイムスタンプ カウンタ（TSC）の仮想化を無効にします。仮想マシンの .vmx 構成ファイルに monitor_control.virtual_rdtsc = FALSE を追加します。

  • ネットワークとファイアウォールの構成: ワーカーは、標準のサーバー通信ポート（15000～15025）に加えてポート 15027 を使用します。ネットワーク構成でポート 15000～15027 の通信が許可されていることを確認してください。

VM にワーカーをデプロイする

仮想マシン（VM）にワーカーをデプロイするには、デプロイ エンドポイントまたはルートサーバーのリストを使用してワーカー プロセスを開始します。

オプション A: デプロイ エンドポイントの使用を開始する

デプロイ エンドポイントを使用してワーカーを開始するには、spanner workers start コマンドを実行します。

spanner workers start \
  --location=LOCATION_NAME \
  --address=WORKER_HOSTNAME:WORKER_PORT_BASE \
  --deployment=DEPLOYMENT_ENDPOINT \
  --base-dir=BASE_DIR \
  --license-file-path=LICENSE_FILE_PATH

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

  • LOCATION_NAME: ターゲット ロケーション名（例: us-central1）。
  • WORKER_HOSTNAME: 解決可能なワーカー VM のホスト名または IP アドレス。
  • WORKER_PORT_BASE: ワーカーが起動するベースポート（15000、20000 など）。
  • DEPLOYMENT_ENDPOINT: デプロイ エンドポイントのホストとポート（例: my-spanner-deployment:15003）。
  • BASE_DIR: ワーカーのデータとログのベース ディレクトリ（例: /var/spanner）。
  • LICENSE_FILE_PATH: Spanner Omni ライセンス ファイルのパス。

オプション B: ルートサーバーのリストの使用を開始する

ルートサーバーのリストを使用してワーカーを起動するには、spanner workers start コマンドを実行します。

spanner workers start \
  --location=LOCATION_NAME \
  --address=WORKER_HOSTNAME:WORKER_PORT_BASE \
  --join-servers=ROOT_SERVER_1_HOST:ROOT_SERVER_PORT_BASE,\
ROOT_SERVER_2_HOST:ROOT_SERVER_PORT_BASE \
  --base-dir=BASE_DIR \
  --license-file-path=LICENSE_FILE_PATH

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

  • LOCATION_NAME: ターゲット ロケーション名（例: us-central1）。
  • WORKER_HOSTNAME: 解決可能なワーカー VM のホスト名または IP アドレス。
  • WORKER_PORT_BASE: ワーカーが起動するベースポート（15000、20000 など）。
  • ROOT_SERVER_1_HOST、ROOT_SERVER_2_HOST: デプロイ内のルートサーバーのホスト名または IP アドレス。
  • ROOT_SERVER_PORT_BASE: ルートサーバーのベースポート（例: 15000）。
  • BASE_DIR: ワーカーのデータとログのベース ディレクトリ（例: /var/spanner）。
  • LICENSE_FILE_PATH: Spanner Omni ライセンス ファイルのパス。

暗号化を構成する

Spanner Omni デプロイで TLS または mTLS 暗号化を使用する場合は、各ワーカーの暗号化を構成します。

  1. まだワーカーのホスト名が含まれていない場合は、ワーカーのホスト名を含めるようにサーバー証明書を更新します。
  2. ca.crt、server.crt、server.key を含む証明書ディレクトリをワーカー VM にコピーします。

  3. spanner workers start を実行するときに --certificate-directory フラグを追加します。

    spanner workers start \
  --location=LOCATION_NAME \
  --address=WORKER_HOSTNAME:WORKER_PORT_BASE \
  --deployment=DEPLOYMENT_ENDPOINT \
  --base-dir=BASE_DIR \
  --certificate-directory=CERTIFICATE_DIRECTORY \
  --license-file-path=LICENSE_FILE_PATH

    CERTIFICATE_DIRECTORY は、ca.crt、server.crt、server.key を含むディレクトリに置き換えます。

証明書と安全なデプロイの構成の詳細については、VM に安全なデプロイを作成するをご覧ください。

Kubernetes にワーカーをデプロイする

Google Kubernetes Engine（GKE）や Amazon Elastic Kubernetes Service（Amazon EKS）などの Kubernetes 環境では、既存の Spanner Omni Helm リリースのクラスタと同じ Namespace にワーカーをデプロイします。Helm チャートは、ヘッドレス Service を使用してワーカーを Kubernetes StatefulSet としてデプロイします。これにより、各ワーカー Pod に安定したネットワーク ID と PersistentVolumeClaims（PVC）が提供され、ルートサーバーが各ワーカーと確実に通信できるようになります。

デフォルトでは、Helm チャートは spanner-role=workers というラベルが付いたノードでのみワーカー Pod をスケジュールし、spanner-role=workers:NoSchedule テイントを許容し、ノードごとに最大 1 つのワーカー Pod を実行します。ワーカーを有効にする前に、このラベルと taint を持つノードプールを追加します。このノードプールには、workers.replicas と同じ数のノードが必要です。各ノードには、workers.resources.cpu と workers.resources.memory で設定された 1 つのワーカー Pod に十分な割り当て可能な CPU とメモリが必要です。Kubernetes は各ノードの容量の一部をシステム コンポーネント用に予約するため、これらの値よりも大きいノードを選択します。別のラベルを使用するには、workers.nodeLabelKey と workers.nodeLabelValue を設定します。ラベルの要件を削除するには、workers.nodeLabelKey="" を設定します。デフォルトのスケジューリング ルールを置き換えるには、workers.affinity を設定します。

既存のデプロイでワーカーを有効にするには、helm upgrade コマンドを実行します。

helm upgrade spanner-omni HELM_CHART_PATH \
  --reuse-values \
  --set workers.enabled=true \
  --namespace NAMESPACE

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

  • HELM_CHART_PATH: Spanner Omni Helm チャートのパス。
  • NAMESPACE: Spanner Omni クラスタがデプロイされている Kubernetes Namespace（例: spanner-ns）。

ワーカーが十分な割り当て可能な CPU とメモリを持つ任意のノードで実行できるようにするには、workers.nodeLabelKey を空の文字列に設定します。これにより、ノードラベルの要件と taint の許容の両方が削除されます。

helm upgrade spanner-omni HELM_CHART_PATH \
  --reuse-values \
  --set workers.enabled=true \
  --set workers.nodeLabelKey="" \
  --namespace NAMESPACE

オプションの構成設定には、次のものがあります。

  • --set workers.replicas=WORKER_REPLICAS: デプロイするワーカー レプリカの数。デフォルトは 1 です。

  • --set workers.resources.cpu=CPU_CORES: 各ワーカーの CPU の上限とリクエスト。デフォルトは 6 です。

  • --set workers.resources.memory=MEMORY_LIMIT: 各ワーカーのメモリの上限とリクエスト。デフォルトは 24Gi です。

  • --set workers.storage.size=STORAGE_SIZE: 各ワーカーのストレージ容量。デフォルトは 20Gi です。

  • --set workers.storage.storageClassName=STORAGE_CLASS: ワーカー ストレージに使用するストレージ クラス（GKE の hyperdisk-balanced-rwo や Amazon EKS の aws-gp3 など）。デフォルトは空の文字列で、クラスタのデフォルトのストレージ クラスが継承されます。

  • --set workers.port=WORKER_PORT: ワーカーがリッスンするネットワーク ポート。デフォルトは deployment.basePort（15000）です。

  • --set workers.joinServers={ROOT_HOST_1:PORT,ROOT_HOST_2:PORT}: 参加するルートサーバー アドレスの明示的なカンマ区切りのリスト。デフォルトは空のリスト（[]）で、デプロイ トポロジからすべてのアクティブなルートサーバーを検出します。

  • --set workers.nodeLabelKey=NODE_LABEL_KEY: ノード アフィニティと toleration に使用される Kubernetes ノードラベルキー。ワーカーを専用ノードプールに分離するために使用されます。デフォルトは spanner-role です。ノード アフィニティと容認を無効にするには、空の文字列 "" に設定します。

  • --set workers.nodeLabelValue=NODE_LABEL_VALUE: ノード アフィニティと toleration に使用される Kubernetes ノードラベル値。デフォルトは workers です。

  • --set workers.pdbMaxUnavailable=MAX_UNAVAILABLE: PodDisruptionBudget での自発的な中断中に使用不可になるワーカー Pod の最大数。デフォルトは 1 です。

  • workers.affinity: ワーカー Pod のカスタム Kubernetes アフィニティ ルール。指定しない場合は、デフォルトのノード アフィニティ（workers.nodeLabelKey と workers.nodeLabelValue を使用）と、ホスト名（kubernetes.io/hostname）間の Pod アンチ アフィニティが適用されます。これはネストされたオブジェクトであるため、-f フラグを使用して values.yaml ファイルで指定します。

ワーカーのデプロイを確認する

ワーカー Pod が実行されていて、準備ができていることを確認するには、次のコマンドを実行します。

kubectl get pods --namespace NAMESPACE -l app.kubernetes.io/component=spanner-worker

ワーカーのスケールとデコミッション

ワーカーはユーザーデータを保存せず、データベース コンセンサスにも参加しません。ワーカーのスケーリングとデコミッションは瞬時に行われます。ベクトル インデックスの作成を開始する前または後にワーカーを起動し、インデックスの作成が完了したらすぐにワーカーを廃止できます。

ワーカーのスケーリングを自動化する

ワーカーの作成とスケーリングを自動化するには、spanner_box_compute_heavy_workers_required 指標をモニタリングします。指標値が 0 より大きい場合、デプロイでは、大きなテーブルでのベクトル インデックスの作成など、保留中のバックグラウンド オペレーションを完了するために 1 つ以上のワーカーが必要です。指標値が 0 に戻ると、保留中のオペレーションはすべて完了し、ワーカーを廃止できます。

VM ワーカーを廃止する

VM で実行されているワーカー プロセスを停止するには、ワーカー プロセスを実行しているターミナルで Ctrl+C を押すか、プロセス ID（PID）を使用してプロセスを停止します。

kill -TERM PID

PID は、spanner workers プロセスのプロセス ID に置き換えます。または、ワーカー VM をシャットダウンします。

Kubernetes ワーカーを廃止する

Kubernetes でワーカーを廃止するには、Helm リリースでワーカーを無効にするか、kubectl を使用してワーカー レプリカを直接スケールダウンします。

  • ワーカーを無効にする: デプロイの残りの部分を保持したまま、クラスタからワーカー StatefulSet とサービスを削除するには、workers.enabled=false を指定して helm upgrade コマンドを実行します。

    helm upgrade spanner-omni HELM_CHART_PATH \
  --reuse-values \
  --set workers.enabled=false \
  --namespace NAMESPACE

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

    • HELM_CHART_PATH: Spanner Omni Helm チャートのパス。
    • NAMESPACE: Spanner Omni クラスタがデプロイされている Kubernetes Namespace（例: spanner-ns）。

  • ワーカー レプリカをスケールダウンする: クラスタでワーカー構成をアクティブな状態に保ちながら、ワーカー Pod をゼロ レプリカにスケールダウンするには、kubectl scale コマンドを実行します。

    kubectl scale statefulset spanner-worker \
  --replicas=0 \
  --namespace NAMESPACE

    NAMESPACE は、Spanner Omni クラスタがデプロイされている Kubernetes Namespace（spanner-ns など）に置き換えます。

ワーカーのモニタリングとトラブルシューティング

デプロイでモニタリングが有効になっている場合は、Prometheus または Grafana ダッシュボードを使用してワーカーをモニタリングできます。ワーカーは、Spanner Omni サーバーと同様の指標を公開します。Grafana ダッシュボードには、各ワーカーのリソース使用率をモニタリングできる Worker Insights ダッシュボードが含まれています。

ワーカーは、--base-dir で指定されたベース ディレクトリ内の logs サブディレクトリにログファイルを書き込みます。

BASE_DIR/logs

spanner admin diagnostics create コマンドは、ワーカーからログや診断情報を収集しません。ワーカーログを調べるには、ワーカー マシンまたは Pod の BASE_DIR/logs でファイルを直接表示するか、Kubernetes ワーカー Pod の場合は kubectl logs を実行します。

ダッシュボードのモニタリングと構成の詳細については、モニタリングの概要と Grafana ダッシュボードを使用したモニタリングをご覧ください。

ベクトル インデックスの作成が進まない

大きなテーブルにベクトル インデックスを作成し、インデックス作成が進行せずに保留中のままになっている場合は、少なくとも 1 つのワーカーが実行され、デプロイに接続されていることを確認します。

Spanner Omni では、ワーカーがアクティブでない場合でもベクトル インデックスを作成できるため、必要な場合にのみワーカーをデプロイできます。アクティブなワーカーがない場合、インデックス作成オペレーションはワーカーがデプロイされるまで無期限に一時停止します。ワーカーが起動してデプロイに登録すると、インデックスの作成が自動的に再開されます。