Conecta Pub/Sub Lite a Apache Kafka

En este documento, se describe cómo integrar Apache Kafka y Pub/Sub Lite mediante el conector de Kafka de grupos de Pub/Sub.

Acerca del conector de Kafka de grupos de Pub/Sub

Apache Kafka es una plataforma de código abierto para eventos de transmisión. Por lo general, se usa en arquitecturas distribuidas para permitir la comunicación entre componentes con acoplamiento bajo. Pub/Sub Lite es un servicio administrado para enviar y recibir mensajes de forma asíncrona. Al igual que con Kafka, puedes usar Pub/Sub Lite para la comunicación entre componentes de tu arquitectura en la nube.

El conector de Kafka de grupos de Pub/Sub te permite integrar estos dos sistemas. Los siguientes conectores se empaquetan en el archivo JAR del conector:

  • El conector de receptor lee los registros de uno o más temas de Kafka y los publica en Pub/Sub Lite.
  • El conector de origen lee los mensajes de un tema de Pub/Sub Lite y los publica en Kafka.

A continuación, se muestran algunas situaciones en las que puedes usar el conector de Kafka de grupos de Pub/Sub:

  • Estás migrando una arquitectura basada en Kafka a Google Cloud.
  • Tienes un sistema de frontend que almacena eventos en Kafka fuera de Google Cloud, pero también usas Google Cloud para ejecutar algunos de tus servicios de backend, que necesitan recibir los eventos de Kafka.
  • Recopilas registros de una solución de Kafka local y los envías a Google Cloud para el análisis de datos.
  • Tienes un sistema de frontend que usa Google Cloud, pero también almacenas datos de forma local con Kafka.

El conector requiere Kafka Connect, que es un framework para transmitir datos entre Kafka y otros sistemas. Para usar el conector, debes ejecutar Kafka Connect junto con tu clúster de Kafka.

En este documento, se supone que estás familiarizado con Kafka y Pub/Sub Lite. Para comenzar a usar Pub/Sub Lite, consulta Publica y recibe mensajes en Pub/Sub Lite con la consola de Google Cloud.

Comienza a usar el conector de Kafka de grupos de Pub/Sub

En esta sección, se explican las siguientes tareas:

  1. Configurar el conector de Kafka de grupos de Pub/Sub
  2. Enviar eventos de Kafka a Pub/Sub Lite
  3. Enviar mensajes de Pub/Sub Lite a Kafka

Requisitos previos

Instalar Kafka

Sigue la guía de inicio rápido de Apache Kafka para instalar un Kafka de nodo único en tu máquina local. Completa los siguientes pasos en la guía de inicio rápido:

  1. Descarga la versión más reciente de Kafka y extráela.
  2. Inicie el entorno de Kafka.
  3. Crear un tema de Kafka

Autenticar

El conector de Kafka de grupos de Pub/Sub debe autenticarse con Pub/Sub para enviar y recibir mensajes de Pub/Sub. Para configurar la autenticación, sigue estos pasos:

  1. Accede a tu cuenta de Google Cloud. Si eres nuevo en Google Cloud, crea una cuenta para evaluar el rendimiento de nuestros productos en situaciones reales. Los clientes nuevos también obtienen $300 en créditos gratuitos para ejecutar, probar y, además, implementar cargas de trabajo.
  2. Instala Google Cloud CLI.

  3. Para inicializar la CLI de gcloud, ejecuta el siguiente comando: 

    gcloud init

  4. Crea o selecciona un proyecto de Google Cloud.

    • Crea un proyecto de Google Cloud:

      gcloud projects create PROJECT_ID

      Reemplaza PROJECT_ID por un nombre para el proyecto de Google Cloud que estás creando.

    • Selecciona el proyecto de Google Cloud que creaste:

      gcloud config set project PROJECT_ID

      Reemplaza PROJECT_ID por el nombre del proyecto de Google Cloud.

  5. Crea credenciales de autenticación locales para tu Cuenta de Google: 

    gcloud auth application-default login

  6. Otorga roles a tu Cuenta de Google. Ejecuta el siguiente comando una vez para cada uno de los siguientes roles de IAM: roles/pubsublite.admin 

    gcloud projects add-iam-policy-binding PROJECT_ID --member="user:EMAIL_ADDRESS" --role=ROLE
    • Reemplaza PROJECT_ID con el ID del proyecto.
    • Reemplaza EMAIL_ADDRESS por tu dirección de correo electrónico.
    • Reemplaza ROLE por cada rol individual.
    7.
  7. Instala Google Cloud CLI.

  8. Para inicializar la CLI de gcloud, ejecuta el siguiente comando: 

    gcloud init

  9. Crea o selecciona un proyecto de Google Cloud.

    • Crea un proyecto de Google Cloud:

      gcloud projects create PROJECT_ID

      Reemplaza PROJECT_ID por un nombre para el proyecto de Google Cloud que estás creando.

    • Selecciona el proyecto de Google Cloud que creaste:

      gcloud config set project PROJECT_ID

      Reemplaza PROJECT_ID por el nombre del proyecto de Google Cloud.

  10. Crea credenciales de autenticación locales para tu Cuenta de Google: 

    gcloud auth application-default login

  11. Otorga roles a tu Cuenta de Google. Ejecuta el siguiente comando una vez para cada uno de los siguientes roles de IAM: roles/pubsublite.admin 

    gcloud projects add-iam-policy-binding PROJECT_ID --member="user:EMAIL_ADDRESS" --role=ROLE
    • Reemplaza PROJECT_ID con el ID del proyecto.
    • Reemplaza EMAIL_ADDRESS por tu dirección de correo electrónico.
    • Reemplaza ROLE por cada rol individual.
    12.

Descarga el JAR del conector

Descarga el archivo JAR del conector en tu máquina local. Para obtener más información, consulta Adquiere el conector en el archivo readme de GitHub.

Copia los archivos de configuración del conector

  1. Clona o descarga el repositorio de GitHub para el conector.

    git clone https://github.com/googleapis/java-pubsub-group-kafka-connector.git
cd java-pubsub-group-kafka-connector

  2. Copia el contenido del directorio config en el subdirectorio config de la instalación de Kafka.

    cp config/* [path to Kafka installation]/config/

Estos archivos contienen los parámetros de configuración del conector.

Actualice su configuración de Kafka Connect

  1. Navega al directorio que contiene el objeto binario Kafka Connect que descargaste.
  2. En el directorio binario de Kafka Connect, abre el archivo llamado config/connect-standalone.properties en un editor de texto.
  3. Si plugin.path property está marcado como comentario, quita el comentario.

  4. Actualiza el plugin.path property para incluir la ruta de acceso al conector JAR.

    Ejemplo:

    plugin.path=/home/PubSubKafkaConnector/pubsub-group-kafka-connector-1.0.0.jar

  5. Configura la propiedad offset.storage.file.filename con un nombre de archivo local. En el modo independiente, Kafka usa este archivo para almacenar datos de desplazamiento.

    Ejemplo:

    offset.storage.file.filename=/tmp/connect.offsets

Reenvía eventos de Kafka a Pub/Sub Lite

En esta sección, se describe cómo iniciar el conector de receptores, publicar eventos en Kafka y leer los mensajes reenviados desde Pub/Sub Lite.

  1. Usa Google Cloud CLI para crear una reserva de Pub/Sub Lite.

    gcloud pubsub lite-reservations create RESERVATION_NAME \
--location=LOCATION \
--throughput-capacity=4

    Reemplaza lo siguiente:

    • RESERVATION_NAME: Es el nombre de la reserva de Pub/Sub Lite.
    • LOCATION: Es la ubicación de la reserva.

  2. Usa Google Cloud CLI para crear un tema de Pub/Sub Lite con una suscripción.

    gcloud pubsub lite-topics create LITE_TOPIC \
--location=LOCATION \
--partitions=2 \
--per-partition-bytes=30GiB \
--throughput-reservation=RESERVATION_NAME

gcloud pubsub lite-subscriptions create LITE_SUBSCRIPTION \
--location=LOCATION \
--topic=LITE_TOPIC

    Reemplaza lo siguiente:

    • LITE_TOPIC: Es el nombre del tema de Pub/Sub Lite para recibir mensajes de Kafka.
    • LOCATION: Es la ubicación del tema. El valor debe coincidir con la ubicación de la reserva.
    • RESERVATION_NAME: Es el nombre de la reserva de Pub/Sub Lite.
    • LITE_SUBSCRIPTION: Es el nombre de una suscripción de Pub/Sub Lite para el tema.

  3. Abre el archivo /config/pubsub-lite-sink-connector.properties en un editor de texto. Agrega valores para las siguientes propiedades, que están marcadas como "TODO" en los comentarios:

    topics=KAFKA_TOPICS
pubsublite.project=PROJECT_ID
pubsublite.location=LOCATION
pubsublite.topic=LITE_TOPIC

    Reemplaza lo siguiente:

    • KAFKA_TOPICS: Es una lista separada por comas de temas de Kafka desde los que se leerá.
    • PROJECT_ID: Es el proyecto de Google Cloud que contiene tu tema de Pub/Sub Lite.
    • LOCATION: Es la ubicación del tema de Pub/Sub Lite.
    • LITE_TOPIC: Es el tema de Pub/Sub Lite para recibir mensajes de Kafka.

  4. Desde el directorio de Kafka, ejecuta el siguiente comando:

    bin/connect-standalone.sh \
  config/connect-standalone.properties \
  config/pubsub-lite-sink-connector.properties

  5. Sigue los pasos de la guía de inicio rápido de Apache Kafka para escribir algunos eventos en tu tema de Kafka.

  6. Suscríbete a la suscripción a Pub/Sub Lite con cualquiera de los métodos que se muestran en Recibe mensajes de suscripciones Lite.

Reenvía mensajes de Pub/Sub Lite a Kafka

En esta sección, se describe cómo iniciar el conector de origen, publicar mensajes en Pub/Sub Lite y leer los mensajes reenviados desde Kafka.

  1. Usa Google Cloud CLI para crear una reserva de Pub/Sub Lite.

    gcloud pubsub lite-reservations create RESERVATION_NAME \
--location=LOCATION \
--throughput-capacity=4

    Reemplaza lo siguiente:

    • RESERVATION_NAME: Es el nombre de la reserva de Pub/Sub Lite.
    • LOCATION: Es la ubicación de la reserva.

  2. Usa Google Cloud CLI para crear un tema de Pub/Sub Lite con una suscripción.

    gcloud pubsub lite-topics create LITE_TOPIC \
--location=LOCATION \
--partitions=2 \
--per-partition-bytes=30GiB \
--throughput-reservation=RESERVATION_NAME

gcloud pubsub lite-subscriptions create LITE_SUBSCRIPTION \
--location=LOCATION \
--topic=LITE_TOPIC

    Reemplaza lo siguiente:

    • LITE_TOPIC: Es el nombre del tema de Pub/Sub Lite.
    • LOCATION: Es la ubicación del tema. El valor debe coincidir con la ubicación de la reserva.
    • RESERVATION_NAME: Es el nombre de la reserva de Pub/Sub Lite.
    • LITE_SUBSCRIPTION: Es el nombre de una suscripción de Pub/Sub Lite para el tema.

  3. Abre el archivo llamado /config/pubsub-lite-source-connector.properties en un editor de texto. Agrega valores para las siguientes propiedades, que están marcadas como "TODO" en los comentarios:

    topic=KAFKA_TOPIC
pubsublite.project=PROJECT_ID
pubsublite.location=LOCATION
pubsublite.subscription=LITE_SUBSCRIPTION

    Reemplaza lo siguiente:

    • KAFKA_TOPIC: Son los temas de Kafka para recibir los mensajes de Pub/Sub.
    • PROJECT_ID: Es el proyecto de Google Cloud que contiene el tema de Pub/Sub.
    • LOCATION: Es la ubicación del tema de Pub/Sub Lite.
    • LITE_SUBSCRIPTION: Es el tema de Pub/Sub Lite.

  4. Desde el directorio de Kafka, ejecuta el siguiente comando:

    bin/connect-standalone.sh \
  config/connect-standalone.properties \
  config/pubsub-lite-source-connector.properties

  5. Publica mensajes en el tema de Pub/Sub Lite con cualquiera de los métodos que se muestran en Publica mensajes en temas de Lite.

  6. Lea el mensaje de Kafka. Sigue los pasos de la guía de inicio rápido de Apache Kafka para leer los mensajes del tema de Kafka.

Conversión de mensajes

Un registro Kafka contiene una clave y un valor, que son arrays de bytes de longitud variable. De manera opcional, un registro Kafka también puede tener encabezados, que son pares clave-valor. Un mensaje de Pub/Sub Lite tiene los siguientes campos:

  • key: Tecla de mensaje (bytes)
  • data: Datos de mensajes (bytes)
  • attributes: cero o más atributos Cada atributo es un mapa (key,values[]). Un mismo atributo puede tener varios valores.
  • event_time: Una marca de tiempo del evento opcional proporcionada por el usuario

Kafka Connect utiliza conversores para serializar claves y valores hacia y desde Kafka. Para controlar la serialización, establece las siguientes propiedades en los archivos de configuración del conector:

  • key.converter: El conversor que se usa para serializar claves de registro
  • value.converter: el convertidor que se usa para serializar valores de registro.

Conversión de Kafka a Pub/Sub Lite

El conector de receptores convierte los registros de Kafka en mensajes de Pub/Sub Lite de la siguiente manera.

Registro de Kafka (SinkRecord) Mensaje de Pub/Sub Lite
Clave key
Valor data
Encabezados attributes
Marca de tiempo eventTime
Tipo de marca de tiempo attributes["x-goog-pubsublite-source-kafka-event-time-type"]
Tema attributes["x-goog-pubsublite-source-kafka-topic"]
Partition attributes["x-goog-pubsublite-source-kafka-offset"]
Desplazamiento attributes["x-goog-pubsublite-source-kafka-partition"]

Las claves, los valores y los encabezados se codifican de la siguiente manera:

  • Los esquemas nulos se tratan como esquemas de string.
  • Las cargas útiles de bytes se escriben directamente sin conversión.
  • Las cargas útiles de string, de número entero y de punto flotante se codifican en una secuencia de bytes UTF-8.
  • Todas las demás cargas útiles se codifican en un tipo de búfer de protocolo Value y, luego, se convierten en una string de bytes.
    • Los campos de string anidados se codifican en un protobuf Value.
    • Los campos de bytes anidados están codificados en un Value de protobuf que contiene los bytes codificados en base64.
    • Los campos numéricos anidados están codificados como un doble en un Value de protobuf.
    • No se admiten mapas con claves de array, mapa o struct.

Conversión de Pub/Sub Lite a Kafka

El conector de origen convierte los mensajes de Pub/Sub Lite en registros de Kafka de la siguiente manera:

Mensaje de Pub/Sub Lite Registro de Kafka (SourceRecord)
key Clave
data Valor
attributes Encabezados
event_time Marca de tiempo Si event_time no está presente, se usa la hora de publicación.

Opciones de configuración

Además de los parámetros de configuración que proporciona la API de Kafka Connect, el conector admite los siguientes parámetros de configuración de Pub/Sub Lite.

Opciones de configuración del conector de receptores

El conector del receptor admite las siguientes opciones de configuración.

Parámetro de configuración Tipo de datos Descripción
connector.class String Obligatorio. La clase Java para el conector. Para el conector de receptores de Pub/Sub Lite, el valor debe ser com.google.pubsublite.kafka.sink.PubSubLiteSinkConnector.
gcp.credentials.file.path String Opcional. La ruta a un archivo que almacena las credenciales de Google Cloud para autenticar Pub/Sub Lite.
gcp.credentials.json String Opcional. Un BLOB JSON que contiene Google Cloud para autenticar Pub/Sub Lite.
pubsublite.location String Obligatorio. La ubicación del tema de Pub/Sub Lite.
pubsublite.project String Obligatorio. El Google Cloud que contiene el tema de Pub/Sub Lite.
pubsublite.topic String Obligatorio. El tema de Pub/Sub Lite en el que se deben publicar los registros de Kafka.
topics String Obligatorio. Una lista separada por comas de temas de Kafka desde los que se debe leer.

Opciones de configuración del conector de origen

El conector de origen admite las siguientes opciones de configuración.

Parámetro de configuración Tipo de datos Descripción
connector.class String Obligatorio. La clase Java para el conector. Para el conector de origen de Pub/Sub Lite, el valor debe ser com.google.pubsublite.kafka.source.PubSubLiteSourceConnector.
gcp.credentials.file.path String Opcional. La ruta a un archivo que almacena las credenciales de Google Cloud para autenticar Pub/Sub Lite.
gcp.credentials.json String Opcional. Un BLOB JSON que contiene Google Cloud para autenticar Pub/Sub Lite.
kafka.topic String Obligatorio. El tema de Kafka que recibe mensajes de Pub/Sub Lite.
pubsublite.location String Obligatorio. La ubicación del tema de Pub/Sub Lite.
pubsublite.partition_flow_control.bytes Long

La cantidad máxima de bytes pendientes por partición de Pub/Sub Lite.

Valor predeterminado: 20,000,000
pubsublite.partition_flow_control.messages Long

La cantidad máxima de mensajes pendientes por partición de Pub/Sub Lite.

Valor predeterminado: Long.MAX_VALUE
pubsublite.project String Obligatorio. El proyecto de Google Cloud que contiene el tema de Pub/Sub Lite.
pubsublite.subscription String Obligatorio. El nombre de la suscripción a Pub/Sub Lite desde la que se extraen los mensajes.

¿Qué sigue?