듀얼 쓰기 프록시를 사용하여 Cassandra에서 Bigtable로 마이그레이션

1. 소개

Bigtable은 대규모 분석 및 운영 워크로드를 위해 설계된 완전 관리형 고성능 NoSQL 데이터베이스 서비스입니다. Apache Cassandra와 같은 기존 데이터베이스에서 Bigtable로 마이그레이션하려면 다운타임과 애플리케이션 영향을 최소화하기 위해 신중하게 계획해야 하는 경우가 많습니다.

이 Codelab에서는 프록시 도구를 조합하여 Cassandra에서 Bigtable로 마이그레이션하는 전략을 보여줍니다.

1. Cassandra-Bigtable 프록시: 쿼리를 변환하여 Cassandra 클라이언트 및 도구 (예: cqlsh 또는 드라이버)가 Cassandra Query Language (CQL) 프로토콜을 사용하여 Bigtable과 상호작용할 수 있도록 지원합니다.
2. Datastax 다운타임 제로 마이그레이션 (ZDM) 프록시: 애플리케이션과 데이터베이스 서비스 (Cassandra-Bigtable 프록시를 통한 원본 Cassandra 및 타겟 Bigtable) 사이에 있는 오픈소스 프록시입니다. 이 도구는 이중 쓰기를 조정하고 트래픽 라우팅을 관리하여 애플리케이션 변경사항과 다운타임을 최소화하면서 마이그레이션을 지원합니다.
3. Cassandra 데이터 마이그레이터 (CDM): 소스 Cassandra 클러스터에서 대상 Bigtable 인스턴스로 이전 데이터를 일괄 마이그레이션하는 데 사용되는 오픈소스 도구입니다.

학습할 내용

• Compute Engine에서 기본 Cassandra 클러스터를 설정하는 방법
• Bigtable 인스턴스를 만드는 방법
• Cassandra 스키마를 Bigtable에 매핑하기 위해 Cassandra-Bigtable 프록시를 배포하고 구성하는 방법
• 이중 쓰기를 위해 Datastax ZDM 프록시를 배포하고 구성하는 방법
• Cassandra 데이터 마이그레이터 도구를 사용하여 기존 데이터를 일괄 마이그레이션하는 방법
• 프록시 기반 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. 리전 및 영역 선택

리소스의 리전과 영역을 선택합니다. 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

3. 필요한 API 사용 설정

프로젝트에 Compute Engine API와 Bigtable API가 사용 설정되어 있는지 확인합니다.

gcloud services enable compute.googleapis.com bigtable.googleapis.com bigtableadmin.googleapis.com

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:7000,tcp:14001 \
--source-ranges=10.0.0.0/8 \
--target-tags=cassandra-migration

3. Cassandra 클러스터 배포 (원본)

이 Codelab에서는 Compute Engine에 간단한 단일 노드 Cassandra 클러스터를 설정합니다. 실제 시나리오에서는 기존 클러스터에 연결합니다.

1. Cassandra용 GCE VM 만들기

gcloud compute instances create cassandra-origin \
--machine-type=e2-medium \
--image-family=ubuntu-2204-lts \
--image-project=ubuntu-os-cloud \
--tags=cassandra-migration \
--boot-disk-size=20GB \
--scopes=cloud-platform \
--zone="$ZONE"

Cassandra 인스턴스에 SSH로 연결

gcloud compute ssh --zone="$ZONE" "cassandra-origin"

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 41x main" | sudo tee -a /etc/apt/sources.list.d/cassandra.sources.list
curl https://downloads.apache.org/cassandra/KEYS | sudo apt-key add -

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

# (Optional) Verify Cassandra is running
sudo systemctl status cassandra

3. Cassandra 구성

비공개 네트워크 내에서 액세스할 수 있도록 Cassandra를 구성해야 합니다.

다음을 실행하여 Cassandra-origin의 비공개 IP를 가져옵니다.

hostname -I

Cassandra 구성을 수정합니다. 새 구성 행을 추가할 필요는 없습니다. 이미 있는 행만 업데이트하면 됩니다.

sudo vim /etc/cassandra/cassandra.yaml

1. seed_provider.parameters.seeds을 "CASSANDRA_ORIGIN_PRIVATE_IP:7000"로 설정합니다.
2. rpc_address을 CASSANDRA_ORIGIN_PRIVATE_IP로 설정합니다.
3. listen_address을 CASSANDRA_ORIGIN_PRIVATE_IP로 설정합니다.

파일을 저장합니다.

마지막으로 Cassandra를 다시 시작하여 구성 변경사항을 로드합니다.

sudo systemctl restart cassandra

# (Optional) Verify Cassandra is running
sudo systemctl status cassandra

4. 키스페이스 및 테이블 만들기

직원 테이블 예시를 사용하여 'zdmbigtable'이라는 키스페이스를 만듭니다.

참고: Cassandra가 연결을 수락하기 시작하는 데 1분 정도 걸릴 수 있습니다.

# Start cqlsh
cqlsh $(hostname -I)

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 프록시용 Compute Engine VM 만들기

gcloud iam service-accounts create bigtable-proxy-sa \
    --description="Service account for Bigtable Proxy access" \
    --display-name="Bigtable Proxy Access SA"

export BIGTABLE_PROXY_SA_EMAIL=$(gcloud iam service-accounts list --filter="displayName='Bigtable Proxy Access SA'" --format="value(email)")

gcloud bigtable instances add-iam-policy-binding zdmbigtable \
  --member="serviceAccount:$BIGTABLE_PROXY_SA_EMAIL" \
  --role="roles/bigtable.admin"

gcloud compute instances create bigtable-proxy-vm \
--machine-type=e2-medium \
--image-family=ubuntu-2204-lts \
--image-project=ubuntu-os-cloud \
--tags=cassandra-migration \
--boot-disk-size=20GB \
--zone=$ZONE \
--scopes=cloud-platform \
--service-account="$BIGTABLE_PROXY_SA_EMAIL"

bigtable-proxy-vm에 SSH로 연결합니다.

gcloud compute ssh --zone="$ZONE" "bigtable-proxy-vm"

bigtable-proxy-vm에서 다음을 실행합니다.

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

wget https://go.dev/dl/go1.23.6.linux-amd64.tar.gz
sudo rm -rf /usr/local/go
sudo tar -C /usr/local -xzf go1.23.6.linux-amd64.tar.gz

echo 'export GOPATH=$HOME/go' >> ~/.profile
echo 'export PATH=$PATH:/usr/local/go/bin:$GOPATH/bin' >> ~/.profile
source ~/.profile

# Clone the proxy repository
git clone https://github.com/GoogleCloudPlatform/cloud-bigtable-ecosystem.git
cd cloud-bigtable-ecosystem/cassandra-bigtable-migration-tools/cassandra-bigtable-proxy/

2. Cassandra-Bigtable 프록시 시작

프록시 서버를 시작합니다.

# At the root of the cassandra-to-bigtable-proxy directory
go run proxy.go --project-id="$(gcloud config get-value project)" --instance-id=zdmbigtable --keyspace-id=zdmbigtable --rpc-address=$(hostname -I)

프록시가 시작되고 포트 9042에서 수신되는 CQL 연결을 수신 대기합니다. 이 터미널 세션을 실행 상태로 유지합니다. 이 VM의 IP 주소를 기록합니다 (호스트 이름 -I).

3. CQL을 통해 테이블 만들기

CQLSH를 Cassandra-Bigtable 프록시 VM의 IP 주소에 연결합니다. 다음 명령어를 로컬로 실행하여 IP 주소를 찾을 수 있습니다.

gcloud compute instances describe bigtable-proxy-vm --format='get(networkInterfaces[0].networkIP)'

별도의 창에서 cassandra-origin VM에 SSH로 연결하고 cqlsh를 bigtable-proxy에 사용합니다. Bigtable에서 기본 테이블을 만들 수 있는 충분한 시간을 확보하기 위해 기본 요청 제한 시간보다 긴 제한 시간을 설정했습니다. 'Connected to cassandra-bigtable-proxy-v0.2.3' 또는 이와 유사한 메시지가 표시되어야 합니다. 이는 로컬 Cassandra 서버가 아닌 Bigtable 프록시에 연결되었음을 나타냅니다.

# Replace <your-bigtable-proxy-vm-ip> with the ip from the above command
export BIGTABLE_PROXY_IP=<your-bigtable-proxy-vm-ip>
cqlsh --request-timeout=60 $BIGTABLE_PROXY_IP

-- 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
);

CQLSH에서 다음을 실행하여 테이블이 생성되었는지 확인합니다.

DESC TABLE zdmbigtable.employee;

6. ZDM 프록시 설정

이 실습에서는 ZDM 프록시의 단일 인스턴스를 만들지만 프로덕션 마이그레이션에는 멀티 노드 설정이 필요합니다.

1. ZDM 프록시 VM 만들기

gcloud compute instances create zdm-proxy-vm \
--machine-type=e2-medium \
--image-family=ubuntu-2204-lts \
--image-project=ubuntu-os-cloud \
--tags=cassandra-migration \
--boot-disk-size=20GB \
--scopes=cloud-platform \
--zone=$ZONE

두 VM의 IP 주소를 확인합니다.

2. ZDM 프록시 준비

gcloud compute ssh --zone="$ZONE" zdm-proxy-vm

export ZDM_VERSION="2.3.4"
wget "https://github.com/datastax/zdm-proxy/releases/download/v$ZDM_VERSION/zdm-proxy-linux-amd64-v$ZDM_VERSION.tgz"
tar -xvzf "zdm-proxy-linux-amd64-v$ZDM_VERSION.tgz"

# replace YOUR_ZONE
gcloud config set compute/zone "YOUR_ZONE"
export ZDM_ORIGIN_CONTACT_POINTS=$(gcloud compute instances describe cassandra-origin --format='get(networkInterfaces[0].networkIP)') 
export ZDM_TARGET_CONTACT_POINTS=$(gcloud compute instances describe bigtable-proxy-vm --format='get(networkInterfaces[0].networkIP)')
export ZDM_ORIGIN_USERNAME=""
export ZDM_ORIGIN_PASSWORD=""
export ZDM_TARGET_USERNAME=""
export ZDM_TARGET_PASSWORD=""
export ZDM_PROXY_LISTEN_ADDRESS=0.0.0.0
export ZDM_PROXY_LISTEN_PORT=9042
./zdm-proxy-v${ZDM_VERSION}

7. 애플리케이션 구성 및 이중 쓰기 시작

지속 시간 0:05

실제 마이그레이션의 이 단계에서는 ZDM 프록시 VM의 IP 주소(예: :9042)에 연결합니다.

애플리케이션이 ZDM 프록시에 연결되면 기본적으로 읽기는 출처 (Cassandra)에서 제공됩니다. 쓰기는 출처 (Cassandra)와 타겟 (Cassandra-Bigtable 프록시를 통한 Bigtable) 모두로 전송됩니다. 이렇게 하면 애플리케이션이 정상적으로 계속 작동하면서 새 데이터가 두 데이터베이스에 동시에 기록됩니다. ZDM 프록시를 가리키는 cqlsh를 사용하여 연결을 테스트할 수 있습니다.

cqlsh $(gcloud compute instances describe zdm-proxy-vm --format='get(networkInterfaces[0].networkIP)')

데이터를 삽입해 보세요.

INSERT INTO zdmbigtable.employee (name, age, is_active) VALUES ('Alice', 30, true); 
INSERT INTO zdmbigtable.employee (name, age, is_active) VALUES ('Anna', 45, true); 
INSERT INTO zdmbigtable.employee (name, age, is_active) VALUES ('Albert', 50, false); 
SELECT * FROM zdmbigtable.employee;

이 데이터는 Cassandra와 Bigtable 모두에 기록되어야 합니다. Google Cloud 콘솔로 이동하여 인스턴스의 Bigtable 쿼리 편집기를 열면 Bigtable에서 이를 확인할 수 있습니다. 'SELECT * FROM employee' 쿼리를 실행하면 최근에 삽입된 데이터가 표시됩니다.

8. Cassandra 데이터 마이그레이터를 사용하여 이전 데이터 마이그레이션

이제 새 데이터에 대해 이중 쓰기가 활성화되었으므로 Cassandra 데이터 마이그레이터 (CDM) 도구를 사용하여 Cassandra에서 Bigtable로 기존 이전 데이터를 복사합니다.

1. CDM용 Compute Engine VM 만들기

이 VM에는 Spark에 충분한 메모리가 필요합니다.

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

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
tar -xvzf spark-3.5.3-bin-hadoop3-scala2.13.tgz

echo 'export SPARK_HOME=$PWD/spark-3.5.3-bin-hadoop3-scala2.13' >> ~/.profile
echo 'export PATH=$PATH:$SPARK_HOME/bin' >> ~/.profile
source ~/.profile

3. Cassandra 데이터 마이그레이터 다운로드

브라우저에서 CDM 패키지 페이지를 열고 애셋 패널에서 .jar 링크를 복사합니다. 5.4.0을 사용할 수 없는 경우 가장 근접한 버전을 선택합니다. 아래 명령어에 링크를 붙여넣고 cdm-migrator-vm 인스턴스에서 실행합니다. URL 주변의 작은따옴표는 유지합니다.

wget 'JAR_URL_GOES_HERE' -O cassandra-data-migrator.jar

jar 도구로 jar 파일을 스캔하여 올바르게 다운로드되었는지 확인합니다. '.class' 파일의 긴 목록이 표시되어야 합니다.

jar tf cassandra-data-migrator.jar 

4. 데이터 추가

cassandra-origin (zdm-proxy-vm 아님)에 직접 작성하여 이전할 데이터를 추가해야 합니다.

INSERT INTO zdmbigtable.employee (name, age, is_active) VALUES ('Alfred', 67, true); 
INSERT INTO zdmbigtable.employee (name, age, is_active) VALUES ('Bobby', 12, false); 
INSERT INTO zdmbigtable.employee (name, age, is_active) VALUES ('Carol', 29, true); 

5. 마이그레이션 작업 실행

spark-submit을 사용하여 마이그레이션을 실행합니다. 이 명령어는 속성 파일을 사용하여 CDM jar를 실행하고 마이그레이션할 키스페이스와 테이블을 지정하도록 Spark에 지시합니다. VM 크기와 데이터 볼륨에 따라 메모리 설정 (–driver-memory, –executor-memory)을 조정합니다.

CDM jar 및 속성 파일이 포함된 디렉터리에 있는지 확인합니다.

팁: 로컬 머신에서 다음 명령어를 실행하여 Cassandra 및 프록시 VM의 내부 IP를 가져올 수 있습니다.

gcloud compute instances describe cassandra-origin --format='get(networkInterfaces[0].networkIP)'
gcloud compute instances describe bigtable-proxy-vm --format='get(networkInterfaces[0].networkIP)'

export ORIGIN_HOST="<your-cassandra-origin-ip>"
export TARGET_HOST="<your-bigtable-proxy-vm-ip>"
export KEYSPACE_TABLE="zdmbigtable.employee"
spark-submit --verbose --master "local[*]" \
--driver-memory 3G --executor-memory 3G \
--conf spark.cdm.schema.origin.keyspaceTable="$KEYSPACE_TABLE" \
--conf spark.cdm.connect.origin.host="$ORIGIN_HOST" \
--conf spark.cdm.connect.origin.port=9042 \
--conf spark.cdm.connect.target.host="$TARGET_HOST" \
--conf spark.cdm.connect.target.port=9042 \
--conf spark.cdm.feature.origin.ttl.automatic=false \
--conf spark.cdm.feature.origin.writetime.automatic=false \
--conf spark.cdm.feature.target.ttl.automatic=false \
--conf spark.cdm.feature.target.writetime.automatic=false \
--conf spark.cdm.schema.origin.column.ttl.automatic=false \
--conf spark.cdm.schema.ttlwritetime.calc.useCollections=false \
--class com.datastax.cdm.job.Migrate cassandra-data-migrator.jar

6. 데이터 이전 확인

CDM 작업이 완료되면 Bigtable에 이전 데이터가 있는지 확인합니다.

cqlsh <bigtable-proxy-vm-ip>

cqlsh 내부:

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

9. 컷오버 (개념)

Cassandra와 Bigtable 간의 데이터 일관성을 철저히 확인한 후 최종 컷오버를 진행할 수 있습니다.

ZDM 프록시를 사용하면 전환 시 출처 (Cassandra) 대신 타겟 (Bigtable)에서 주로 읽도록 다시 구성해야 합니다. 일반적으로 ZDM 프록시의 구성을 통해 이 작업이 이루어지며, 애플리케이션의 읽기 트래픽이 Bigtable로 효과적으로 전환됩니다.

Bigtable이 모든 트래픽을 올바르게 처리한다고 확신이 들면 다음 작업을 할 수 있습니다.

• ZDM 프록시를 재구성하여 이중 쓰기를 중지합니다.
• 원래 Cassandra 클러스터를 사용 중단합니다.
• ZDM 프록시를 삭제하고 애플리케이션이 Cassandra-Bigtable 프록시에 직접 연결되도록 하거나 네이티브 Bigtable CQL 클라이언트(Java용)를 사용합니다.

전환을 위한 ZDM 프록시 재구성의 구체적인 내용은 이 기본 Codelab의 범위를 벗어나지만 Datastax ZDM 문서에 자세히 설명되어 있습니다.

10. 삭제

요금이 발생하지 않도록 이 Codelab에서 만든 리소스를 삭제합니다.

1. Compute Engine VM 삭제

gcloud compute instances delete cassandra-origin zdm-proxy-vm 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 데이터 마이그레이터를 사용하여 이전 데이터를 이동합니다.

이 접근 방식을 사용하면 프록시 레이어를 활용하여 다운타임을 최소화하고 코드 변경 없이 마이그레이션할 수 있습니다.

다음 단계

• Bigtable 문서 살펴보기
• 고급 구성 및 전환 절차는 Datastax ZDM 프록시 문서를 참고하세요.
• 자세한 내용은 Cassandra-Bigtable 프록시 저장소를 참고하세요.
• 고급 사용법은 Cassandra Data Migrator 저장소를 확인하세요.
• 다른 Google Cloud Codelab 사용해 보기