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 filaire Cassandra v4, le client Java Spanner Cassandra traduit le protocole filaire Cassandra en API gRPC Spanner. Cela vous permet de migrer vos applications Cassandra vers Spanner avec un minimum de modifications du 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 la section 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 du proxy side-car, la configuration dans le processus offre de meilleures performances en évitant un saut réseau supplémentaire et la sérialisation et la désérialisation des données associées. Il simplifie également l'architecture de votre déploiement en supprimant la nécessité de gérer un processus autonome distinct.

Pour utiliser le client comme dépendance dans le processus, procédez comme suit :

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

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

    Communication en 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())
    .setExperimentalHostEndpoint("ENDPOINT")
  .setUsePlainText(true)
        .build();

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

session.close();

    Connexion TLS

    Pour utiliser une connexion TLS, assurez-vous que le certificat de l'autorité de certification est ajouté au truststore utilisé par l'application, comme indiqué dans les instructions TLS 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())
    .setExperimentalHostEndpoint("ENDPOINT")
  .setUsePlainText(false)
        .build();

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

session.close();

    Connexion mTLS

    Pour utiliser une connexion mTLS, assurez-vous que le certificat de l'autorité de certification est ajouté au truststore utilisé par l'application et que la clé client est au format PKCS#8, comme indiqué dans 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())
    .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();

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 filaire 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"
  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

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.

Pour un seul écouteur, vous pouvez utiliser les propriétés système. Les exemples suivants montrent comment exécuter le proxy side-car en tant que processus autonome pour chaque mode de sécurité compatible :

Communication en texte brut

Pour 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 \
-DexperimentalHostEndpoint=ENDPOINT \
-DusePlainText=true \
-jar PATH_TO_ADAPTER_JAR

Connexion TLS

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

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

Connexion mTLS

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

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