Usar o Apache Beam e o SpannerIO para se conectar ao Spanner Omni

O Apache Beam é um modelo unificado e de código aberto para a definição de pipelines de processamento paralelo de dados em lote e streaming. Este documento descreve como usar o conector SpannerIO em um pipeline do Apache Beam para ler ou gravar em bancos de dados do Spanner Omni.

Antes de começar

Para conectar o SpannerIO ao Spanner Omni, verifique se você atende aos seguintes requisitos:

  • Inicialize um banco de dados no ambiente do Spanner Omni.

  • Se você usar criptografia, use uma versão compatível do Apache Beam:

    • Para criptografia TLS, versão 2.69.0 ou mais recente.
    • Para criptografia TLS mútua (mTLS), versão 2.75.0 ou mais recente.

  • Configure as credenciais de autenticação para seu ambiente.

Configurar o SpannerIO para se conectar ao Spanner Omni

Para conectar o SpannerIO ao Spanner Omni, configure SpannerConfig com os detalhes do banco de dados e os parâmetros de conexão.

Para configurar a conexão, escolha um dos seguintes modos:

Conectar usando comunicação de texto simples

Para estabelecer uma conexão de texto simples, especifique o endpoint do Spanner Omni, ative o suporte de host experimental com o método withExperimentalHost() e configure o pipeline com o método withUsingPlainTextChannel().

O exemplo a seguir mostra como configurar uma conexão de texto simples:

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

Substitua:

  • DATABASE_ID: o ID do banco de dados do Spanner Omni, por exemplo, test-db.

  • ENDPOINT: o endpoint da instância do Spanner Omni, por exemplo, localhost:15000.

Conectar usando criptografia

Para proteger o tráfego do banco de dados e garantir a comunicação segura entre o Apache Beam e o Spanner Omni, você pode se conectar usando a criptografia TLS ou mTLS. O uso da criptografia ajuda a manter suas credenciais e dados confidenciais.

Usar criptografia TLS

Para proteger o tráfego do banco de dados entre o Apache Beam e o Spanner Omni usando a criptografia TLS, não é necessário especificar propriedades de credenciais em SpannerConfig. Em vez disso, configure um truststore Java com o certificado de CA do Spanner Omni e, em seguida, configure o SpannerConfig para usar o endpoint TLS seguro.

Etapa 1: configurar o truststore Java

Para proteger a comunicação, importe o certificado de CA gerado pelo Spanner Omni para um truststore Java. Use uma das seguintes opções:

Truststore Java padrão

Adicione o certificado de CA gerado pelo Spanner Omni ao truststore Java padrão executando o seguinte comando:

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

Truststore personalizado

Para garantir que o pipeline ainda possa se conectar a outros bancos de dados ou serviços que usam autoridades de certificação (CAs) padrão, crie um truststore personalizado:

  1. Crie um truststore personalizado copiando o truststore Java atual:

    cp $JAVA_HOME/lib/security/cacerts PATH_TO_CUSTOM_CA_CERTIFICATE

  2. Importe o certificado de CA para o truststore personalizado:

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

  3. Transmita o armazenamento de certificado de CA personalizado ao executar o pipeline:

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

Substitua:

  • PATH_TO_CUSTOM_CA_CERTIFICATE: o caminho para o armazenamento de certificado de CA personalizado.

  • PIPELINE_NAME: o nome do pipeline do Apache Beam.

Etapa 2: configurar SpannerConfig

Para configurar SpannerConfig para usar uma conexão TLS segura, adicione o seguinte código ao pipeline:

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

Substitua:

  • DATABASE_ID: o ID do banco de dados do Spanner Omni, por exemplo, test-db.

  • ENDPOINT: o endpoint da instância do Spanner Omni, por exemplo, localhost:15000.

Usar criptografia mTLS

Para estabelecer uma conexão TLS mútua (mTLS) usando o Apache Beam, configure o truststore Java com o certificado de CA, gere ou converta uma chave privada do cliente para o formato PKCS#8 e configure SpannerConfig com o certificado do cliente e o caminho da chave.

Etapa 1: configurar o truststore Java

Configure o truststore Java com o certificado de CA do Spanner Omni , conforme descrito em Etapa 1: configurar o truststore Java, anteriormente neste documento.

Etapa 2: converter ou gerar a chave privada do cliente

Para se conectar usando mTLS, verifique se a chave privada do cliente está no formato PKCS#8. Use uma das seguintes opções:

openssl

Para converter a chave do cliente gerada pelo Spanner Omni em um formato compatível com Java, execute o seguinte comando:

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

CLI para Spanner Omni

Gere a chave diretamente no formato PKCS#8 ao criar o certificado do cliente usando a CLI para Spanner Omni com a flag --generate-pkcs8-key.

Para gerar um certificado do cliente e uma chave privada do cliente no formato PKCS#8, execute o seguinte 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

Substitua:

  • CLIENT_NAME: o nome do cliente para gerar o certificado e a chave privada.

  • PATH_TO_CA_CERTIFICATES: o caminho para o diretório que contém os certificados de CA.

  • PATH_TO_PRIVATE_KEYS: o caminho para o diretório que contém as chaves privadas de CA.

  • PATH_TO_CERTIFICATES: o caminho para o diretório em que o certificado do cliente e a chave privada são salvos.

Etapa 3: configurar SpannerConfig

Configure o SpannerConfig no código do pipeline com o certificado do cliente e a chave privada do cliente:

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");

Substitua:

  • DATABASE_ID: o ID do banco de dados do Spanner Omni, por exemplo, test-db.

  • ENDPOINT: o endpoint da instância do Spanner Omni, por exemplo, localhost:15000.

  • PATH_TO_CLIENT_CERT: o caminho para o arquivo de certificado do cliente.

  • PATH_TO_CLIENT_CERT_KEY: o caminho para o arquivo de chave privada do cliente.

Configurar tokens de autenticação

Os tokens de autenticação não são recomendados para uso do cliente porque os tokens gerados pelo Spanner Omni expiram e exigem renovação manual com a CLI para Spanner Omni. Para usar um token de autenticação com uma configuração TLS ou mTLS para um endpoint do Spanner Omni, defina a variável de ambiente SPANNER_EXPERIMENTAL_HOST_AUTH_TOKEN como o valor do token de autenticação gerado pela CLI para Spanner Omni. Deixe essa variável não definida para conexões que não exigem credenciais.

A seguir