Migração do Cassandra para o Bigtable com um proxy de gravação dupla

Migração do Cassandra para o Bigtable com um proxy de gravação dupla

Sobre este codelab

subjectÚltimo abr. 15, 2025 atualizado
account_circleEscrito por Louis Cheynel

1. Introdução

O Bigtable é um serviço de banco de dados NoSQL de alto desempenho e totalmente gerenciado, projetado para grandes cargas de trabalho analíticas e operacionais. A migração de bancos de dados existentes, como o Apache Cassandra, para o Bigtable geralmente requer um planejamento cuidadoso para minimizar o tempo de inatividade e o impacto no aplicativo.

Este codelab demonstra uma estratégia de migração do Cassandra para o Bigtable usando uma combinação de ferramentas de proxy:

  1. Cassandra-Bigtable Proxy:permite que clientes e ferramentas do Cassandra (como cqlsh ou drivers) interajam com o Bigtable usando o protocolo Cassandra Query Language (CQL) ao traduzir consultas.
  2. Proxy de migração sem inatividade do Datastax (ZDM, na sigla em inglês):um proxy de código aberto que fica entre o aplicativo e os serviços de banco de dados (origem do Cassandra e Bigtable de destino pelo proxy Cassandra-Bigtable). Ele orquestra gravações duplas e gerencia o roteamento de tráfego, permitindo a migração com o mínimo de mudanças no aplicativo e inatividade.
  3. Cassandra Data Migrator (CDM): uma ferramenta de código aberto usada para migrar dados históricos em massa do cluster de origem do Cassandra para a instância de destino do Bigtable.

O que você vai aprender

  • Como configurar um cluster básico do Cassandra no Compute Engine.
  • Como criar uma instância do Bigtable.
  • Como implantar e configurar o proxy Cassandra-Bigtable para mapear um esquema do Cassandra para o Bigtable.
  • Como implantar e configurar o proxy ZDM do Datastax para gravações duplas.
  • Como usar a ferramenta Cassandra Data Migrator para migrar dados em massa.
  • O fluxo de trabalho geral para uma migração do Cassandra para o Bigtable baseada em proxy.

O que é necessário

  • Ter um projeto do Google Cloud com o faturamento ativado. Novos usuários podem fazer um teste sem custo financeiro.
  • Conhecimento básico dos conceitos do Google Cloud, como projetos, Compute Engine, redes VPC e regras de firewall. Conhecimento básico das ferramentas de linha de comando do Linux.
  • Acesso a uma máquina com a CLI gcloud instalada e configurada ou use o Google Cloud Shell.

Neste codelab, vamos usar principalmente máquinas virtuais (VMs) no Compute Engine na mesma rede e região da VPC para simplificar a rede. É recomendável usar endereços IP internos.

2. Configurar o ambiente

1. Selecionar ou criar um projeto do Google Cloud

Acesse o console do Google Cloud e selecione um projeto ou crie um novo. Anote o ID do projeto.

2. Ativar APIs obrigatórias

Verifique se a API Compute Engine e a API Bigtable estão ativadas no projeto.

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

Substitua pelo ID do seu projeto.

3. Escolha uma região e uma zona

Selecione uma região e uma zona para seus recursos. Usaremos us-central1 e us-central1-c como exemplos. Defina estas variáveis de ambiente para sua conveniência:

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. Configurar regras de firewall

Precisamos permitir a comunicação entre nossas VMs na rede VPC padrão em várias portas:

  • Porta CQL do Cassandra/proxies: 9042
  • Porta de verificação de integridade do proxy do ZDM: 14001
  • SSH: 22

Crie uma regra de firewall para permitir o tráfego interno nessas portas. Vamos usar uma tag cassandra-migration para aplicar essa regra facilmente às VMs relevantes.

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. Implantar o cluster do Cassandra (Origin)

Neste codelab, vamos configurar um cluster Cassandra simples de nó único no Compute Engine. Em um cenário real, você se conectaria ao cluster atual.

1. Criar uma VM do GCE para o Cassandra

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. Instalar o 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. Criar um keyspace e uma tabela

Vamos usar um exemplo de tabela de funcionários e criar um keyspace chamado "zdmbigtable".

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

Dentro do 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;

Deixe a sessão SSH aberta ou anote o endereço IP dessa VM (hostname -I).

4. Configurar o Bigtable (Target)

Duração 0:01

Criar uma instância do Bigtable. Vamos usar zdmbigtable como o ID da instância.

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

A tabela do Bigtable será criada mais tarde pelo script de configuração do proxy Cassandra-Bigtable.

5. Configurar o proxy do Cassandra-Bigtable

1. Criar uma VM do Compute Engine para o proxy Cassandra-Bigtable

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

Conecte-se via SSH à bigtable-proxy-vm:

gcloud compute ssh bigtable-proxy-vm

Na 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. Configurar o proxy

nano config.yaml

Atualize as seguintes variáveis. Para uma configuração mais avançada, use este exemplo fornecido no 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

Salve e feche o arquivo (Ctrl+X, depois Y e Enter no nano).

3. Iniciar o proxy Cassandra-Bigtable

Inicie o servidor proxy.

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

O proxy vai começar e detectar na porta 9042 as conexões CQL recebidas. Mantenha esta sessão do terminal em execução. Anote o endereço IP dessa VM (hostname -I)

4. Criar tabela usando CQL

Conecte cqlsh ao endereço IP da VM do proxy Cassandra-Bigtable.

Em cqlsh, execute o seguinte comando

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

Verifique no console do Google Cloud se a tabela de funcionários e a tabela de metadados existem na sua instância do Bigtable.

6. Configurar o proxy do ZDM

O proxy ZDM requer pelo menos duas máquinas: um ou mais nós de proxy que processam o tráfego e um "jumphost" usado para implantação e orquestração pelo Ansible.

1. Criar VMs do Compute Engine para o proxy ZDM

Precisamos de duas VMs: zdm-proxy-jumphost e 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

Anote os endereços IP das duas VMs.

2. Preparar o jumphost

Conecte-se via SSH ao zdm-jumphost

gcloud compute ssh zdm-jumphost

# Install Git and Ansible

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

Dentro do jumphost

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

cd zdm-proxy-automation/ansible/

Edite o arquivo de configuração principal vars/zdm_proxy_cluster_config.yml:

Atualize os valores de origin_contact_points e target_contact_points com os endereços IP internos da VM do Cassandra e da VM do proxy do Cassandra-Bigtable, respectivamente. Deixe a autenticação comentada, porque não a configuramos.

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

Salve e feche o arquivo.

3. Implantar o proxy do ZDM usando o Ansible

Execute o playbook do Ansible no diretório ansible no jumphost:

ansible-playbook deploy_zdm_proxy.yml -i zdm_ansible_inventory

Esse comando vai instalar o software necessário (como o Docker) no nó de proxy (zdm-proxy-node-1), extrair a imagem do Proxy Docker do ZDM e iniciar o contêiner do proxy com a configuração fornecida.

4. Verificar a integridade do proxy ZDM

Verifique o endpoint de prontidão do proxy ZDM em execução no zdm-proxy-node-1 (porta 14001) do jumphost:

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

A saída será semelhante a esta, indicando que a origem (Cassandra) e o destino (proxy do Cassandra-Bigtable) estão ativos:

{
  "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. Configurar o aplicativo e iniciar gravações duplas

Duração 0:05

Nesta etapa de uma migração real, você reconfiguraria os aplicativos para apontarem para o endereço IP do nó do proxy do ZDM (por exemplo, :9042) em vez de se conectar diretamente ao Cassandra.

Quando o aplicativo se conecta ao proxy ZDM: as leituras são enviadas da origem (Cassandra) por padrão. As gravações são enviadas para a origem (Cassandra) e o destino (Bigtable, pelo proxy Cassandra-Bigtable). Isso permite que o aplicativo continue funcionando normalmente, garantindo que novos dados sejam gravados nos dois bancos de dados simultaneamente. É possível testar a conexão usando o cqlsh apontado para o proxy do ZDM do jumphost ou de outra VM na rede:

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

Tente inserir alguns dados:

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

Esses dados precisam ser gravados no Cassandra e no Bigtable. Para confirmar isso no Bigtable, acesse o console do Google Cloud e abra o editor de consulta do Bigtable para sua instância. Execute uma consulta "SELECT * FROM employee" e os dados inseridos recentemente vão aparecer.

8. Migrar dados históricos usando o Cassandra Data Migrator

Agora que as gravações duplas estão ativas para novos dados, use a ferramenta Cassandra Data Migrator (CDM) para copiar os dados históricos do Cassandra para o Bigtable.

1. Criar uma VM do Compute Engine para o CDM

Essa VM precisa de memória suficiente para o 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. Instalar pré-requisitos (Java 11, Spark)

Use SSH para acessar a cdm-migrator-vm:

gcloud compute ssh cdm-migrator-vm

Na 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. Fazer o download do Cassandra Data Migrator

Faça o download do arquivo jar da ferramenta CDM. Verifique a página de lançamento do GitHub do Cassandra Data Migrator para encontrar o URL correto da versão desejada.

# 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. Configurar o CDM

Crie um arquivo de propriedades chamado cdm.properties

Nano cdm.properties

Cole a configuração a seguir, substituindo os endereços IP e desativando os recursos de TTL/tempo de gravação, já que eles não têm suporte direto do Bigtable. Deixe a autenticação comentada.

# 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

Salve e feche o arquivo.

5. Executar o job de migração

Execute a migração usando o spark-submit. Esse comando instrui o Spark a executar o jar do CDM usando o arquivo de propriedades e especificando o espaço de chaves e a tabela a serem migrados. Ajuste as configurações de memória (–driver-memory, –executor-memory) com base no tamanho da VM e no volume de dados.

Verifique se você está no diretório que contém o jar do CDM e o arquivo de propriedades. Substitua "cassandra-data-migrator-5.2.2.jar" se você tiver feito o download de uma versão diferente.

./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

A migração será executada em segundo plano, e os registros serão gravados em cdm_migration_... .log. Monitore o arquivo de registro para verificar o progresso e os erros:

tail -f cdm_migration_*.log

6. Verificar a migração de dados

Depois que o job do CDM for concluído, verifique se os dados históricos estão no Bigtable. Como o proxy do Cassandra-Bigtable permite leituras de CQL, você pode usar o cqlsh conectado ao proxy do ZDM (que encaminha as leituras para o destino após a migração ou pode ser configurado para isso) ou diretamente para o proxy do Cassandra-Bigtable para consultar os dados. Conectar usando o proxy do ZDM:

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

Dentro do cqlsh:

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

Como alternativa, use a ferramenta cbt (se instalada na VM do CDM ou no Cloud Shell) para procurar dados diretamente no 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. Transição (conceitual)

Depois de verificar completamente a consistência dos dados entre o Cassandra e o Bigtable, você pode prosseguir com a transição final.

Com o proxy ZDM, a transição envolve reconfigurá-lo para ler principalmente do destino (Bigtable) em vez da origem (Cassandra). Isso geralmente é feito pela configuração do proxy do ZDM, transferindo efetivamente o tráfego de leitura do aplicativo para o Bigtable.

Quando tiver certeza de que o Bigtable está veiculando todo o tráfego corretamente, você poderá:

  • Pare as gravações duplas reconfigurando o proxy ZDM.
  • Desative o cluster original do Cassandra.
  • Remova o proxy ZDM e faça com que o aplicativo se conecte diretamente ao proxy Cassandra-Bigtable ou use o cliente CQL Bigtable nativo para Java.

As especificidades da reconfiguração do proxy do ZDM para a transição estão fora do escopo deste codelab básico, mas estão detalhadas na documentação do Datastax ZDM.

10. Limpar

Para evitar cobranças, exclua os recursos criados durante este codelab.

1. Excluir VMs do Compute Engine

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

2. Excluir instância do Bigtable

gcloud bigtable instances delete zdmbigtable

3. Excluir regras de firewall

gcloud compute firewall-rules delete allow-migration-internal

4. Excluir o banco de dados Cassandra (se instalado localmente ou persistido)

Se você instalou o Cassandra fora de uma VM do Compute Engine criada aqui, siga as etapas adequadas para remover os dados ou desinstalar o Cassandra.

11. Parabéns!

Você concluiu o processo de configuração de um caminho de migração baseado em proxy do Apache Cassandra para o Bigtable.

Agora você já sabe:

Implante o Cassandra e o Bigtable.

  • Configure o proxy Cassandra-Bigtable para compatibilidade com CQL.
  • Implante o proxy ZDM do Datastax para gerenciar gravações duplas e tráfego.
  • Use o Cassandra Data Migrator para mover dados históricos.

Essa abordagem permite migrações com o tempo de inatividade mínimo e sem mudanças no código, aproveitando a camada de proxy.

Próximas etapas

  • Acesse a documentação do Bigtable
  • Consulte a documentação do proxy do Datastax ZDM para ver configurações avançadas e procedimentos de transição.
  • Consulte o repositório do proxy Cassandra-Bigtable para mais detalhes.
  • Consulte o repositório do Cassandra Data Migrator para conferir o uso avançado.
  • Teste outros codelabs do Google Cloud
bug_report Informar um erro