Menggunakan klien Java Cassandra untuk terhubung ke Spanner Omni

Klien Java Cassandra untuk Spanner menghubungkan aplikasi yang ditulis untuk database Apache Cassandra dengan Spanner. Klien bekerja dengan Spanner Omni dengan cara yang sama seperti saat bekerja dengan Spanner.

Karena Spanner secara native mendukung protokol komunikasi Cassandra v4, klien Java Cassandra Spanner menerjemahkan protokol komunikasi Cassandra ke Spanner gRPC API. Hal ini memungkinkan Anda memigrasikan aplikasi Cassandra ke Spanner dengan perubahan kode minimal.

Dokumen ini menunjukkan cara mengintegrasikan klien dengan Spanner Omni menggunakan salah satu metode berikut:

  • Dependensi dalam proses: Gunakan metode ini untuk aplikasi Java yang sudah menggunakan cassandra-java-driver. Pendekatan ini menyematkan klien dalam proses aplikasi Anda dengan modifikasi kode minimal.

  • Proxy sidecar: Gunakan metode ini untuk aplikasi non-Java atau saat menggunakan alat Cassandra eksternal, seperti cqlsh. Pendekatan ini menjalankan klien sebagai proses mandiri.

Untuk mengetahui informasi selengkapnya, lihat Antarmuka Cassandra di dokumentasi Spanner.

Kapan harus menggunakan klien Java Cassandra Spanner

Klien ini berguna dalam skenario berikut:

  • Gunakan Spanner dengan refaktorisasi minimal. Anda ingin menggunakan Spanner sebagai backend untuk aplikasi Java, tetapi lebih memilih untuk terus menggunakan cassandra-java-driver API yang sudah dikenal untuk akses data.

  • Gunakan alat Cassandra non-Java. Anda ingin terhubung ke Spanner menggunakan alat Cassandra standar seperti cqlsh atau aplikasi yang ditulis dalam bahasa lain yang menggunakan driver Cassandra.

Menggunakan klien sebagai dependensi dalam proses

Mengintegrasikan klien Java Cassandra Spanner sebagai dependensi dalam proses adalah metode yang direkomendasikan bagi aplikasi Java untuk terhubung ke Spanner Omni. Dibandingkan dengan metode proxy sidecar, konfigurasi dalam proses memberikan performa yang lebih baik dengan menghindari hop jaringan tambahan serta serialisasi dan deserialisasi data terkait. Selain itu, arsitektur deployment Anda juga disederhanakan karena Anda tidak perlu mengelola proses mandiri yang terpisah.

Untuk menggunakan klien sebagai dependensi dalam proses, lakukan hal berikut:

  1. Tambahkan klien Java Spanner Cassandra sebagai dependensi ke project Anda:

    <dependency>
  <groupId>com.google.cloud</groupId>
  <artifactId>google-cloud-spanner-cassandra</artifactId>
  <version>1.2.0</version>
</dependency>

  2. Ubah kode pembuatan CqlSession dan tambahkan opsi khusus komunikasi Spanner Omni:

    Teks biasa

    Contoh berikut menunjukkan cara membuat koneksi teks biasa ke Spanner Omni:

    CqlSession session =
    SpannerCqlSession.builder() // `SpannerCqlSession` instead of `CqlSession`
        .setDatabaseUri("DATABASE_ID") // Required: Specify the Spanner database name
        .withConfigLoader(
            DriverConfigLoader.programmaticBuilder()
                .withString(DefaultDriverOption.PROTOCOL_VERSION, "V4")
                .withDuration(
                    DefaultDriverOption.CONNECTION_INIT_QUERY_TIMEOUT,
                    Duration.ofSeconds(5))
                .build())
        .setHost("ENDPOINT")
        .setInstanceType(SpannerCqlSessionBuilder.InstanceType.OMNI)
        .setUsePlainText(true)
        .build();

// Rest of your business logic such as session.Query(SELECT * FROM ...)

session.close();

    TLS

    Untuk menggunakan koneksi TLS, pastikan sertifikat CA ditambahkan ke truststore yang digunakan oleh aplikasi, seperti yang dijelaskan dalam Mengonfigurasi truststore Java:

    CqlSession session =
    SpannerCqlSession.builder() // `SpannerCqlSession` instead of `CqlSession`
        .setDatabaseUri("DATABASE_ID") // Required: Specify the Spanner database name
        .withConfigLoader(
            DriverConfigLoader.programmaticBuilder()
                .withString(DefaultDriverOption.PROTOCOL_VERSION, "V4")
                .withDuration(
                    DefaultDriverOption.CONNECTION_INIT_QUERY_TIMEOUT,
                    Duration.ofSeconds(5))
                .build())
        .setHost("ENDPOINT")
        .setInstanceType(SpannerCqlSessionBuilder.InstanceType.OMNI)
        .setUsePlainText(false)
        .build();

// Rest of your business logic such as session.Query(SELECT * FROM ...)

session.close();

    mTLS

    Untuk menggunakan koneksi mTLS, pastikan sertifikat CA ditambahkan ke truststore yang digunakan oleh aplikasi dan kunci klien dalam format PKCS#8. Untuk mengetahui informasi selengkapnya, lihat petunjuk mTLS Java SDK.

    CqlSession session =
    SpannerCqlSession.builder() // `SpannerCqlSession` instead of `CqlSession`
        .setDatabaseUri("DATABASE_ID") // Required: Specify the Spanner database name
        .withConfigLoader(
            DriverConfigLoader.programmaticBuilder()
                .withString(DefaultDriverOption.PROTOCOL_VERSION, "V4")
                .withDuration(
                    DefaultDriverOption.CONNECTION_INIT_QUERY_TIMEOUT,
                    Duration.ofSeconds(5))
                .build())
        .setHost("ENDPOINT")
        .setInstanceType(SpannerCqlSessionBuilder.InstanceType.OMNI)
        .setUsePlainText(false)
        .setClientCertPathAndKey(
            "PATH_TO_CLIENT_CERT",
            "PATH_TO_CLIENT_KEY_PKCS8")
        .build();

// Rest of your business logic such as session.Query(SELECT * FROM ...)

  session.close();

    Ganti kode berikut:

    • DATABASE_ID: ID database Spanner Omni Anda, misalnya, test-db.

    • ENDPOINT: endpoint instance Spanner Omni Anda, misalnya, localhost:15000.

    • PATH_TO_CLIENT_CERT: jalur ke file sertifikat klien Anda.

    • PATH_TO_CLIENT_KEY_PKCS8: jalur ke file kunci pribadi klien Anda dalam format PKCS#8.

Proxy sidecar atau proses mandiri

Men-deploy klien Java Cassandra Spanner sebagai proxy sidecar adalah opsi yang efektif untuk aplikasi dan alat non-Java, seperti cqlsh, untuk terhubung ke Spanner Omni menggunakan driver Cassandra standar. Metode ini menjalankan klien sebagai proxy TCP mandiri yang mencegat traffic protokol kabel Cassandra dan menerjemahkannya ke gRPC untuk komunikasi dengan Spanner Omni.

Anda dapat menjalankan proxy sidecar menggunakan file konfigurasi YAML atau dengan menentukan properti sistem.

Menggunakan file konfigurasi YAML

Untuk penyiapan produksi, sebaiknya gunakan file YAML untuk mengonfigurasi adaptor. Metode ini mendukung beberapa pemroses dan setelan global:

java -DconfigFilePath=PATH_TO_CONFIG_YAML -jar PATH_TO_ADAPTER_JAR

Contoh config.yaml:

globalClientConfigs:
  enableBuiltInMetrics: false
  healthCheckEndpoint: "127.0.0.1:8080"
  spannerEndpoint: "ENDPOINT"
  instanceType: "omni"
  clientCertPath: "PATH_TO_CLIENT_CERT"
  clientKeyPath: "PATH_TO_CLIENT_KEY_PKCS8"
  usePlainText: "false"

listeners:
  - name: "listener_1"
    host: "127.0.0.1"
    port: 9042
    spanner:
      databaseUri: "DATABASE_ID"
      numGrpcChannels: 4
      maxCommitDelayMillis: 5
  - name: "listener_2"
    host: "127.0.0.2"
    port: 9043
    spanner:
      databaseUri: "DATABASE_ID_2"
      numGrpcChannels: 8

Menggunakan properti sistem

Untuk satu pemroses atau deployment yang lebih sederhana, Anda dapat menjalankan proxy sidecar sebagai proses mandiri dan mengonfigurasi setelannya menggunakan properti sistem Java.

Contoh berikut menunjukkan cara menjalankan proxy sidecar sebagai proses mandiri untuk setiap konfigurasi keamanan yang didukung:

Teks biasa

Untuk menjalankan dengan komunikasi teks biasa, jalankan perintah berikut:

java -DdatabaseUri=DATABASE_ID \
-Dhost=127.0.0.1 \
-Dport=9042 \
-DnumGrpcChannels=4 \
-DhealthCheckPort=8080 \
-DspannerEndpoint=ENDPOINT \
-DinstanceType=omni \
-DusePlainText=true \
-jar PATH_TO_ADAPTER_JAR

TLS

Untuk menjalankan dengan koneksi TLS, jalankan perintah berikut:

java -DdatabaseUri=DATABASE_ID \
-Dhost=127.0.0.1 \
-Dport=9042 \
-DnumGrpcChannels=4 \
-DhealthCheckPort=8080 \
-DspannerEndpoint=ENDPOINT \
-DinstanceType=omni \
-jar PATH_TO_ADAPTER_JAR

mTLS

Untuk menjalankan dengan koneksi mTLS, jalankan perintah berikut:

java -DdatabaseUri=DATABASE_ID \
-Dhost=127.0.0.1 \
-Dport=9042 \
-DnumGrpcChannels=4 \
-DhealthCheckPort=8080 \
-DspannerEndpoint=ENDPOINT \
-DinstanceType=omni \
-DclientCertPath=PATH_TO_CLIENT_CERT \
-DclientKeyPath=PATH_TO_CLIENT_KEY_PKCS8 \
-jar PATH_TO_ADAPTER_JAR

Ganti kode berikut:

  • DATABASE_ID: ID database Spanner Omni Anda, misalnya, test-db.

  • ENDPOINT: endpoint instance Spanner Omni Anda, misalnya, localhost:15000.

  • PATH_TO_ADAPTER_JAR: jalur ke file JAR adaptor Cassandra Anda.

  • PATH_TO_CLIENT_CERT: jalur ke file sertifikat klien Anda.

  • PATH_TO_CLIENT_KEY_PKCS8: jalur ke file kunci pribadi klien Anda dalam format PKCS#8.