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 dans des bases de données Spanner Omni.

Avant de commencer

Pour connecter SpannerIO à Spanner Omni, assurez-vous de remplir les conditions 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 compatibilité expérimentale avec l'hôte à l'aide de la méthode withExperimentalHost() et configurez le pipeline à l'aide de 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 garantir 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 la base de données entre Apache Beam et Spanner Omni à l'aide du chiffrement TLS, vous n'avez pas besoin de spécifier de propriétés d'identifiants dans SpannerConfig. Configurez plutôt un truststore Java avec le certificat CA Spanner Omni, puis configurez SpannerConfig pour utiliser le point de terminaison TLS sécurisé.

Étape 1 : Configurer le truststore Java

Pour sécuriser les communications, vous devez importer le certificat CA généré par Spanner Omni dans un truststore Java. Utilisez l'une des options suivantes :

Magasin de confiance 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 (CA) 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é 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 CA personnalisé.

  • PIPELINE_NAME : nom de votre pipeline Apache Beam.

Étape 2 : Configurer SpannerConfig

Pour configurer SpannerConfig afin d'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 CA, générer ou convertir une clé privée client au format PKCS#8, puis configurer SpannerConfig avec le certificat client et le chemin d'accès à la clé.

Étape 1 : Configurer le truststore Java

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

Étape 2 : Convertir ou générer 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 lors de la création de votre certificat client en utilisant la CLI Spanner Omni avec l'option --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 CA.

  • 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 le certificat client et la clé privée sont enregistrés.

Étape 3 : Configurez SpannerConfig

Configurez SpannerConfig dans le code de votre pipeline avec le certificat client et la clé privée 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 une utilisation par le client, car les jetons générés par Spanner Omni expirent et nécessitent un renouvellement manuel 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 la CLI Spanner Omni. Laissez cette variable non définie pour les connexions qui ne nécessitent pas d'identifiants.

Étapes suivantes