Menggunakan klien Go Cassandra untuk terhubung ke Spanner Omni

Klien Cassandra Go 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 ini memungkinkan aplikasi Go yang menggunakan driver gocql, atau aplikasi dan alat non-Go seperti cqlsh, terhubung ke database Spanner.

Klien ini bertindak sebagai proxy TCP lokal. Klien ini mencegat byte protokol Cassandra mentah yang dikirim oleh driver atau alat klien. Kemudian, klien ini menggabungkan byte dan metadata yang diperlukan ke dalam pesan gRPC untuk berkomunikasi dengan Spanner Omni. Klien menerjemahkan respons dari Spanner Omni kembali ke format wire Cassandra dan mengirimkannya kembali ke driver atau alat asal.

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

  • Dependensi dalam proses: Gunakan metode ini untuk aplikasi Go yang sudah menggunakan driver gocql. Pendekatan ini menyematkan klien dalam proses aplikasi Anda untuk modifikasi kode minimal.

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

Untuk mengetahui informasi selengkapnya tentang cara Apache Cassandra berfungsi dengan Spanner, lihat Antarmuka Cassandra.

Kapan harus menggunakan Klien Go Cassandra Spanner

Klien ini berguna dalam skenario berikut:

  • Menggunakan Spanner dengan refactoring minimal. Anda ingin menggunakan Spanner sebagai backend untuk aplikasi Go, tetapi lebih suka terus menggunakan gocql API yang sudah dikenal untuk akses data.

  • Menggunakan alat Cassandra non-Go. 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

Aplikasi Go terhubung ke Spanner Omni dengan mengintegrasikan klien Go Cassandra Spanner sebagai dependensi dalam proses. Pendekatan ini menyematkan logika proxy langsung dalam aplikasi Anda, yang menyederhanakan arsitektur deployment dengan menghilangkan kebutuhan akan proses terpisah. Konfigurasi ini juga memberikan performa optimal dengan menghindari hop jaringan tambahan serta serialisasi dan deserialisasi data tambahan.

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

  • Impor paket Spanner di aplikasi Go Anda:

    import spanner "github.com/googleapis/go-spanner-cassandra/cassandra/gocql"

  • Ubah kode pembuatan cluster Anda. Daripada menggunakan gocql.NewCluster, gunakan spanner.NewCluster dan berikan opsi khusus Spanner Omni berikut:

    Komunikasi teks biasa

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

    func main() {
  opts := &spanner.Options{
      // Required: Specify the Spanner database URI
      DatabaseUri: "DATABASE_ID",
  }
  // Optional: Configure Spanner Omni cluster settings as needed
  opts.ExperimentalHost = true
  opts.UsePlainText = true

  cluster := spanner.NewCluster(opts)
  // ...
}

    Koneksi TLS

    Contoh berikut menunjukkan cara membuat koneksi TLS ke Spanner Omni:

    func main() {
  opts := &spanner.Options{
      // Required: Specify the Spanner database URI
      DatabaseUri: "DATABASE_ID",
  }
  // Optional: Configure Spanner Omni cluster settings as needed
  opts.ExperimentalHost = true
  opts.CaCertificate = "PATH_TO_CA_CRT"

  cluster := spanner.NewCluster(opts)
  // ...
}

    Koneksi mTLS

    Contoh berikut menunjukkan cara membuat koneksi mTLS ke Spanner Omni:

    func main() {
  opts := &spanner.Options{
      // Required: Specify the Spanner database URI
      DatabaseUri: "DATABASE_ID",
  }
  // Optional: Configure Spanner Omni cluster settings as needed
  opts.ExperimentalHost = true
  opts.CaCertificate = "PATH_TO_CA_CRT"
  opts.ClientCertificate = "PATH_TO_CLIENT_CERT"
  opts.ClientKey = "PATH_TO_CLIENT_KEY"

  cluster := spanner.NewCluster(opts)
  // ...
}

Men-deploy klien sebagai proxy sidecar

Men-deploy klien Go Cassandra Spanner sebagai proxy sidecar adalah opsi yang efektif untuk aplikasi dan alat non-Go, seperti cqlsh, untuk 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.

Konfigurasi ini berguna saat Anda perlu menggunakan alat Cassandra eksternal atau saat Anda perlu menghindari modifikasi langsung pada kode aplikasi.

Anda dapat menjalankan proxy sidecar dengan cara berikut:

Jalankan secara lokal dengan perintah run Go

Menjalankan proxy sidecar sebagai proses lokal dari kode sumber berguna untuk lingkungan pengembangan dan pengujian tempat Anda ingin melakukan iterasi dengan cepat pada konfigurasi aplikasi dan proxy.

  1. Buat clone repositori:

    git clone https://github.com/googleapis/go-spanner-cassandra.git

  2. Ubah menjadi direktori repositori:

    cd go-spanner-cassandra

  3. Jalankan cassandra_launcher.go dengan flag -db yang diperlukan dan flag khusus Spanner Omni berikut. Ganti nilai -db dengan nama database Spanner Omni Anda:

  • Untuk komunikasi teks biasa, jalankan perintah berikut:
go run cassandra_launcher.go -db DATABASE_ID -endpoint ENDPOINT -experimentalHost -usePlainText
  • Untuk koneksi TLS, jalankan perintah berikut:
go run cassandra_launcher.go -db DATABASE_ID -endpoint ENDPOINT -experimentalHost -caCertificate PATH_TO_CA_CRT
  • Untuk koneksi mTLS, jalankan perintah berikut:
go run cassandra_launcher.go -db DATABASE_ID -endpoint ENDPOINT -experimentalHost -caCertificate PATH_TO_CA_CRT -clientCertificate PATH_TO_CLIENT_CERT -clientKey PATH_TO_CLIENT_KEY

Jalankan dengan image Docker bawaan

Sebaiknya jalankan proxy sidecar sebagai aplikasi dalam container menggunakan image Docker bawaan untuk lingkungan produksi karena memberikan lingkungan runtime yang konsisten dan terisolasi.

  1. Tarik image dari repositori registry resmi:

    docker pull gcr.io/cloud-spanner-adapter/cassandra-adapter

  2. Jalankan image dengan flag yang diperlukan:

    Komunikasi teks biasa

    Untuk komunikasi teks biasa, jalankan perintah berikut:

    docker run -d -p 9042:9042 gcr.io/cloud-spanner-adapter/cassandra-adapter -db DATABASE_ID -endpoint ENDPOINT -experimentalHost -usePlainText

    Koneksi TLS

    Untuk koneksi TLS, jalankan perintah berikut:

    docker run -d -p 9042:9042 gcr.io/cloud-spanner-adapter/cassandra-adapter -db DATABASE_ID -endpoint ENDPOINT -experimentalHost -caCertificate PATH_TO_CA_CRT

    Koneksi mTLS

    Untuk koneksi mTLS, jalankan perintah berikut:

    docker run -d -p 9042:9042 gcr.io/cloud-spanner-adapter/cassandra-adapter -db DATABASE_ID -endpoint ENDPOINT -experimentalHost -caCertificate PATH_TO_CA_CRT -clientCertificate PATH_TO_CLIENT_CERT -clientKey PATH_TO_CLIENT_KEY