이 Codelab 정보
1. 소개
Spanner는 관계형 워크로드와 비관계형 워크로드 모두에 적합한 수평 확장이 가능하고 전 세계적으로 분산된 완전 관리형 데이터베이스 서비스입니다.
Spanner의 Cassandra 인터페이스를 사용하면 익숙한 Cassandra 도구와 문법을 사용하여 Spanner의 확장 가능하고 가용성이 높은 완전 관리형 인프라를 활용할 수 있습니다.
학습할 내용
- Spanner 인스턴스와 데이터베이스를 설정하는 방법
- Cassandra 스키마 및 데이터 모델을 변환하는 방법
- 수신 데이터에 이중 쓰기를 배포하고 구성하는 방법
- Cassandra에서 Spanner로 이전 데이터를 일괄 내보내는 방법
- 데이터를 검증하여 마이그레이션 프로세스 전반에서 데이터 무결성을 보장하는 방법
- Cassandra 대신 Spanner를 가리키도록 애플리케이션을 구성하는 방법
필요한 항목
- 결제 계정에 연결된 Google Cloud 프로젝트
gcloudCLI가 설치되고 구성된 머신에 액세스하거나 Google Cloud Shell을 사용합니다.- Chrome 또는 Firefox와 같은 웹브라우저
2. 설정 및 요건
GCP 프로젝트 만들기
Google Cloud Console에 로그인하여 새 프로젝트를 만들거나 기존 프로젝트를 재사용합니다. 아직 Gmail이나 Google Workspace 계정이 없는 경우 계정을 만들어야 합니다.
- 프로젝트 이름은 이 프로젝트 참가자의 표시 이름입니다. 이는 Google API에서 사용하지 않는 문자열이며 언제든지 업데이트할 수 있습니다.
- 프로젝트 ID는 모든 Google Cloud 프로젝트에서 고유하며, 변경할 수 없습니다(설정된 후에는 변경할 수 없음). Cloud 콘솔은 고유한 문자열을 자동으로 생성합니다. 일반적으로는 신경 쓰지 않아도 됩니다. 대부분의 Codelab에서는 프로젝트 ID (일반적으로
PROJECT_ID로 식별됨)를 참조해야 합니다. 생성된 ID가 마음에 들지 않으면 다른 임의 ID를 생성할 수 있습니다. 또는 직접 시도해 보고 사용 가능한지 확인할 수도 있습니다. 이 단계 이후에는 변경할 수 없으며 프로젝트 기간 동안 유지됩니다. - 참고로 세 번째 값은 일부 API에서 사용하는 프로젝트 번호입니다. 이 세 가지 값에 대한 자세한 내용은 문서를 참고하세요.
결제 설정
그런 다음 결제 관리 사용자 가이드에 따라 Cloud 콘솔에서 결제를 사용 설정해야 합니다. Google Cloud 신규 사용자는 300달러(USD) 상당의 무료 체험판 프로그램에 참여할 수 있습니다. 이 튜토리얼을 마친 후 비용이 청구되지 않도록 하려면 Codelab의 끝에 있는 '9단계 정리'에 따라 Spanner 인스턴스를 종료하면 됩니다.
Cloud Shell 시작
Google Cloud를 노트북에서 원격으로 실행할 수 있지만, 이 Codelab에서는 Cloud에서 실행되는 명령줄 환경인 Google Cloud Shell을 사용합니다.
Google Cloud Console의 오른쪽 상단 툴바에 있는 Cloud Shell 아이콘을 클릭합니다.
환경을 프로비저닝하고 연결하는 데 몇 분 정도 소요됩니다. 완료되면 다음과 같이 표시됩니다.
가상 머신에는 필요한 개발 도구가 모두 들어있습니다. 영구적인 5GB 홈 디렉터리를 제공하고 Google Cloud에서 실행되므로 네트워크 성능과 인증이 크게 개선됩니다. 이 Codelab의 모든 작업은 브라우저 내에서 수행할 수 있습니다. 아무것도 설치할 필요가 없습니다.
다음 단계
다음으로 Cassandra 클러스터를 배포합니다.
3. Cassandra 클러스터 배포 (출처)
이 Codelab에서는 Compute Engine에 단일 노드 Cassandra 클러스터를 설정합니다.
1. Cassandra용 GCE VM 만들기
인스턴스를 만들려면 gcloud compute instances create 명령어를 사용합니다.
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. 키스페이스 및 테이블 만들기
사용자 테이블 예시를 사용하고 'analytics'라는 키스페이스를 만들겠습니다.
cd ~/apache-cassandra bin/cqlsh <your-localhost-ip? 9042 #starts the cql shell
cqlsh 내부:
-- Create keyspace (adjust replication for production)
CREATE KEYSPACE analytics WITH replication = {'class':'SimpleStrategy', 'replication_factor':1};
-- Use the keyspace
USE analytics;
-- Create the users table
CREATE TABLE users (
id int PRIMARY KEY,
active boolean,
username text,
);
-- Exit cqlsh
EXIT;
SSH 세션을 열어 두거나 이 VM의 IP 주소 (hostname -I)를 기록해 둡니다.
다음 단계
이제 Cloud Spanner 인스턴스와 데이터베이스를 설정합니다.
4. Spanner 인스턴스 및 데이터베이스 만들기 (타겟)
Spanner에서 인스턴스는 하나 이상의 Spanner 데이터베이스를 호스팅하는 컴퓨팅 및 스토리지 리소스의 클러스터입니다. 이 Codelab의 Spanner 데이터베이스를 호스팅하려면 인스턴스가 하나 이상 필요합니다.
gcloud SDK 버전 확인
인스턴스를 만들기 전에 Google Cloud Shell의 gcloud SDK가 필요한 버전(gcloud SDK 493.0.0)으로 업데이트되었는지 확인합니다. 아래 명령어에 따라 gcloud SDK 버전을 찾을 수 있습니다.
$ gcloud version | grep Google
다음은 출력 예시입니다.
Google Cloud SDK 489.0.0
사용 중인 버전이 필수 493.0.0 버전 (이전 예의 489.0.0)보다 낮은 경우 다음 명령어를 실행하여 Google Cloud SDK를 업그레이드해야 합니다.
sudo apt-get update \
&& sudo apt-get --only-upgrade install google-cloud-cli-anthoscli google-cloud-cli-cloud-run-proxy kubectl google-cloud-cli-skaffold google-cloud-cli-cbt google-cloud-cli-docker-credential-gcr google-cloud-cli-spanner-migration-tool google-cloud-cli-cloud-build-local google-cloud-cli-pubsub-emulator google-cloud-cli-app-engine-python google-cloud-cli-kpt google-cloud-cli-bigtable-emulator google-cloud-cli-datastore-emulator google-cloud-cli-spanner-emulator google-cloud-cli-app-engine-go google-cloud-cli-app-engine-python-extras google-cloud-cli-config-connector google-cloud-cli-package-go-module google-cloud-cli-istioctl google-cloud-cli-anthos-auth google-cloud-cli-gke-gcloud-auth-plugin google-cloud-cli-app-engine-grpc google-cloud-cli-kubectl-oidc google-cloud-cli-terraform-tools google-cloud-cli-nomos google-cloud-cli-local-extract google-cloud-cli-firestore-emulator google-cloud-cli-harbourbridge google-cloud-cli-log-streaming google-cloud-cli-minikube google-cloud-cli-app-engine-java google-cloud-cli-enterprise-certificate-proxy google-cloud-cli
Spanner API 사용 설정
Cloud Shell 내에서 프로젝트 ID가 설정되어 있는지 확인합니다. 아래의 첫 번째 명령어를 사용하여 현재 구성된 프로젝트 ID를 찾습니다. 결과가 예상과 다른 경우 아래의 두 번째 명령어를 사용하여 올바른 결과를 설정합니다.
gcloud config get-value project
gcloud config set project [YOUR-DESIRED-PROJECT-ID]
기본 리전을 us-central1로 구성합니다. Spanner 리전 구성에서 지원하는 다른 리전으로 언제든지 변경할 수 있습니다.
gcloud config set compute/region us-central1
Spanner API를 사용 설정합니다.
gcloud services enable spanner.googleapis.com
Spanner 인스턴스 만들기
이 섹션에서는 무료 체험판 인스턴스 또는 프로비저닝된 인스턴스를 만듭니다. 이 Codelab에서는 사용되는 Spanner Cassandra 어댑터 인스턴스 ID가 cassandra-adapter-demo이며 export 명령줄을 사용하여 SPANNER_INSTANCE_ID 변수로 설정됩니다. 원하는 경우 자체 인스턴스 ID 이름을 선택할 수 있습니다.
Spanner 무료 체험판 인스턴스 만들기
프로젝트에 Cloud Billing이 사용 설정된 Google 계정이 있는 모든 사용자는 Spanner 90일 무료 체험판 인스턴스를 사용할 수 있습니다. 무료 체험판 인스턴스를 유료 인스턴스로 업그레이드하기로 선택하지 않으면 요금이 청구되지 않습니다. Spanner Cassandra 어댑터는 무료 체험판 인스턴스에서 지원됩니다. 자격 요건을 충족하는 경우 Cloud Shell을 열고 다음 명령어를 실행하여 무료 체험판 인스턴스를 만듭니다.
export SPANNER_INSTANCE_ID=cassandra-adapter-demo
export SPANNER_REGION=regional-us-central1
gcloud spanner instances create $SPANNER_INSTANCE_ID \
--config=$SPANNER_REGION \
--instance-type=free-instance \
--description="Spanner Cassandra Adapter demo"
명령어 결과 출력:
$ gcloud spanner instances create $SPANNER_INSTANCE_ID \ --config=$SPANNER_REGION \ --instance-type=free-instance \ --description="Spanner Cassandra Adapter demo" Creating instance...done.
데이터베이스 만들기
인스턴스가 실행되면 데이터베이스를 만들 수 있습니다. 데이터베이스에서는 스키마를 정의합니다. 데이터베이스에 액세스할 수 있는 사용자를 제어하고, 맞춤 암호화를 설정하고, 최적화 도구를 구성하고, 보관 기간을 설정할 수도 있습니다.
데이터베이스는 ID가 SPANNER_INSTANCE_ID인 인스턴스에 생성됩니다.
데이터베이스를 만들려면 gcloud 명령줄 도구를 사용합니다.
export SPANNER_DATABASE=analytics
gcloud spanner databases create $SPANNER_DATABASE \
--instance=$SPANNER_INSTANCE_ID
명령어 결과:
$ gcloud spanner databases create $SPANNER_DATABASE \ --instance=$SPANNER_INSTANCE_ID Creating database...done.
5. Cassandra 스키마 및 데이터 모델을 Spanner로 마이그레이션
Cassandra 데이터베이스에서 Spanner로 데이터를 전환하는 초기 단계에서 중요한 작업은 Spanner의 구조 및 데이터 유형 요구사항에 맞게 기존 Cassandra 스키마를 변환하는 것입니다.
이 복잡한 스키마 마이그레이션 프로세스를 간소화하기 위해 Spanner는 Spanner Cassandra 스키마 도구라는 유용한 오픈소스 도구를 제공합니다.
Spanner Cassandra 스키마 도구
Spanner Cassandra 스키마 도구는 Spanner 평가 및 스키마 마이그레이션을 위한 독립형 오픈소스 도구입니다. 이 도구의 기본 기능은 기존 Cassandra 스키마에 있는 정의를 기반으로 Spanner 스키마를 자동으로 생성하는 것입니다. 이 도구는 Cassandra 테이블 구조, 데이터 유형, 기본 키 구성을 분석하여 이에 상응하는 Spanner 테이블 정의를 생성하므로 일반적으로 스키마 변환에 수반되는 수동 작업이 크게 줄어듭니다.
Cassandra 스키마 내보내기
Spanner Cassandra 스키마 도구를 사용하기 전에 가장 먼저 해야 할 일은 현재 Cassandra 클러스터에서 스키마를 추출하는 것입니다. cqlsh를 통해 기존 Cassandra 클러스터에 연결하고 Cassandra에서 스키마를 내보내면 됩니다.
cqlsh [IP] "-e DESC SCHEMA" > orig_schema.cql
이 명령어에서 [IP]는 Cassandra 클러스터의 노드 중 하나의 IP 주소 또는 호스트 이름으로 바꿔야 합니다. 명령어의 -e DESC SCHEMA 부분은 cqlsh에 Cassandra 클러스터의 전체 스키마를 설명하도록 지시합니다. 그러면 CREATE KEYSPACE 및 CREATE TABLE 문이 포함된 이 명령어의 출력이 orig_schema.cql라는 파일로 리디렉션됩니다.
이 orig_schema.cql 파일의 콘텐츠는 기본적으로 Cassandra 스키마의 텍스트 블루프린트를 나타냅니다. orig_schema.cql 파일의 콘텐츠는 다음과 같습니다.
CREATE KEYSPACE analytics WITH replication = {'class': 'SimpleStrategy', 'replication_factor': '1'} AND durable_writes = true;
CREATE TABLE analytics.users (
id int PRIMARY KEY,
active boolean,
username text
) WITH additional_write_policy = '99p'
AND allow_auto_snapshot = true
AND bloom_filter_fp_chance = 0.01
AND caching = {'keys': 'ALL', 'rows_per_partition': 'NONE'}
AND cdc = false
AND comment = ''
AND compaction = {'class': 'org.apache.cassandra.db.compaction.SizeTieredCompactionStrategy', 'max_threshold': '32', 'min_threshold': '4'}
AND compression = {'chunk_length_in_kb': '16', 'class': 'org.apache.cassandra.io.compress.LZ4Compressor'}
AND memtable = 'default'
AND crc_check_chance = 1.0
AND default_time_to_live = 0
AND extensions = {}
AND gc_grace_seconds = 864000
AND incremental_backups = true
AND max_index_interval = 2048
AND memtable_flush_period_in_ms = 0
AND min_index_interval = 128
AND read_repair = 'BLOCKING'
AND speculative_retry = '99p';
저장소 복제
Spanner Cassandra 스키마 도구를 활용하려면 다음 단계에서 도구의 소스 코드를 가져와야 합니다. GitHub에 호스팅된 저장소를 클론하면 됩니다. Cloud Shell에 다음 명령어를 입력하여 GitHub에서 Spanner Cassandra 스키마 도구를 클론합니다.
git clone https://github.com/cloudspannerecosystem/spanner-cassandra-schema-tool.git
그런 다음 명령어를 실행할 'spanner-cassandra-schema-tool' 디렉터리로 변경합니다.
cd spanner-cassandra-schema-tool
종속 항목 설치
Spanner Cassandra 스키마 도구는 Go 프로그래밍 언어로 작성됩니다. 이 도구는 올바르게 작동하기 위해 특정 외부 Go 모듈 (라이브러리)을 사용합니다. 도구를 실행하려면 이러한 종속 항목을 다운로드하고 관리해야 합니다. spanner-cassandra-schema-tool 디렉터리 내에서 다음 명령어를 실행합니다.
go mod download
Google Cloud 사용자 인증 정보 설정
이 도구는 Spanner 데이터베이스에 연결하기 위한 사용자 인증 정보 소스로 애플리케이션 기본 사용자 인증 정보 (ADC)를 사용합니다. GOOGLE_APPLICATION_CREDENTIALS 환경 변수를 서비스 계정 키 파일의 경로로 설정합니다.
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/service-account-file.json"
/path/to/your/service-account-file.json을 다운로드한 서비스 계정 키 파일의 실제 경로로 바꿉니다. 이 환경 변수를 설정하면 Spanner Cassandra 스키마 도구가 Google Cloud 프로젝트 및 Spanner 인스턴스와 안전하게 인증할 수 있습니다.
사용
종속 항목이 설치되고 Google Cloud 사용자 인증 정보가 구성되면 Spanner Cassandra 스키마 도구를 실행하여 내보낸 Cassandra 스키마 파일에서 Spanner 스키마를 생성할 수 있습니다. 터미널 또는 Cloud Shell에서 spanner-cassandra-schema-tool 디렉터리로 이동하여 다음 go run 명령어를 실행합니다.
go run schema_converter.go \
--project $PROJECT_ID \
--instance $SPANNER_INSTANCE_ID \
--database $SPANNER_DATABASE \
--cql orig_schema.cql \
--dry-run
--dry-run 옵션으로 실행하면 스키마만 생성됩니다. 도구에서 생성한 데이터 유형 매핑 및 기본 키 열을 검토하고 미세 조정합니다. Spanner 데이터 유형이 해당 Cassandra 데이터베이스 유형의 범위, 정밀도, 시맨틱을 정확하게 나타내는지 확인합니다.
이 도구는 지원되는 Cassandra 데이터 유형에 설명된 대로 Cassandra 유형을 Spanner 유형에 매핑합니다.
명령어 출력은 다음과 같이 표시됩니다.
.....
[Converted Spanner statement]
CREATE TABLE users (
id INT64 NOT NULL OPTIONS (cassandra_type = 'int'),
active BOOL OPTIONS (cassandra_type = 'boolean'),
username STRING(MAX) OPTIONS (cassandra_type = 'text'),
) PRIMARY KEY (id)
----------------------------------------------
Writing converted Spanner schema to: schema.txt
Dry run enabled. Skipping schema execution.
Schema conversion completed!
스키마 적용을 Spanner에 자동으로 적용하려면 --dry-run 옵션 없이 CLI를 실행해야 합니다.
Google Cloud 콘솔에서 테이블과 메타데이터 테이블이 Cloud Spanner 데이터베이스에 있는지 확인합니다.
6. 수신 데이터의 이중 쓰기 설정
[TODO]
7. 이전 데이터 일괄 내보내기
[TODO]
8. 데이터 유효성 검사
[TODO]
9. 애플리케이션이 Spanner를 가리키도록 설정 (전환)
마이그레이션 단계 후 데이터의 정확성과 무결성을 꼼꼼하게 검증한 후에는 애플리케이션의 운영 중점을 기존 Cassandra 시스템에서 새로 채워진 Google Cloud Spanner 데이터베이스로 전환하는 것이 중요합니다. 이 중요한 전환 기간을 일반적으로 '전환'이라고 합니다.
전환 단계는 실시간 애플리케이션 트래픽이 원래 Cassandra 클러스터에서 리디렉션되어 강력하고 확장 가능한 Spanner 인프라에 직접 연결되는 순간을 나타냅니다. 이 전환은 특히 Spanner Cassandra 인터페이스를 활용할 때 애플리케이션이 Spanner의 기능을 얼마나 쉽게 활용할 수 있는지 보여줍니다.
Spanner Cassandra 인터페이스를 사용하면 전환 프로세스가 간소화됩니다. 여기에는 기본적으로 모든 데이터 상호작용에 네이티브 Spanner Cassandra 클라이언트를 활용하도록 클라이언트 애플리케이션을 구성하는 작업이 포함됩니다. 애플리케이션은 Cassandra (소스) 데이터베이스와 통신하는 대신 Spanner (타겟)에 직접 데이터를 읽고 쓰기 시작합니다. 이러한 연결의 근본적인 변화는 일반적으로 Spanner 인스턴스에 대한 연결 설정을 용이하게 하는 Spanner Cassandra 클라이언트 라이브러리의 핵심 구성요소인 SpannerCqlSessionBuilder를 사용하여 이루어집니다. 이렇게 하면 애플리케이션의 전체 데이터 트래픽 흐름이 Spanner로 효과적으로 라우팅됩니다.
이미 cassandra-java-driver 라이브러리를 사용하는 Java 애플리케이션의 경우 Spanner Cassandra Java 클라이언트를 통합하려면 CqlSession 초기화를 약간만 변경하면 됩니다.
google-cloud-spanner-cassandra 종속 항목 가져오기
Spanner Cassandra 클라이언트를 사용하려면 먼저 종속 항목을 프로젝트에 통합해야 합니다. google-cloud-spanner-cassandra 아티팩트는 Maven Central의 그룹 ID com.google.cloud에 게시됩니다. Java 프로젝트의 기존 <dependencies> 섹션 아래에 다음과 같은 새 종속 항목을 추가합니다. 다음은 google-cloud-spanner-cassandra 종속 항목을 포함하는 방법을 보여주는 간단한 예입니다.
<!-- native Spanner Cassandra Client -->
<dependencies>
<dependency>
<groupId>com.google.cloud</groupId>
<artifactId>google-cloud-spanner-cassandra</artifactId>
<version>0.2.0</version>
</dependency>
</dependencies>
Spanner에 연결하도록 연결 구성 변경
필요한 종속 항목을 추가한 후에는 Spanner 데이터베이스에 연결하도록 연결 구성을 변경해야 합니다.
Cassandra 클러스터와 상호작용하는 일반적인 애플리케이션은 연결을 설정하기 위해 다음과 유사한 코드를 사용하는 경우가 많습니다.
CqlSession session = CqlSession.builder()
.addContactPoint(new InetSocketAddress("127.0.0.1", 9042))
.withLocalDatacenter("datacenter1")
.withAuthCredentials("username", "password")
.build();
이 연결을 Spanner로 리디렉션하려면 CqlSession 생성 로직을 수정해야 합니다. cassandra-java-driver의 표준 CqlSessionBuilder를 직접 사용하는 대신 Spanner Cassandra 클라이언트에서 제공하는 SpannerCqlSession.builder()를 활용합니다. 다음은 연결 코드를 수정하는 방법을 보여주는 예입니다.
String databaseUri = "projects/<your-gcp-project>/instances/<your-spanner-instance>/databases/<your-spanner-database>";
CqlSession session = SpannerCqlSession.builder()
.setDatabaseUri(databaseUri)
.addContactPoint(new InetSocketAddress("localhost", 9042))
.withLocalDatacenter("datacenter1")
.build();
SpannerCqlSession.builder()를 사용하여 CqlSession를 인스턴스화하고 올바른 databaseUri를 제공하면 애플리케이션이 Spanner Cassandra 클라이언트를 통해 대상 Spanner 데이터베이스에 연결됩니다. 이 중요한 변경사항을 통해 애플리케이션에서 실행하는 후속 읽기 및 쓰기 작업이 모두 Spanner로 전달되고 Spanner에서 제공되므로 초기 전환이 효과적으로 완료됩니다. 이제 애플리케이션이 Spanner의 확장성과 안정성을 기반으로 예상대로 계속 작동합니다.
내부 작동 방식: Spanner Cassandra 클라이언트의 작동 방식
Spanner Cassandra 클라이언트는 로컬 TCP 프록시 역할을 하여 드라이버 또는 클라이언트 도구에서 전송한 원시 Cassandra 프로토콜 바이트를 가로챕니다. 그런 다음 Spanner와 통신하기 위해 이러한 바이트를 필요한 메타데이터와 함께 gRPC 메시지로 래핑합니다. Spanner의 응답은 Cassandra 와이어 형식으로 다시 변환되어 출처 드라이버 또는 도구로 다시 전송됩니다.
Spanner가 모든 트래픽을 올바르게 제공한다고 확신하면 다음과 같은 작업을 할 수 있습니다.
- 이중 쓰기를 중지합니다.
- 원래 Cassandra 클러스터를 사용 중단합니다.
10. 정리 (선택사항)
정리하려면 Cloud Console의 Spanner 섹션으로 이동하여 Codelab에서 만든 cassandra-adapter-demo 인스턴스를 삭제하면 됩니다.
Cassandra 데이터베이스 삭제 (로컬에 설치되었거나 지속되는 경우)
여기에서 만든 Compute Engine VM 외부에 Cassandra를 설치한 경우 적절한 단계에 따라 데이터를 삭제하거나 Cassandra를 제거합니다.