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

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

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

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

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.ExperimentalHost = true
  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.ExperimentalHost = true
  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.ExperimentalHost = true
  opts.CaCertificate = "PATH_TO_CA_CRT"
  opts.ClientCertificate = "PATH_TO_CLIENT_CERT"
  opts.ClientKey = "PATH_TO_CLIENT_KEY"

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

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

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

この構成は、外部の 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 を実行します。-db の値は、Spanner Omni データベース名に置き換えます。

  • 平文による通信の場合は、次を実行します。
go run cassandra_launcher.go -db DATABASE_ID -endpoint ENDPOINT -experimentalHost -usePlainText
  • TLS 接続の場合は、次を実行します。
go run cassandra_launcher.go -db DATABASE_ID -endpoint ENDPOINT -experimentalHost -caCertificate PATH_TO_CA_CRT
  • mTLS 接続の場合は、次を実行します。
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

事前構築済みの 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 -experimentalHost -usePlainText

    TLS 接続

    TLS 接続の場合は、次のコマンドを実行します。

    docker run -d -p 9042:9042 gcr.io/cloud-spanner-adapter/cassandra-adapter -db DATABASE_ID -endpoint ENDPOINT -experimentalHost -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 -experimentalHost -caCertificate PATH_TO_CA_CRT -clientCertificate PATH_TO_CLIENT_CERT -clientKey PATH_TO_CLIENT_KEY