Menggunakan klien Go Cassandra untuk terhubung ke Spanner Omni

Klien Go 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 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. Alat ini mencegat byte protokol Cassandra mentah yang dikirim oleh driver atau alat klien. Kemudian, Spanner Omni membungkus byte dan metadata yang diperlukan ini 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 dengan 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 kerja Apache Cassandra dengan Spanner, lihat Antarmuka Cassandra.

Kapan harus menggunakan Klien Go Cassandra Spanner

Klien ini berguna dalam skenario berikut:

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

  • Menggunakan alat Cassandra non-Google. 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 Spanner Cassandra 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. Gunakan spanner.NewCluster, bukan gocql.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 kabel Cassandra dan menerjemahkannya ke gRPC untuk berkomunikasi 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 Go run

Menjalankan proxy sidecar sebagai proses lokal dari kode sumber berguna untuk lingkungan pengembangan dan pengujian tempat Anda ingin melakukan iterasi 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

Menjalankan dengan image Docker yang telah dibuat sebelumnya

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

  1. Tarik image dari repositori registry resmi:

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

  2. Jalankan gambar 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