Cassandra Go クライアントを使用して Spanner Omni に接続する

Spanner 用の Cassandra Go クライアントは、Apache Cassandra データベース用に作成されたアプリケーションを Spanner に接続します。クライアントは、Spanner Omni を Spanner と同じように操作します。Spanner は Cassandra v4 ワイヤ プロトコルをネイティブにサポートしているため、このクライアントを使用すると、gocql ドライバを使用する Go アプリケーションや、cqlsh などの Go 以外のアプリケーションやツールを Spanner データベースに接続できます。

このクライアントはローカル TCP プロキシとして機能します。ドライバまたはクライアント ツールが送信する未加工の Cassandra プロトコル バイトをインターセプトします。次に、これらのバイトと必要なメタデータを gRPC メッセージにラップして、Spanner Omni と通信します。クライアントは、Spanner Omni からのレスポンスを Cassandra ワイヤー形式に変換し、元のドライバまたはツールに送り返します。

このドキュメントでは、次のいずれかの方法を使用してクライアントを Spanner Omni と統合する方法について説明します。

  • インプロセス依存関係: gocql ドライバをすでに使用している Go アプリケーションには、この方法を使用します。このアプローチでは、コードの変更を最小限に抑えるために、クライアントをアプリケーション プロセスに埋め込みます。

  • サイドカー プロキシ: Go 以外のアプリケーションの場合や、cqlsh などの外部 Cassandra ツールを使用する場合は、この方法を使用します。このアプローチでは、クライアントはスタンドアロン プロセスとして実行されます。

Apache Cassandra が Spanner と連携する仕組みについては、Cassandra インターフェースをご覧ください。

Spanner Cassandra Go クライアントを使用するタイミング

このクライアントは、次のようなシナリオで役立ちます。

  • 最小限のリファクタリングで Spanner を使用する。Go アプリケーションのバックエンドとして Spanner を使用したいが、データアクセスには使い慣れた gocql API を引き続き使用したい。

  • Go 以外の Cassandra ツールを使用します。cqlsh などの標準の Cassandra ツールや、Cassandra ドライバを使用する他の言語で記述されたアプリケーションを使用して Spanner に接続する場合。

クライアントをインプロセス依存関係として使用する

Go アプリケーションは、Spanner Cassandra Go クライアントをプロセス内依存関係として統合することで、Spanner Omni に接続します。このアプローチでは、プロキシ ロジックがアプリケーションに直接埋め込まれるため、個別のプロセスが不要になり、デプロイ アーキテクチャが簡素化されます。この構成では、余分なネットワーク ホップやデータの余分なシリアル化と逆シリアル化を回避することで、最適なパフォーマンスも実現します。

クライアントをインプロセス依存関係として使用するには、次の操作を行います。

  • Go アプリケーションで Spanner パッケージをインポートします。

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

  • クラスタ作成コードを変更します。gocql.NewCluster ではなく spanner.NewCluster を使用して、次の Spanner Omni 固有のオプションを指定します。

    書式なしテキスト

    次の例は、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

    次の例は、Spanner Omni への TLS 接続を確立する方法を示しています。

    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

    次の例は、Spanner Omni への mTLS 接続を確立する方法を示しています。

    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)
  // ...
}

    次のように置き換えます。

    • DATABASE_ID: Spanner Omni データベースの ID（例: test-db）。

    • ENDPOINT: Spanner Omni インスタンスのエンドポイント（例: localhost:15000）。

    • PATH_TO_CA_CRT: CA 証明書ファイルのパス。

    • PATH_TO_CLIENT_CERT: クライアント証明書ファイルのパス。

    • PATH_TO_CLIENT_KEY: クライアント キーファイルのパス。

クライアントをサイドカー プロキシとしてデプロイする

Spanner Cassandra Go クライアントをサイドカー プロキシとしてデプロイすることは、cqlsh などの Go 以外のアプリケーションやツールが標準の Cassandra ドライバを使用して Spanner Omni に接続する場合に有効なオプションです。このメソッドは、Cassandra ワイヤ プロトコル トラフィックをインターセプトして Spanner Omni との通信用に gRPC に変換するスタンドアロン TCP プロキシとしてクライアントを実行します。

この構成は、外部の Cassandra ツールを使用する必要がある場合や、アプリケーションのコードを直接変更する必要がない場合に便利です。

サイドカー プロキシは次の方法で実行できます。

Go run コマンドを使用してローカルで実行する

サイドカー プロキシをソースコードからローカル プロセスとして実行すると、アプリケーションとプロキシ構成を迅速に反復処理する開発環境やテスト環境で役立ちます。

  1. リポジトリのクローンを作成します。

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

  2. リポジトリ ディレクトリに移動します。

    cd go-spanner-cassandra

  3. 必要な -db フラグと次の Spanner Omni 固有のフラグを指定して cassandra_launcher.go を実行します。

    書式なしテキスト

    プレーン テキスト通信で実行するには、次のコマンドを実行します。

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

    TLS

    TLS 接続で実行するには、次のコマンドを実行します。

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

    mTLS

    mTLS 接続で実行するには、次のコマンドを実行します。

    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

事前構築済みの Docker イメージで実行する

本番環境では、一貫性のある分離されたランタイム環境が提供されるため、ビルド済みの Docker イメージを使用して、コンテナ化されたアプリケーションとしてサイドカー プロキシを実行することをおすすめします。

  1. 公式レジストリ リポジトリからイメージを pull します。

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

  2. 必要なフラグを指定してイメージを実行します。

    書式なしテキスト

    プレーン テキスト通信で実行するには、次のコマンドを実行します。

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

    TLS

    TLS 接続で実行するには、次のコマンドを実行します。

    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

    mTLS 接続で実行するには、次のコマンドを実行します。

    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