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 komunikasi 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. Interceptor 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 suka terus menggunakan gocql API yang sudah dikenal untuk akses data.

  • Gunakan 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 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. Daripada menggunakan gocql.NewCluster, gunakan spanner.NewCluster dan berikan opsi khusus Spanner Omni berikut:

    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.SpannerEndpoint = "ENDPOINT"
  opts.InstanceType = spanner.Omni
  opts.UsePlainText = true

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

    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.SpannerEndpoint = "ENDPOINT"
  opts.InstanceType = spanner.Omni
  opts.CaCertificate = "PATH_TO_CA_CRT"

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

    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.SpannerEndpoint = "ENDPOINT"
  opts.InstanceType = spanner.Omni
  opts.CaCertificate = "PATH_TO_CA_CRT"
  opts.ClientCertificate = "PATH_TO_CLIENT_CERT"
  opts.ClientKey = "PATH_TO_CLIENT_KEY"

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

    Ganti kode berikut:

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

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

    • PATH_TO_CA_CRT: jalur ke file sertifikat CA Anda.

    • PATH_TO_CLIENT_CERT: jalur ke file sertifikat klien Anda.

    • PATH_TO_CLIENT_KEY: jalur ke file kunci klien Anda.

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 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 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:

    Teks biasa

    Untuk menjalankan dengan komunikasi teks biasa, jalankan perintah berikut:

    go run cassandra_launcher.go -db DATABASE_ID -endpoint ENDPOINT -instanceType OMNI -usePlainText

    TLS

    Untuk menjalankan dengan koneksi TLS, jalankan perintah berikut:

    go run cassandra_launcher.go -db DATABASE_ID -endpoint ENDPOINT -instanceType OMNI -caCertificate PATH_TO_CA_CRT

    mTLS

    Untuk menjalankan dengan koneksi mTLS, jalankan perintah berikut:

    go run cassandra_launcher.go -db DATABASE_ID -endpoint ENDPOINT -instanceType OMNI -caCertificate PATH_TO_CA_CRT -clientCertificate PATH_TO_CLIENT_CERT -clientKey PATH_TO_CLIENT_KEY

Menjalankan dengan image Docker bawaan

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 image dengan flag yang diperlukan:

    Teks biasa

    Untuk menjalankan dengan komunikasi teks biasa, jalankan perintah berikut:

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

    TLS

    Untuk menjalankan dengan koneksi TLS, jalankan perintah berikut:

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

    mTLS

    Untuk menjalankan dengan koneksi mTLS, jalankan perintah berikut:

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