デュアル書き込みプロキシを使用した Cassandra から Bigtable への移行

1. はじめに

Bigtable は、大規模な分析ワークロードや運用ワークロード用に設計された、フルマネージドで高性能な NoSQL データベース サービスです。Apache Cassandra などの既存のデータベースから Bigtable に移行する場合、多くの場合、ダウンタイムとアプリケーションへの影響を最小限に抑える慎重な計画が必要です。

この Codelab では、次のプロキシ ツールを組み合わせて Cassandra から Bigtable に移行する方法を示します。

  1. Cassandra-Bigtable プロキシ: Cassandra クライアントとツール（cqlsh やドライバなど）が、クエリを変換して Cassandra クエリ言語（CQL）プロトコルを使用して Bigtable とやり取りできるようにします。
  2. Datastax Zero Downtime Migration（ZDM）プロキシ: アプリケーションとデータベース サービス（Cassandra-Bigtable プロキシを介した送信元 Cassandra とターゲット Bigtable）の間に配置されるオープンソース プロキシ。デュアル書き込みをオーケストレートし、トラフィック ルーティングを管理することで、アプリケーションの変更とダウンタイムを最小限に抑えて移行できます。
  3. Cassandra Data Migrator（CDM）: ソースの Cassandra クラスタからターゲットの Bigtable インスタンスに過去のデータを一括で移行するために使用されるオープンソース ツール。

学習内容

  • Compute Engine で基本的な Cassandra クラスタをセットアップする方法。
  • Bigtable インスタンスを作成する方法。
  • Cassandra スキーマを Bigtable にマッピングするように Cassandra-Bigtable プロキシをデプロイして構成する方法。
  • デュアル書き込み用に Datastax ZDM Proxy をデプロイして構成する方法。
  • Cassandra Data Migrator ツールを使用して既存のデータを一括移行する方法。
  • プロキシベースの Cassandra から Bigtable への移行の全体的なワークフロー。

必要なもの

  • 課金を有効にした Google Cloud プロジェクト。新規ユーザーは無料トライアルをご利用いただけます。
  • プロジェクト、Compute Engine、VPC ネットワーク、ファイアウォール ルールなどの Google Cloud のコンセプトに精通していること。Linux のコマンドライン ツールに基本的な知識があること。
  • gcloud CLI がインストールされて構成されているマシンにアクセスするか、Google Cloud Shell を使用します。

この Codelab では、ネットワークを簡素化するために、主に同じ VPC ネットワークとリージョン内の Compute Engine 上の仮想マシン（VM）を使用します。内部 IP アドレスを使用することをおすすめします。

2.環境を設定する

1. Google Cloud プロジェクトを選択または作成する

Google Cloud コンソールに移動し、既存のプロジェクトを選択するか、新しいプロジェクトを作成します。プロジェクト ID をメモします。

2. 必要な API の有効化

プロジェクトで Compute Engine API と Bigtable API が有効になっていることを確認します。

gcloud services enable compute.googleapis.com bigtable.googleapis.com bigtableadmin.googleapis.com --project=<your-project-id>

は、実際のプロジェクト ID に置き換えます。

3. リージョンとゾーンを選択する

リソースのリージョンとゾーンを選択します。例として us-central1 と us-central1-c を使用します。便宜上、これらを環境変数として定義します。

export PROJECT_ID="<your-project-id>"
export REGION="us-central1"
export ZONE="us-central1-c"

gcloud config set project $PROJECT_ID
gcloud config set compute/region $REGION
gcloud config set compute/zone $ZONE

4. ファイアウォール ルールの構成

デフォルトの VPC ネットワーク内の VM 間の通信を、次のポートで許可する必要があります。

  • Cassandra/プロキシの CQL ポート: 9042
  • ZDM プロキシのヘルスチェック ポート: 14001
  • SSH: 22

これらのポートで内部トラフィックを許可するファイアウォール ルールを作成します。タグ cassandra-migration を使用して、このルールを関連する VM に簡単に適用します。

gcloud compute firewall-rules create allow-migration-internal \
--network=default \
--action=ALLOW \
--rules=tcp:22,tcp:9042,tcp:14001 \
--source-ranges=10.128.0.0/9 # Adjust if using a custom VPC/IP range \
--target-tags=cassandra-migration

3. Cassandra クラスタをデプロイする（Origin）

この Codelab では、Compute Engine に単純な単一ノード Cassandra クラスタを設定します。実際のシナリオでは、既存のクラスタに接続します。

1. Cassandra 用の GCE VM を作成する

gcloud compute instances create cassandra-origin \
--machine-type=e2-medium \
--image-family=ubuntu-2004-lts \
--image-project=ubuntu-os-cloud \
--tags=cassandra-migration \
--boot-disk-size=20GB

2. Cassandra をインストールする

# Install Java (Cassandra dependency)
sudo apt-get update
sudo apt-get install -y openjdk-11-jre-headless

# Add Cassandra repository
echo "deb [https://debian.cassandra.apache.org](https://debian.cassandra.apache.org) 41x main" | sudo tee -a /etc/apt/sources.list.d/cassandra.sources.list
curl [https://downloads.apache.org/cassandra/KEYS](https://downloads.apache.org/cassandra/KEYS) | sudo apt-key add -

# Install Cassandra
sudo apt-get update
sudo apt-get install -y cassandra

3. キースペースとテーブルを作成する

従業員テーブルの例を使用して、「zdmbigtable」というキースペースを作成します。

cd ~/apache-cassandra
bin/cqlsh <your-localhost-ip? 9042  #starts the cql shell

cqlsh 内:

-- Create keyspace (adjust replication for production)
CREATE KEYSPACE zdmbigtable WITH replication = {'class':'SimpleStrategy', 'replication_factor':1};

-- Use the keyspace
USE zdmbigtable;

-- Create the employee table
CREATE TABLE employee (
    name text PRIMARY KEY,
    age bigint,
    code int,
    credited double,
    balance float,
    is_active boolean,
    birth_date timestamp
);

-- Exit cqlsh
EXIT;

SSH セッションを開いたままにするか、この VM の IP アドレス（hostname -I）をメモします。

4. Bigtable（ターゲット）を設定する

所要時間 0:01

Bigtable インスタンスを作成します。インスタンス ID として zdmbigtable を使用します。

gcloud bigtable instances create zdmbigtable \ 
--display-name="ZDM Bigtable Target" \ 
--cluster=bigtable-c1 \ 
--cluster-zone=$ZONE \ 
--cluster-num-nodes=1 # Use 1 node for dev/testing; scale as needed

Bigtable テーブル自体は、後で Cassandra-Bigtable プロキシ設定スクリプトによって作成されます。

5. Cassandra-Bigtable プロキシを設定する

1. Cassandra-Bigtable Proxy 用の Compute Engine VM を作成する

gcloud compute instances create bigtable-proxy-vm \ 
--machine-type=e2-medium \
--image-family=ubuntu-2004-lts \
--image-project=ubuntu-os-cloud \
--tags=cassandra-migration \
--boot-disk-size=20GB

bigtable-proxy-vm に SSH 接続します。

gcloud compute ssh bigtable-proxy-vm

VM 内:

# Install Git and Go
sudo apt-get update
sudo apt-get install -y git golang-go

# Clone the proxy repository
# Replace with the actual repository URL if different
git clone https://github.com/GoogleCloudPlatform/cloud-bigtable-ecosystem.git
cd cassandra-to-bigtable-proxy/

# Set Go environment variables
export GOPATH=$HOME/go
export PATH=$PATH:/usr/local/go/bin:$GOPATH/bin

2. プロキシを構成する

nano config.yaml

次の変数を更新します。より高度な構成については、GitHub で提供されているこの例を使用します。

#!/bin/bash
cassandraToBigtableConfigs:
  # Global default GCP Project ID
  projectId: <your-project-id>

listeners:
- name: cluster1
  port: 9042
  bigtable:
    #If you want to use multiple instances then pass the instance names by comma seperated
    #Instance name should not contain any special characters except underscore(_)
    instanceIds: zdmbigtable

    # Number of grpc channels to be used for Bigtable session.
    Session:
      grpcChannels: 4

otel:
  # Set enabled to true or false for OTEL metrics/traces/logs.
  enabled: False

  # Name of the collector service to be setup as a sidecar
  serviceName: cassandra-to-bigtable-otel-service

  healthcheck:
    # Enable the health check in this proxy application config only if the
    # "health_check" extension is added to the OTEL collector service configuration.
    #
    # Recommendation:
    # Enable the OTEL health check if you need to verify the collector's availability
    # at the start of the application. For development or testing environments, it can
    # be safely disabled to reduce complexity.

    # Enable/Disable Health Check for OTEL, Default 'False'.
    enabled: False
    # Health check endpoint for the OTEL collector service
    endpoint: localhost:13133
  metrics:
    # Collector service endpoint
    endpoint: localhost:4317

  traces:
    # Collector service endpoint
    endpoint: localhost:4317
    #Sampling ratio should be between 0 and 1. Here 0.05 means 5/100 Sampling ratio.
    samplingRatio: 1

loggerConfig:
  # Specifies the type of output, here it is set to 'file' indicating logs will be written to a file.
  # Value of `outputType` should be `file` for file type or `stdout` for standard output.
  # Default value is `stdout`.
  outputType: stdout
  # Set this only if the outputType is set to `file`.
  # The path and name of the log file where logs will be stored. For example, output.log, Required Key.
  # Default `/var/log/cassandra-to-spanner-proxy/output.log`.
  fileName: output/output.log
  # Set this only if the outputType is set to `file`.
  # The maximum size of the log file in megabytes before it is rotated. For example, 500 for 500 MB.
  maxSize: 10
  # Set this only if the outputType is set to `file`.
  # The maximum number of backup log files to keep. Once this limit is reached, the oldest log file will be deleted.
  maxBackups: 2
  # Set this only if the outputType is set to `file`.
  # The maximum age in days for a log file to be retained. Logs older than this will be deleted. Required Key.
  # Default 3 days
  maxAge: 1

  # Set this only if the outputType is set to `file`.
  # Default value is set to 'False'. Change the value to 'True', if log files are required to be compressed.
  compress: True

ファイルを保存して閉じます（nano で Ctrl+X、Y、Enter の順に押します）。

3. Cassandra-Bigtable プロキシを起動する

プロキシ サーバーを起動します。

# At the root of the cassandra-to-bigtable-proxy directory
go run proxy.go

プロキシが起動され、ポート 9042 で受信 CQL 接続をリッスンします。このターミナル セッションは実行したままにします。この VM の IP アドレスをメモします（ホスト名 -I）

4. CQL を使用してテーブルを作成する

cqlsh を Cassandra-Bigtable プロキシ VM の IP アドレスに接続します。

cqlsh で次のコマンドを実行します。

-- Create the employee table
CREATE TABLE zdmbigtable.employee (
    name text PRIMARY KEY,
    age bigint,
    code int,
    credited double,
    balance float,
    is_active boolean,
    birth_date timestamp
);

Google Cloud コンソールで、Bigtable インスタンスに従業員テーブルとメタデータ テーブルが存在することを確認します。

6. ZDM プロキシを設定する

ZDM プロキシには、トラフィックを処理する 1 つ以上のプロキシノードと、Ansible を介したデプロイとオーケストレーションに使用される「ジャンプホスト」の 2 台以上のマシンが必要です。

1. ZDM プロキシの Compute Engine VM を作成する

2 つの VM（zdm-proxy-jumphost と zdm-proxy-node-1）が必要です。

# Jumphost VM 
gcloud compute instances create zdm-jumphost \
--machine-type=e2-medium \
--image-family=ubuntu-2004-lts \
--image-project=ubuntu-os-cloud \
--tags=cassandra-migration \
--boot-disk-size=20GB

# Proxy Node VM 
gcloud compute instances create zdm-proxy-node-1 \
--machine-type=e2-standard-8 \
--image-family=ubuntu-2004-lts \
--image-project=ubuntu-os-cloud \
--tags=cassandra-migration \
--boot-disk-size=20GB

両方の VM の IP アドレスをメモします。

2. ジャンプホストを準備する

zdm-jumphost に SSH 接続する

gcloud compute ssh zdm-jumphost

# Install Git and Ansible

sudo apt-get update
sudo apt-get install -y git ansible

ジャンプホスト内

git clone https:\/\/github.com/datastax/zdm-proxy-automation.git 

cd zdm-proxy-automation/ansible/

メインの構成ファイル vars/zdm_proxy_cluster_config.yml を編集します。

origin_contact_points と target_contact_points を、Cassandra VM と Cassandra-Bigtable プロキシ VM の内部 IP アドレスにそれぞれ更新します。認証は設定していないため、コメント化したままにします。

##############################
#### ORIGIN CONFIGURATION ####
##############################
## Origin credentials (leave commented if no auth)
# origin_username: ...
# origin_password: ...

## Set the following two parameters only if Origin is a self-managed, non-Astra cluster
origin_contact_points: <Your-Cassandra-VM-Internal-IP> # Replace!
origin_port: 9042

##############################
#### TARGET CONFIGURATION ####
##############################
## Target credentials (leave commented if no auth)
# target_username: ...
# target_password: ...

## Set the following two parameters only if Target is a self-managed, non-Astra cluster
target_contact_points: <Your-Bigtable-Proxy-VM-Internal-IP> # Replace!
target_port: 9042

# --- Other ZDM Proxy settings can be configured below ---
# ... (keep defaults for this codelab)

ファイルを保存して閉じます。

3. Ansible を使用して ZDM プロキシをデプロイする

ジャンプホストの ansible ディレクトリから Ansible プレイブックを実行します。

ansible-playbook deploy_zdm_proxy.yml -i zdm_ansible_inventory

このコマンドは、プロキシノード（zdm-proxy-node-1）に必要なソフトウェア（Docker など）をインストールし、ZDM Proxy Docker イメージを pull して、指定した構成でプロキシ コンテナを起動します。

4. ZDM プロキシの正常性を確認する

ジャンプホストから zdm-proxy-node-1（ポート 14001）で実行されている ZDM プロキシの準備状況エンドポイントを確認します。

# Replace <zdm-proxy-node-1-internal-ip> with the actual internal IP.
curl -G http://<zdm-proxy-node-1-internal-ip>:14001/health/readiness

次のような出力が表示され、送信元（Cassandra）とターゲット（Cassandra-Bigtable プロキシ）の両方が UP であることを示します。

{
  "OriginStatus": {
    "Addr": "<Your-Cassandra-VM-Internal-IP>:9042",
    "CurrentFailureCount": 0,
    "FailureCountThreshold": 1,
    "Status": "UP"
  },
  "TargetStatus": {
    "Addr": "<Your-Bigtable-Proxy-VM-Internal-IP>:9042",
    "CurrentFailureCount": 0,
    "FailureCountThreshold": 1,
    "Status": "UP"
  },
  "Status": "UP"
}

7. アプリケーションを構成して二重書き込みを開始する

所要時間 0:05

実際の移行では、この段階で ZDM プロキシ ノードの IP アドレス（:9042）に接続します。

アプリケーションが ZDM プロキシに接続すると、デフォルトでは読み取りはオリジン（Cassandra）から提供されます。書き込みは、送信元（Cassandra）と宛先（Bigtable、Cassandra-Bigtable プロキシ経由）の両方に送信されます。これにより、新しいデータが両方のデータベースに同時に書き込まれながら、アプリケーションは通常どおり機能し続けることができます。ジャンプホストまたはネットワーク内の別の VM から ZDM Proxy を指す cqlsh を使用して、接続をテストできます。

Cqlsh <zdm-proxy-node-1-ip-address> 9042

データを挿入してみます。

INSERT INTO zdmbigtable.employee (name, age, is_active) VALUES ('Alice', 30, true); 
SELECT * FROM employee WHERE name = 'Alice';

このデータは Cassandra と Bigtable の両方に書き込む必要があります。これは、Google Cloud コンソールに移動して、インスタンスの Bigtable Query Editor を開くことで Bigtable で確認できます。「SELECT * FROM employee」クエリを実行すると、最近挿入されたデータが表示されます。

8. Cassandra Data Migrator を使用して過去のデータを移行する

新しいデータに対してデュアル書き込みが有効になったので、Cassandra Data Migrator（CDM）ツールを使用して、既存の過去データを Cassandra から Bigtable にコピーします。

1. CDM 用の Compute Engine VM を作成する

この VM には、Spark に十分なメモリが必要です。

gcloud compute instances create cdm-migrator-vm \
--machine-type=e2-medium \
--image-family=ubuntu-2004-lts \
--image-project=ubuntu-os-cloud \
--tags=cassandra-migration \
--boot-disk-size=40GB

2. 前提条件（Java 11、Spark）をインストールする

cdm-migrator-vm に SSH 接続します。

gcloud compute ssh cdm-migrator-vm

VM 内:

# Install Java 11 
sudo apt-get update 
sudo apt-get install -y openjdk-11-jdk
 
# Verify Java installation 
java -version 

# Download and Extract Spark (Using version 3.5.3 as requested) 
# Check the Apache Spark archives for the correct URL if needed

wget  [https://archive.apache.org/dist/spark/spark-3.5.3/spark-3.5.3-bin-hadoop3-scala2.13.tgz](https://archive.apache.org/dist/spark/spark-3.5.3/spark-3.5.3-bin-hadoop3-scala2.13.tgz) tar -xvzf spark-3.5.3-bin-hadoop3-scala2.13.tgz
 
export SPARK_HOME=$PWD/spark-3.5.3-bin-hadoop3-scala2.13 
export PATH=$PATH:$SPARK_HOME/bin

3. Cassandra Data Migrator をダウンロードする

CDM ツールの jar ファイルをダウンロードします。Cassandra Data Migrator GitHub リリース ページで、目的のバージョンの正しい URL を確認します。

# Example using version 5.2.2 - replace URL if needed
wget https://github.com/datastax/cassandra-data-migrator/releases/download/v5.2.2/cassandra-data-migrator-5.2.2.jar)

4. CDM を構成する

cdm.properties という名前のプロパティ ファイルを作成します。

Nano cdm.properties

次の構成を貼り付け、IP アドレスを置き換え、TTL/Writetime 機能を無効にします。これらの機能は、Bigtable で直接サポートされていないためです。auth はコメントアウトしたままにします。

# Origin Cassandra Connection 
spark.cdm.connect.origin.host <Your-Cassandra-VM-IP-Address> # Replace!
spark.cdm.connect.origin.port 9042
spark.cdm.connect.origin.username cassandra # Leave default, or set if auth is enabled # 
spark.cdm.connect.origin.password cassandra # Leave default, or set if auth is enabled #

# Target Bigtable (via Cassandra-Bigtable Proxy)
Connection spark.cdm.connect.target.host <Your-Bigtable-Proxy-VM-IP-Address> # Replace! 
spark.cdm.connect.target.port 9042
spark.cdm.connect.target.username cassandra # Leave default, or set if auth is enabled #
spark.cdm.connect.target.password cassandra # Leave default, or set if auth is enabled #

# Disable TTL/Writetime features (Important for Bigtable compatibility via Proxy)
spark.cdm.feature.origin.ttl.automatic false 
spark.cdm.feature.origin.writetime.automatic false 
spark.cdm.feature.target.ttl.automatic false 
spark.cdm.feature.target.writetime.automatic false

ファイルを保存して閉じます。

5. 移行ジョブを実行する

spark-submit を使用して移行を実行します。このコマンドは、プロパティ ファイルを使用して CDM jar を実行し、移行するキースペースとテーブルを指示します。VM のサイズとデータ量に基づいて、メモリ設定（–driver-memory、–executor-memory）を調整します。

CDM JAR ファイルとプロパティ ファイルを含むディレクトリにいることを確認します。別のバージョンをダウンロードした場合は、「cassandra-data-migrator-5.2.2.jar」を置き換えます。

./spark-3.5.3-bin-hadoop3-scala2.13/bin/spark-submit \ --properties-file cdm.properties \ --master "local[*]" \ --driver-memory 4G \ --executor-memory 4G \ --class com.datastax.cdm.job.Migrate \ cassandra-data-migrator-5.2.2.jar &> cdm_migration_$(date +%Y%m%d_%H%M).log

移行はバックグラウンドで実行され、ログは cdm_migration_... に書き込まれます。.log に保存されます。ログファイルで進捗状況とエラーを確認します。

tail -f cdm_migration_*.log

6. データの移行を確認する

CDM ジョブが正常に完了したら、過去のデータが Bigtable に存在することを確認します。Cassandra-Bigtable Proxy は CQL 読み取りを許可するため、ZDM Proxy（移行後に読み取りをターゲットに転送するか、転送するように構成可能）または Cassandra-Bigtable Proxy に直接接続した cqlsh を使用して、データをクエリできます。ZDM プロキシ経由で接続する:

cqlsh <zdm-proxy-node-1-ip-address> 9042

cqlsh 内:

SELECT COUNT(*) FROM zdmbigtable.employee; -- Check row count matches origin 
SELECT * FROM employee LIMIT 10; -- Check some sample data

または、cbt ツール（CDM VM または Cloud Shell にインストールされている場合）を使用して、Bigtable でデータを直接検索します。

# First, install cbt if needed
# gcloud components update
# gcloud components install cbt

# Then lookup a specific row (replace 'some_employee_name' with an actual primary key)
cbt -project $PROJECT_ID -instance zdmbigtable lookup employee some_employee_name

9. カットオーバー（概念）

Cassandra と Bigtable 間のデータの整合性を徹底的に確認したら、最終的なカットオーバーに進むことができます。

ZDM プロキシでは、カットオーバー時に、ソース（Cassandra）ではなくターゲット（Bigtable）から主に読み取るようにプロキシを再構成します。これは通常、ZDM Proxy の構成を介して行われ、アプリケーションの読み取りトラフィックを Bigtable に効果的にシフトします。

Bigtable がすべてのトラフィックを正しく処理していることを確認したら、最終的には次のことができます。

  • ZDM プロキシを再構成して、デュアル書き込みを停止します。
  • 元の Cassandra クラスタを廃止します。
  • ZDM Proxy を削除し、アプリケーションを Cassandra-Bigtable Proxy に直接接続するか、Java 用のネイティブ Bigtable CQL クライアントを使用します。

カットオーバー用の ZDM プロキシの再構成の詳細については、この基本的な Codelab の範囲を超えますが、Datastax ZDM のドキュメントで詳しく説明されています。

10. クリーンアップ

料金が発生しないように、この Codelab で作成したリソースを削除します。

1. Compute Engine VM を削除する

gcloud compute instances delete cassandra-origin-vm zdm-proxy-jumphost zdm-proxy-node-1 bigtable-proxy-vm cdm-migrator-vm --zone=$ZONE --quiet

2. Bigtable インスタンスを削除する

gcloud bigtable instances delete zdmbigtable

3. ファイアウォール ルールを削除する

gcloud compute firewall-rules delete allow-migration-internal

4. Cassandra データベースを削除する（ローカルにインストールされている場合、または永続化されている場合）

ここで作成した Compute Engine VM の外部に Cassandra をインストールした場合は、適切な手順に沿ってデータを削除するか、Cassandra をアンインストールします。

11. 完了

これで、Apache Cassandra から Bigtable へのプロキシベースの移行パスを設定するプロセスが完了しました。

このチュートリアルでは、以下の内容について学習しました。

Cassandra と Bigtable をデプロイします。

  • CQL 互換性のために Cassandra-Bigtable プロキシを構成します。
  • Datastax ZDM プロキシをデプロイして、デュアル書き込みとトラフィックを管理します。
  • Cassandra Data Migrator を使用して過去のデータを移動します。

このアプローチでは、プロキシ レイヤを活用することで、ダウンタイムを最小限に抑え、コードを変更せずに移行できます。

次のステップ

  • Bigtable のドキュメントを確認する
  • 詳細な構成とカットオーバー手順については、Datastax ZDM Proxy のドキュメントをご覧ください。
  • 詳細については、Cassandra-Bigtable Proxy リポジトリをご覧ください。
  • 詳細な使用方法については、Cassandra Data Migrator リポジトリをご覧ください。
  • 他の Google Cloud Codelab を試す