Usa Apache Beam y SpannerIO para conectarte a Spanner Omni

Apache Beam es un modelo unificado de código abierto para definir canalizaciones de procesamiento paralelo de datos de transmisión y por lotes. En este documento, se describe cómo usar el conector de SpannerIO dentro de una canalización de Apache Beam para leer o escribir en bases de datos de Spanner Omni.

Antes de comenzar

Para conectar SpannerIO a Spanner Omni, asegúrate de cumplir con los siguientes requisitos:

  • Inicializar una base de datos en tu entorno de Spanner Omni

  • Si usas la encriptación, asegúrate de usar una versión compatible de Apache Beam:

    • Para la encriptación TLS, versión 2.69.0 o posterior.
    • Para la encriptación de TLS mutua (mTLS), versión 2.75.0 o posterior.

  • Configura las credenciales de autenticación para tu entorno.

Configura SpannerIO para conectarte a Spanner Omni

Para conectar SpannerIO a Spanner Omni, configura SpannerConfig con los detalles de tu base de datos y los parámetros de conexión.

Para configurar la conexión, elige uno de los siguientes modos de conexión:

Conéctate con la comunicación de texto sin formato

Para establecer una conexión de texto sin formato, especifica el extremo de Spanner Omni, habilita la compatibilidad experimental con hosts con el método withExperimentalHost() y configura la canalización con el método withUsingPlainTextChannel().

En el siguiente ejemplo, se muestra cómo configurar una conexión de texto sin formato:

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

Reemplaza lo siguiente:

  • DATABASE_ID: Es el ID de tu base de datos de Spanner Omni, por ejemplo, test-db.

  • ENDPOINT: Es el extremo de tu instancia de Spanner Omni, por ejemplo, localhost:15000.

Conéctate con encriptación

Para proteger el tráfico de la base de datos y garantizar una comunicación segura entre Apache Beam y Spanner Omni, puedes conectarte con la encriptación TLS o mTLS. La encriptación ayuda a mantener la confidencialidad de tus credenciales y datos.

Usa la encriptación TLS

Para proteger el tráfico de la base de datos entre Apache Beam y Spanner Omni con la encriptación TLS, no es necesario que especifiques las propiedades de las credenciales en SpannerConfig. En su lugar, configura un almacén de certificados de confianza de Java con el certificado de la AC de Spanner Omni y, luego, configura el SpannerConfig para usar el extremo de TLS seguro.

Paso 1: Configura el almacén de certificados de confianza de Java

Para proteger la comunicación, debes importar el certificado de la AC que genera Spanner Omni a un almacén de certificados de confianza de Java. Usa una de las siguientes opciones:

Almacén de certificados de confianza de Java predeterminado

Agrega el certificado de la AC generado por Spanner Omni al almacén de certificados de confianza de Java estándar ejecutando el siguiente comando:

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

Almacén de certificados de confianza personalizado

Para asegurarte de que tu canalización aún pueda conectarse a otras bases de datos o servicios que usen autoridades certificadoras (AC) estándar, crea un almacén de certificados de confianza personalizado:

  1. Crea un almacén de certificados de confianza personalizado copiando el almacén de certificados de confianza de Java existente:

    cp $JAVA_HOME/lib/security/cacerts PATH_TO_CUSTOM_CA_CERTIFICATE

  2. Importa el certificado de la AC a tu almacén de certificados de confianza personalizado:

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

  3. Pasa el almacén de certificados de la AC personalizada cuando ejecutes la canalización:

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

Reemplaza lo siguiente:

  • PATH_TO_CUSTOM_CA_CERTIFICATE: Es la ruta de acceso a tu almacén de certificados de la AC personalizado.

  • PIPELINE_NAME: Es el nombre de tu canalización de Apache Beam.

Paso 2: Configura la SpannerConfig

Para configurar SpannerConfig de modo que use una conexión TLS segura, agrega el siguiente código a tu canalización:

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

Reemplaza lo siguiente:

  • DATABASE_ID: Es el ID de tu base de datos de Spanner Omni, por ejemplo, test-db.

  • ENDPOINT: Es el extremo de tu instancia de Spanner Omni, por ejemplo, localhost:15000.

Usa la encriptación de mTLS

Para establecer una conexión de TLS mutua (mTLS) con Apache Beam, debes configurar el almacén de certificados de confianza de Java con el certificado de la AC, generar o convertir una clave privada de cliente al formato PKCS#8 y, luego, configurar SpannerConfig con el certificado de cliente y la ruta de acceso de la clave.

Paso 1: Configura el almacén de certificados de confianza de Java

Configura el almacén de certificados de confianza de Java con el certificado de la AC de Spanner Omni como se describe en el Paso 1: Configura el almacén de certificados de confianza de Java que se encuentra más arriba en este documento.

Paso 2: Convierte o genera la clave privada del cliente

Para conectarte con mTLS, asegúrate de que tu clave privada de cliente esté en el formato PKCS#8. Usa una de las siguientes opciones:

openssl

Para convertir la clave de cliente generada por Spanner Omni en un formato compatible con Java, ejecuta el siguiente comando:

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

CLI de Spanner Omni

Genera la clave directamente en formato PKCS#8 cuando crees tu certificado de cliente con la CLI de Spanner Omni con la marca --generate-pkcs8-key.

Para generar un certificado de cliente y una clave privada de cliente en formato PKCS#8, ejecuta el siguiente 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

Reemplaza lo siguiente:

  • CLIENT_NAME: Es el nombre del cliente para el que se generará el certificado y la clave privada.

  • PATH_TO_CA_CERTIFICATES: Es la ruta de acceso al directorio que contiene los certificados de la AC.

  • PATH_TO_PRIVATE_KEYS: Es la ruta de acceso al directorio que contiene las claves privadas de la AC.

  • PATH_TO_CERTIFICATES: Es la ruta de acceso al directorio en el que se guardan el certificado de cliente y la clave privada.

Paso 3: Configura SpannerConfig

Configura el SpannerConfig en el código de tu canalización con el certificado de cliente y la clave privada del 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");

Reemplaza lo siguiente:

  • DATABASE_ID: Es el ID de tu base de datos de Spanner Omni, por ejemplo, test-db.

  • ENDPOINT: Es el extremo de tu instancia de Spanner Omni, por ejemplo, localhost:15000.

  • PATH_TO_CLIENT_CERT: Es la ruta de acceso al archivo del certificado del cliente.

  • PATH_TO_CLIENT_CERT_KEY: Es la ruta de acceso al archivo de clave privada del cliente.

Configura tokens de autenticación

No se recomienda usar tokens de autenticación para los clientes, ya que los tokens que genera Spanner Omni vencen y requieren una renovación manual con la CLI de Spanner Omni. Para usar un token de autenticación con una configuración de TLS o mTLS para un extremo de Spanner Omni, establece la variable de entorno SPANNER_EXPERIMENTAL_HOST_AUTH_TOKEN en el valor del token de autenticación que genera la CLI de Spanner Omni. Deja esta variable sin configurar para las conexiones que no requieren credenciales.

¿Qué sigue?