Utiliser Apache Beam et SpannerIO pour se connecter à Spanner Omni

Apache Beam est un modèle unifié Open Source permettant de définir des pipelines de traitement parallèle des données par lots et en streaming. Ce document explique comment utiliser le connecteur SpannerIO dans un pipeline Apache Beam pour lire ou écrire des données dans des bases de données Spanner Omni.

Avant de commencer

Pour connecter SpannerIO à Spanner Omni, assurez-vous de répondre aux exigences suivantes :

  • Initialisez une base de données dans votre environnement Spanner Omni.

  • Si vous utilisez le chiffrement, assurez-vous d'utiliser une version compatible d'Apache Beam :

    • Pour le chiffrement TLS, version 2.69.0 ou ultérieure.
    • Pour le chiffrement TLS mutuel (mTLS), version 2.75.0 ou ultérieure.

  • Configurez les identifiants d'authentification pour votre environnement.

Configurer SpannerIO pour se connecter à Spanner Omni

Pour connecter SpannerIO à Spanner Omni, configurez SpannerConfig avec les détails de votre base de données et les paramètres de connexion.

Pour configurer la connexion, choisissez l'un des modes de connexion suivants :

Se connecter à l'aide d'une communication en texte brut

Pour établir une connexion en texte brut, spécifiez le point de terminaison Spanner Omni, activez la prise en charge expérimentale de l'hôte avec la méthode withExperimentalHost() et configurez le pipeline avec la méthode withUsingPlainTextChannel().

L'exemple suivant montre comment configurer une connexion en texte brut :

SpannerConfig spannerConfig =
    SpannerConfig.create()
        .withDatabaseId("DATABASE_ID")
        // Define the Spanner Omni endpoint
        .withExperimentalHost("http://ENDPOINT")
        // Use a plain-text connection
        .withUsingPlainTextChannel(true);

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.

Se connecter à l'aide du chiffrement

Pour protéger le trafic de la base de données et assurer une communication sécurisée entre Apache Beam et Spanner Omni, vous pouvez vous connecter à l'aide du chiffrement TLS ou mTLS. Le chiffrement permet de préserver la confidentialité de vos identifiants et de vos données.

Utiliser le chiffrement TLS

Pour protéger le trafic de base de données entre Apache Beam et Spanner Omni à l'aide du chiffrement TLS, vous n'avez pas besoin de spécifier les propriétés des identifiants dans SpannerConfig. Configurez plutôt un truststore Java avec le certificat Spanner Omni CA, puis configurez SpannerConfig pour utiliser le point de terminaison TLS sécurisé.

Étape 1 : Configurer le truststore Java

Pour sécuriser la communication, vous devez importer le certificat de l'autorité de certification généré par Spanner Omni dans un truststore Java. Utilisez l'une des options suivantes :

Truststore Java par défaut

Ajoutez le certificat CA généré par Spanner Omni au truststore Java standard en exécutant la commande suivante :

sudo keytool -import -trustcacerts \
  -file ~/.spanner/certs/ca.crt \
  -alias spanner-ca \
  -keystore $JAVA_HOME/lib/security/cacerts

Truststore personnalisé

Pour vous assurer que votre pipeline peut toujours se connecter à d'autres bases de données ou services qui utilisent des autorités de certification (AC) standards, créez un truststore personnalisé :

  1. Créez un truststore personnalisé en copiant le truststore Java existant :

    cp $JAVA_HOME/lib/security/cacerts PATH_TO_CUSTOM_CA_CERTIFICATE

  2. Importez le certificat CA dans votre truststore personnalisé :

    keytool -import -trustcacerts \
  -file ~/.spanner/certs/ca.crt \
  -alias spanner-ca \
  -keystore PATH_TO_CUSTOM_CA_CERTIFICATE

  3. Transmettez le magasin de certificats CA personnalisés lorsque vous exécutez le pipeline :

    java -Djavax.net.ssl.trustStore=PATH_TO_CUSTOM_CA_CERTIFICATE \
  -Djavax.net.ssl.trustStorePassword=changeit \
  -jar PIPELINE_NAME.jar

Remplacez les éléments suivants :

  • PATH_TO_CUSTOM_CA_CERTIFICATE : chemin d'accès à votre magasin de certificats d'autorité de certification personnalisée.

  • PIPELINE_NAME : nom de votre pipeline Apache Beam.

Étape 2 : Configurer SpannerConfig

Pour configurer SpannerConfig de manière à utiliser une connexion TLS sécurisée, ajoutez le code suivant à votre pipeline :

SpannerConfig spannerConfig =
    SpannerConfig.create()
        .withDatabaseId("DATABASE_ID")
        // Define the secure Spanner Omni endpoint
        .withExperimentalHost("https://ENDPOINT");

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.

Utiliser le chiffrement mTLS

Pour établir une connexion TLS mutuelle (mTLS) à l'aide d'Apache Beam, vous devez configurer le truststore Java avec le certificat de l'autorité de certification, générer ou convertir une clé privée client au format PKCS#8, puis configurer SpannerConfig avec le chemin d'accès au certificat et à la clé client.

Étape 1 : Configurer le truststore Java

Configurez le truststore Java avec le certificat Spanner Omni CA, comme décrit à l'étape 1 : Configurer le truststore Java plus haut dans ce document.

Étape 2 : Convertissez ou générez la clé privée du client

Pour vous connecter à l'aide de mTLS, assurez-vous que votre clé privée client est au format PKCS#8. Utilisez l'une des options suivantes :

openssl

Pour convertir la clé client générée par Spanner Omni dans un format compatible avec Java, exécutez la commande suivante :

openssl pkcs8 -topk8 \
  -in ~/.spanner/certs/client.key \
  -out ~/.spanner/certs/java-client.key \
  -nocrypt

CLI Spanner Omni

Générez la clé directement au format PKCS#8 lorsque vous créez votre certificat client à l'aide de la CLI Spanner Omni avec l'indicateur --generate-pkcs8-key.

Pour générer un certificat client et une clé privée client au format PKCS#8, exécutez la commande suivante :

spanner certificates create-client CLIENT_NAME \
  --ca-certificate-directory=PATH_TO_CA_CERTIFICATES \
  --ca-private-key-directory=PATH_TO_PRIVATE_KEYS \
  --output-directory=PATH_TO_CERTIFICATES \
  --generate-pkcs8-key

Remplacez les éléments suivants :

  • CLIENT_NAME : nom du client pour lequel générer le certificat et la clé privée.

  • PATH_TO_CA_CERTIFICATES : chemin d'accès au répertoire contenant les certificats de l'autorité de certification.

  • PATH_TO_PRIVATE_KEYS : chemin d'accès au répertoire contenant les clés privées de l'autorité de certification.

  • PATH_TO_CERTIFICATES : chemin d'accès au répertoire dans lequel sont enregistrés le certificat client et la clé privée.

Étape 3 : Configurer SpannerConfig

Configurez SpannerConfig dans le code de votre pipeline avec le certificat client et la clé privée du client :

SpannerConfig spannerConfig =
    SpannerConfig.create()
        .withDatabaseId("DATABASE_ID")
        // Define the secure Spanner Omni endpoint
        .withExperimentalHost("https://ENDPOINT")
        // Specify the paths to the client certificate and private key
        .withClientCert(
            "PATH_TO_CLIENT_CERT",
            "PATH_TO_CLIENT_CERT_KEY");

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_CERT_KEY : chemin d'accès au fichier de clé privée de votre client.

Configurer les jetons d'authentification

Les jetons d'authentification ne sont pas recommandés pour l'utilisation par les clients, car les jetons générés par Spanner Omni expirent et doivent être renouvelés manuellement avec la CLI Spanner Omni. Pour utiliser un jeton d'authentification avec une configuration TLS ou mTLS pour un point de terminaison Spanner Omni, définissez la variable d'environnement SPANNER_EXPERIMENTAL_HOST_AUTH_TOKEN sur la valeur du jeton d'authentification généré par l'interface de ligne de commande Spanner Omni. Laissez cette variable non définie pour les connexions qui ne nécessitent pas d'identifiants.

Étapes suivantes