Menggunakan klien Java Cassandra untuk terhubung ke Spanner Omni

Pratinjau

Produk atau fitur ini adalah penawaran pratinjau yang tunduk pada "Persyaratan Penawaran Pra-GA" di bagian Persyaratan Layanan Umum di Persyaratan Khusus Layanan, dan hanya dapat digunakan untuk tujuan pengembangan, pengujian, pembuatan prototipe, dan demonstrasi program software. Produk atau fitur ini tidak dapat digunakan untuk tujuan pemrosesan data atau komersial apa pun. Produk dan fitur pra-GA tersedia "sebagaimana adanya" dan mungkin memiliki dukungan terbatas. Untuk mengetahui informasi selengkapnya, lihat deskripsi tahap peluncuran.

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

Karena Spanner secara native mendukung protokol wire Cassandra v4, klien Java Cassandra Spanner menerjemahkan protokol wire 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 untuk 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:

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

• Menggunakan 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 untuk aplikasi Java agar terhubung ke Spanner Omni. Dibandingkan dengan metode proxy sidecar, konfigurasi dalam proses memberikan performa yang lebih baik dengan menghindari hop jaringan tambahan dan serialisasi serta deserialisasi data terkait. Konfigurasi ini juga menyederhanakan arsitektur deployment Anda dengan menghilangkan kebutuhan untuk mengelola proses mandiri yang terpisah.

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

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

2. Tambahkan klien Java Cassandra Spanner sebagai dependensi ke project Anda.

   Komunikasi 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())
       .setExperimentalHostEndpoint("ENDPOINT")
     .setUsePlainText(true)
           .build();
   
   // Rest of your business logic such as session.Query(SELECT * FROM ...)
   
   session.close();
   

   Koneksi TLS

   Untuk menggunakan koneksi TLS, pastikan sertifikat CA ditambahkan ke truststore yang digunakan oleh aplikasi seperti yang disebutkan dalam petunjuk TLS 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())
       .setExperimentalHostEndpoint("ENDPOINT")
     .setUsePlainText(false)
           .build();
   
   // Rest of your business logic such as session.Query(SELECT * FROM ...)
   
   session.close();
   

   Koneksi mTLS

   Untuk menggunakan koneksi mTLS, pastikan sertifikat CA ditambahkan ke truststore yang digunakan oleh aplikasi dan kunci klien dalam format PKCS#8 seperti yang disebutkan dalam 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())
       .setExperimentalHostEndpoint("ENDPOINT")
     .setUsePlainText(false)
     .useClientCert("PATH_TO_CLIENT_CERT",
             "PATH_TO_CLIENT_KEY_PKCS8")
   
           .build();
   
   // Rest of your business logic such as session.Query(SELECT * FROM ...)
   
   session.close();
   

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, agar terhubung ke Spanner Omni menggunakan driver Cassandra standar. Metode ini menjalankan klien sebagai proxy TCP mandiri yang mencegat traffic protokol wire 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 adapter. 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"
  experimentalHostEndpoint: "ENDPOINT"
  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.

Untuk satu pemroses, Anda dapat menggunakan properti sistem. Contoh berikut menunjukkan cara menjalankan proxy sidecar sebagai proses mandiri untuk setiap mode keamanan yang didukung:

Komunikasi teks biasa

Untuk komunikasi teks biasa, jalankan perintah berikut:

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

Koneksi TLS

Untuk koneksi TLS, jalankan perintah berikut:

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

Koneksi mTLS

Untuk koneksi mTLS, jalankan perintah berikut:

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