Utiliser le client Java Cassandra pour se connecter à Spanner Omni

Le client Java Cassandra pour Spanner connecte les applications écrites pour la base de données Apache Cassandra à Spanner. Le client fonctionne avec Spanner Omni de la même manière qu'avec Spanner.

Comme Spanner est compatible en mode natif avec le protocole de communication Cassandra v4, le client Java Spanner Cassandra traduit le protocole de communication Cassandra en API gRPC Spanner. Cela vous permet de migrer vos applications Cassandra vers Spanner avec un minimum de modifications de code.

Ce document explique comment intégrer le client à Spanner Omni à l'aide de l'une des méthodes suivantes :

  • Dépendance dans le processus : utilisez cette méthode pour les applications Java qui utilisent déjà cassandra-java-driver. Cette approche intègre le client dans le processus de votre application pour un minimum de modifications du code.

  • Proxy side-car : utilisez cette méthode pour les applications non Java ou lorsque vous utilisez des outils Cassandra externes, tels que cqlsh. Cette approche exécute le client en tant que processus autonome.

Pour en savoir plus, consultez Interface Cassandra dans la documentation Spanner.

Quand utiliser le client Java Spanner Cassandra

Ce client est utile dans les scénarios suivants :

  • Utilisez Spanner avec un refactoring minimal. Vous souhaitez utiliser Spanner comme backend pour votre application Java, mais vous préférez continuer à utiliser l'API cassandra-java-driver que vous connaissez bien pour accéder aux données.

  • Utilisez des outils Cassandra non Java. Vous souhaitez vous connecter à Spanner à l'aide d'outils Cassandra standards tels que cqlsh ou d'applications écrites dans d'autres langages qui utilisent des pilotes Cassandra.

Utiliser le client comme dépendance dans le processus

L'intégration du client Java Spanner Cassandra en tant que dépendance dans le processus est la méthode recommandée pour que les applications Java se connectent à Spanner Omni. Par rapport à la méthode de proxy side-car, la configuration dans le processus offre de meilleures performances en évitant un saut de réseau supplémentaire et la sérialisation et la désérialisation des données associées. Il simplifie également votre architecture de déploiement en supprimant la nécessité de gérer un processus autonome distinct.

Pour utiliser le client comme dépendance intégrée, procédez comme suit :

  1. Ajoutez le client Java Spanner Cassandra en tant que dépendance à votre projet :

    <dependency>
  <groupId>com.google.cloud</groupId>
  <artifactId>google-cloud-spanner-cassandra</artifactId>
  <version>1.2.0</version>
</dependency>

  2. Modifiez votre code de création CqlSession et ajoutez les options spécifiques à la communication Spanner Omni :

    Texte brut

    L'exemple suivant montre comment établir une connexion en texte brut à 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())
        .setHost("ENDPOINT")
        .setInstanceType(SpannerCqlSessionBuilder.InstanceType.OMNI)
        .setUsePlainText(true)
        .build();

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

session.close();

    TLS

    Pour utiliser une connexion TLS, assurez-vous que le certificat CA est ajouté au truststore utilisé par l'application, comme décrit dans Configurer le truststore Java :

    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())
        .setHost("ENDPOINT")
        .setInstanceType(SpannerCqlSessionBuilder.InstanceType.OMNI)
        .setUsePlainText(false)
        .build();

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

session.close();

    mTLS

    Pour utiliser une connexion mTLS, assurez-vous que le certificat CA est ajouté au truststore utilisé par l'application et que la clé client est au format PKCS#8. Pour en savoir plus, consultez les instructions mTLS du SDK Java.

    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())
        .setHost("ENDPOINT")
        .setInstanceType(SpannerCqlSessionBuilder.InstanceType.OMNI)
        .setUsePlainText(false)
        .setClientCertPathAndKey(
            "PATH_TO_CLIENT_CERT",
            "PATH_TO_CLIENT_KEY_PKCS8")
        .build();

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

  session.close();

    Remplacez les éléments suivants :

    • DATABASE_ID : ID de votre base de données Spanner Omni (par exemple, test-db).

    • ENDPOINT : point de terminaison de votre instance Spanner Omni, par exemple localhost:15000.

    • PATH_TO_CLIENT_CERT : chemin d'accès à votre fichier de certificat client.

    • PATH_TO_CLIENT_KEY_PKCS8 : chemin d'accès au fichier de clé privée de votre client au format PKCS#8.

Proxy side-car ou processus autonome

Le déploiement du client Java Spanner Cassandra en tant que proxy side-car est une option efficace pour les applications et outils non Java, tels que cqlsh, afin de se connecter à Spanner Omni à l'aide de pilotes Cassandra standards. Cette méthode exécute le client en tant que proxy TCP autonome qui intercepte le trafic du protocole de communication Cassandra et le traduit en gRPC pour la communication avec Spanner Omni.

Vous pouvez exécuter le proxy side-car à l'aide d'un fichier de configuration YAML ou en spécifiant des propriétés système.

Utiliser un fichier de configuration YAML

Pour les configurations de production, nous vous recommandons d'utiliser un fichier YAML pour configurer l'adaptateur. Cette méthode est compatible avec plusieurs écouteurs et paramètres généraux :

java -DconfigFilePath=PATH_TO_CONFIG_YAML -jar PATH_TO_ADAPTER_JAR

Exemple config.yaml :

globalClientConfigs:
  enableBuiltInMetrics: false
  healthCheckEndpoint: "127.0.0.1:8080"
  spannerEndpoint: "ENDPOINT"
  instanceType: "omni"
  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

Utiliser les propriétés système

Pour un seul écouteur ou des déploiements plus simples, vous pouvez exécuter le proxy side-car en tant que processus autonome et configurer ses paramètres à l'aide des propriétés système Java.

Les exemples suivants montrent comment exécuter le proxy side-car en tant que processus autonome pour chaque configuration de sécurité compatible :

Texte brut

Pour exécuter la communication en texte brut, exécutez la commande suivante :

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

TLS

Pour exécuter une connexion TLS, exécutez la commande suivante :

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

mTLS

Pour exécuter avec une connexion mTLS, exécutez la commande suivante :

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

Remplacez les éléments suivants :

  • DATABASE_ID : ID de votre base de données Spanner Omni, par exemple test-db.

  • ENDPOINT : point de terminaison de votre instance Spanner Omni, par exemple localhost:15000.

  • PATH_TO_ADAPTER_JAR : chemin d'accès à votre fichier JAR de l'adaptateur Cassandra.

  • PATH_TO_CLIENT_CERT : chemin d'accès à votre fichier de certificat client.

  • PATH_TO_CLIENT_KEY_PKCS8 : chemin d'accès au fichier de clé privée du client au format PKCS#8.