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

Spanner 用の Cassandra Java クライアント は、Apache Cassandra データベース用に作成されたアプリケーションを Spanner に接続します。このクライアントは、Spanner で動作するのと同じように Spanner Omni で動作します。

Spanner は Cassandra v4 ワイヤ プロトコルをネイティブにサポートしているため、Spanner Cassandra Java クライアントは Cassandra ワイヤ プロトコルを Spanner gRPC API に変換します。これにより、コードを最小限に変更して Cassandra アプリケーションを Spanner に移行できます。

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

詳細については、 Spanner ドキュメントの Cassandra インターフェースをご覧ください。

Spanner Cassandra Java クライアントを使用する場合

このクライアントは、次のような場合に便利です。

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

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

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

Spanner Cassandra Java クライアントをプロセス内依存関係として統合することは、Java アプリケーションが Spanner Omni に接続するための推奨 方法です。サイドカー プロキシ方式と比較して、プロセス内構成では、追加のネットワーク ホップと、それに関連するデータのシリアル化とデシリアル化を回避することで、パフォーマンスが向上します。また、個別のスタンドアロン プロセスを管理する必要がなくなるため、デプロイ アーキテクチャが簡素化されます。

クライアントをプロセス内依存関係として使用する手順は次のとおりです。

  1. CqlSession 作成コードを変更し、Spanner Omni 通信固有のオプションを追加します。

  2. Spanner Cassandra Java クライアントを依存関係としてプロジェクトに追加します。

    平文通信

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

    CqlSession session =
    SpannerCqlSession.builder() // `SpannerCqlSession` instead of `CqlSession`
        .setDatabaseUri("DATABASE_ID") // Required: Specify the Spanner database name
        .withConfigLoader(
            DriverConfigLoader.programmaticBuilder()
                .withString(DefaultDriverOption.PROTOCOL_VERSION, "V4")
                .withDuration(
                    DefaultDriverOption.CONNECTION_INIT_QUERY_TIMEOUT,
                    Duration.ofSeconds(5))
                .build())
    .setExperimentalHostEndpoint("ENDPOINT")
  .setUsePlainText(true)
        .build();

// Rest of your business logic such as session.Query(SELECT * FROM ...)

session.close();

    TLS 接続

    TLS 接続を使用するには、Java SDK の TLS の手順で説明されているように、CA 証明書がアプリケーションで使用されるトラストストア に追加されていることを確認します。

    CqlSession session =
    SpannerCqlSession.builder() // `SpannerCqlSession` instead of `CqlSession`
        .setDatabaseUri("DATABASE_ID") // Required: Specify the Spanner database name
        .withConfigLoader(
            DriverConfigLoader.programmaticBuilder()
                .withString(DefaultDriverOption.PROTOCOL_VERSION, "V4")
                .withDuration(
                    DefaultDriverOption.CONNECTION_INIT_QUERY_TIMEOUT,
                    Duration.ofSeconds(5))
                .build())
    .setExperimentalHostEndpoint("ENDPOINT")
  .setUsePlainText(false)
        .build();

// Rest of your business logic such as session.Query(SELECT * FROM ...)

session.close();

    mTLS 接続

    mTLS 接続を使用するには、Java SDK の mTLS の手順で説明されているように、CA 証明書がアプリケーションで使用されるトラストストア に追加され、クライアント キーが PKCS#8 形式であることを確認します。

    CqlSession session =
    SpannerCqlSession.builder() // `SpannerCqlSession` instead of `CqlSession`
        .setDatabaseUri("DATABASE_ID") // Required: Specify the Spanner database name
        .withConfigLoader(
            DriverConfigLoader.programmaticBuilder()
                .withString(DefaultDriverOption.PROTOCOL_VERSION, "V4")
                .withDuration(
                    DefaultDriverOption.CONNECTION_INIT_QUERY_TIMEOUT,
                    Duration.ofSeconds(5))
                .build())
    .setExperimentalHostEndpoint("ENDPOINT")
  .setUsePlainText(false)
  .useClientCert("PATH_TO_CLIENT_CERT",
          "PATH_TO_CLIENT_KEY_PKCS8")

        .build();

// Rest of your business logic such as session.Query(SELECT * FROM ...)

session.close();

サイドカー プロキシまたはスタンドアロン プロセス

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

サイドカー プロキシは、YAML 構成ファイルを使用するか、システム プロパティを指定して実行できます。

YAML 構成ファイルを使用する

本番環境の設定では、YAML ファイルを使用してアダプタを構成することをおすすめします。この方法では、複数のリスナーとグローバル設定がサポートされます。

java -DconfigFilePath=PATH_TO_CONFIG_YAML -jar PATH_TO_ADAPTER_JAR

config.yaml の例:

globalClientConfigs:
  enableBuiltInMetrics: false
  healthCheckEndpoint: "127.0.0.1:8080"
  experimentalHostEndpoint: "ENDPOINT"
  clientCertPath: "PATH_TO_CLIENT_CERT"
  clientKeyPath: "PATH_TO_CLIENT_KEY_PKCS8"
  usePlainText: "false"

listeners:
  - name: "listener_1"
    host: "127.0.0.1"
    port: 9042
    spanner:
      databaseUri: "DATABASE_ID"
      numGrpcChannels: 4
      maxCommitDelayMillis: 5
  - name: "listener_2"
    host: "127.0.0.2"
    port: 9043
    spanner:
      databaseUri: "DATABASE_ID_2"
      numGrpcChannels: 8

システム プロパティを使用する

単一のリスナーまたはシンプルなデプロイの場合は、サイドカー プロキシをスタンドアロン プロセスとして実行し、Java システム プロパティを使用して設定を構成できます。

単一のリスナーの場合は、システム プロパティを使用できます。次の例は、サポートされているセキュリティ モードごとに、サイドカー プロキシをスタンドアロン プロセスとして実行する方法を示しています。

平文通信

平文通信の場合は、次のコマンドを実行します。

java -DdatabaseUri=DATABASE_ID \
-Dhost=127.0.0.1 \
-Dport=9042 \
-DnumGrpcChannels=4 \
-DhealthCheckPort=8080 \
-DexperimentalHostEndpoint=ENDPOINT \
-DusePlainText=true \
-jar PATH_TO_ADAPTER_JAR

TLS 接続

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

java -DdatabaseUri=DATABASE_ID \
-Dhost=127.0.0.1 \
-Dport=9042 \
-DnumGrpcChannels=4 \
-DhealthCheckPort=8080 \
-DexperimentalHostEndpoint=ENDPOINT \
-jar PATH_TO_ADAPTER_JAR

mTLS 接続

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

java -DdatabaseUri=DATABASE_ID \
-Dhost=127.0.0.1 \
-Dport=9042 \
-DnumGrpcChannels=4 \
-DhealthCheckPort=8080 \
-DexperimentalHostEndpoint=ENDPOINT \
-DclientCertPath=PATH_TO_CLIENT_CERT \
-DclientKeyPath=PATH_TO_CLIENT_KEY_PKCS8 \
-jar PATH_TO_ADAPTER_JAR