Usa Apache Beam y SpannerIO para conectarte a Spanner Omni

Apache Beam es un modelo unificado de código abierto que se usa para definir canalizaciones con paralelismo de datos de procesamiento por lotes y de transmisiones. En este documento, se describe cómo usar el conector 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:

  • Inicializa una base de datos en tu entorno de Spanner Omni.

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

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

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

Configura SpannerIO para conectarse 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 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 el host 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 la comunicación segura entre Apache Beam y Spanner Omni, puedes conectarte con encriptación TLS o mTLS. El uso de 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 confianza de Java con el certificado de CA de Spanner Omni y, luego, configura SpannerConfig para usar el extremo TLS seguro.

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

Para proteger la comunicación, debes importar el certificado de CA generado por Spanner Omni a un almacén de confianza de Java. Usa una de las siguientes opciones:

Almacén de confianza predeterminado de Java

Para agregar el certificado de CA generado por Spanner Omni al almacén de confianza estándar de Java, ejecuta el siguiente comando:

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

Almacén 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 (CA) estándar, crea un almacén de confianza personalizado:

  1. Para crear un almacén de confianza personalizado, copia el almacén de confianza de Java existente:

    cp $JAVA_HOME/lib/security/cacerts PATH_TO_CUSTOM_CA_CERTIFICATE

  2. Importa el certificado de CA a tu almacén 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 CA personalizado 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 CA personalizado.

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

Paso 2: Configura SpannerConfig

Para configurar SpannerConfig para usar 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 mTLS

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

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

Configura el almacén de confianza de Java con el certificado de CA de Spanner Omni como se describe en Paso 1: Configura el almacén de confianza de Java anteriormente en este documento.

Paso 2: Convierte o genera la clave privada del cliente

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

openssl

Para convertir la clave del cliente generada por Spanner Omni a 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 del 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án el certificado y la clave privada.

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

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

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

Paso 3: Configura SpannerConfig

Configura SpannerConfig en el código de tu canalización con el certificado del 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 claves privadas del cliente.

Configura tokens de autenticación

No se recomiendan los tokens de autenticación para el uso del cliente porque los tokens generados por 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 generado por la CLI de Spanner Omni. Deja esta variable sin configurar para las conexiones que no requieren credenciales.

¿Qué sigue?