Utilizza Apache Beam e SpannerIO per connetterti a Spanner Omni

Apache Beam è un modello unificato open source per la definizione di pipeline di elaborazione parallela dei dati sia in batch che in streaming. Questo documento descrive come utilizzare il connettore SpannerIO all'interno di una pipeline Apache Beam per leggere o scrivere nei database Spanner Omni.

Prima di iniziare

Per connettere SpannerIO a Spanner Omni, assicurati di soddisfare i seguenti requisiti:

  • Inizializza un database all'interno dell'ambiente Spanner Omni.

  • Se utilizzi la crittografia, assicurati di utilizzare una versione compatibile di Apache Beam:

    • Per la crittografia TLS, versione 2.69.0 o successive.
    • Per la crittografia mutual TLS (mTLS), versione 2.75.0 o successive.

  • Configura le credenziali di autenticazione per il tuo ambiente.

Configura SpannerIO per la connessione a Spanner Omni

Per connettere SpannerIO a Spanner Omni, configura SpannerConfig con i dettagli del database e i parametri di connessione.

Per configurare la connessione, scegli una delle seguenti modalità di connessione:

Connettiti utilizzando la comunicazione in testo normale

Per stabilire una connessione in testo normale, specifica l'endpoint Spanner Omni, attiva il supporto dell'host sperimentale con il metodo withExperimentalHost() e configura la pipeline con il metodo withUsingPlainTextChannel().

L'esempio seguente mostra come configurare una connessione in testo normale:

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

Sostituisci quanto segue:

  • DATABASE_ID: l'ID del tuo database Spanner Omni, ad esempio test-db.

  • ENDPOINT: l'endpoint della tua istanza Spanner Omni, ad esempio localhost:15000.

Connettiti utilizzando la crittografia

Per proteggere il traffico del database e garantire una comunicazione sicura tra Apache Beam e Spanner Omni, puoi connetterti utilizzando la crittografia TLS o mTLS. L'utilizzo della crittografia contribuisce a mantenere riservati i dati e le credenziali.

Utilizza la crittografia TLS

Per proteggere il traffico del database tra Apache Beam e Spanner Omni utilizzando la crittografia TLS, non è necessario specificare le proprietà delle credenziali in SpannerConfig. Configura invece un truststore Java con il certificato CA di Spanner Omni, quindi configura SpannerConfig per utilizzare l'endpoint TLS sicuro.

Passaggio 1: configura il truststore Java

Per proteggere la comunicazione, devi importare il certificato CA generato da Spanner Omni in un truststore Java. Utilizza una delle seguenti opzioni:

Truststore Java predefinito

Aggiungi il certificato CA generato da Spanner Omni al truststore Java standard eseguendo questo comando:

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

Archivio di attendibilità personalizzato

Per assicurarti che la pipeline possa comunque connettersi ad altri database o servizi che utilizzano autorità di certificazione (CA) standard, crea un truststore personalizzato:

  1. Crea un truststore personalizzato copiando il truststore Java esistente:

    cp $JAVA_HOME/lib/security/cacerts PATH_TO_CUSTOM_CA_CERTIFICATE

  2. Importa il certificato CA nel truststore personalizzato:

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

  3. Passa l'archivio certificati CA personalizzato quando esegui la pipeline:

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

Sostituisci quanto segue:

  • PATH_TO_CUSTOM_CA_CERTIFICATE: il percorso dell'archivio dei certificati CA personalizzati.

  • PIPELINE_NAME: il nome della pipeline Apache Beam.

Passaggio 2: configura SpannerConfig

Per configurare SpannerConfig in modo che utilizzi una connessione TLS sicura, aggiungi il seguente codice alla pipeline:

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

Sostituisci quanto segue:

  • DATABASE_ID: l'ID del tuo database Spanner Omni, ad esempio test-db.

  • ENDPOINT: l'endpoint della tua istanza Spanner Omni, ad esempio localhost:15000.

Utilizza la crittografia mTLS

Per stabilire una connessione mutual TLS (mTLS) utilizzando Apache Beam, devi configurare il truststore Java con il certificato CA, generare o convertire una chiave privata client in formato PKCS#8 e poi configurare SpannerConfig con il certificato client e il percorso della chiave.

Passaggio 1: configura il truststore Java

Configura il truststore Java con il certificato CA di Spanner Omni come descritto nel Passaggio 1: configura il truststore Java riportato in precedenza in questo documento.

Passaggio 2: converti o genera la chiave privata del client

Per connetterti utilizzando mTLS, assicurati che la chiave privata del client sia in formato PKCS#8. Utilizza una delle seguenti opzioni:

openssl

Per convertire la chiave client generata da Spanner Omni in un formato conforme a Java, esegui questo comando:

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

Interfaccia a riga di comando di Spanner Omni

Genera la chiave direttamente in formato PKCS#8 durante la creazione del certificato client utilizzando l'interfaccia a riga di comando di Spanner Omni con il flag --generate-pkcs8-key.

Per generare un certificato client e una chiave privata client in formato PKCS#8, esegui questo comando:

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

Sostituisci quanto segue:

  • CLIENT_NAME: il nome del client per cui generare il certificato e la chiave privata.

  • PATH_TO_CA_CERTIFICATES: il percorso della directory contenente i certificati CA.

  • PATH_TO_PRIVATE_KEYS: il percorso della directory contenente le chiavi private della CA.

  • PATH_TO_CERTIFICATES: il percorso della directory in cui sono salvati il certificato client e la chiave privata.

Passaggio 3: configura SpannerConfig

Configura SpannerConfig nel codice della pipeline con il certificato client e la chiave privata 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");

Sostituisci quanto segue:

  • DATABASE_ID: l'ID del tuo database Spanner Omni, ad esempio test-db.

  • ENDPOINT: l'endpoint della tua istanza Spanner Omni, ad esempio localhost:15000.

  • PATH_TO_CLIENT_CERT: il percorso del file del certificato client.

  • PATH_TO_CLIENT_CERT_KEY: il percorso del file della chiave privata del client.

Configura i token di autenticazione

I token di autenticazione non sono consigliati per l'utilizzo da parte del client perché i token generati da Spanner Omni scadono e richiedono il rinnovo manuale con l'interfaccia a riga di comando di Spanner Omni. Per utilizzare un token di autenticazione con una configurazione TLS o mTLS per un endpoint Spanner Omni, imposta la variabile di ambiente SPANNER_EXPERIMENTAL_HOST_AUTH_TOKEN sul valore del token di autenticazione generato dall'interfaccia a riga di comando di Spanner Omni. Lascia questa variabile non impostata per le connessioni che non richiedono credenziali.

Passaggi successivi