Conectar o Pub/Sub Lite ao Apache Kafka

Observação: o Pub/Sub Lite foi descontinuado. A partir de 18 de março de 2026, o Pub/Sub Lite será desativado.

• Clientes atuais: o Pub/Sub Lite vai continuar funcional até 18 de março de 2026. Se você não tiver usado o Pub/Sub Lite no período de 90 dias anterior a 24 de setembro de 2024 (26 de junho de 2024 a 24 de setembro de 2024), não será possível acessar o Pub/Sub Lite a partir de 24 de setembro de 2024.
• Novos clientes: o Pub/Sub Lite não estará mais disponível para novos clientes depois de 24 de setembro de 2024.

É possível migrar o serviço Pub/Sub Lite para o Google Cloud Managed Service para Apache Kafka ou o Pub/Sub.

Este documento descreve como integrar o Apache Kafka e o Pub/Sub Lite usando o conector do Kafka do grupo do Pub/Sub.

Observação: também é possível usar esse conector com o Pub/Sub. Consulte Conectar o Pub/Sub ao Apache Kafka.

Sobre o conector de Kafka do grupo do Pub/Sub

O Apache Kafka é uma plataforma de código aberto para eventos de streaming. Ele é usado com frequência em arquiteturas distribuídas para permitir a comunicação entre componentes acoplados com flexibilidade. O Pub/Sub Lite é um serviço gerenciado para enviar e receber mensagens de forma assíncrona. Assim como no Kafka, você pode usar o Pub/Sub Lite para se comunicar entre componentes na sua arquitetura de nuvem.

O conector do Kafka do grupo do Pub/Sub permite integrar esses dois sistemas. Os seguintes conectores estão empacotados no JAR do conector:

• O conector do coletor lê registros de um ou mais tópicos do Kafka e os publica no Pub/Sub Lite.
• O conector de origem lê mensagens de um tópico do Pub/Sub Lite e as publica no Kafka.

Confira alguns cenários em que você pode usar o conector de Kafka do grupo do Pub/Sub:

• Você está migrando uma arquitetura baseada em Kafka para o Google Cloud.
• Você tem um sistema de front-end que armazena eventos no Kafka fora do Google Cloud, mas também usa o Google Cloud para executar alguns dos seus serviços de back-end, que precisam receber os eventos do Kafka.
• Você coleta logs de uma solução Kafka local e os envia ao Google Cloud para análise de dados.
• Você tem um sistema de front-end que usa o Google Cloud, mas também armazena dados localmente usando o Kafka.

O conector requer o Kafka Connect, que é uma estrutura para streaming de dados entre o Kafka e outros sistemas. Para usar o conector, execute o Kafka Connect com seu cluster do Kafka.

Neste documento, presumimos que você tenha familiaridade com o Kafka e o Pub/Sub Lite. Para começar a usar o Pub/Sub Lite, consulte Publicar e receber mensagens no Pub/Sub Lite usando o console do Google Cloud.

Começar a usar o conector de Kafka do grupo do Pub/Sub

Esta seção orienta você nas seguintes tarefas:

1. Configure o conector de Kafka do grupo do Pub/Sub.
2. Envie eventos do Kafka para o Pub/Sub Lite.
3. Enviar mensagens do Pub/Sub Lite para o Kafka.

Observação: esta seção usa o Kafka Connect no modo independente, que é adequado para testes. Para sistemas de produção, o modo distribuído é recomendado. Para informações sobre como executar o Kafka Connect no modo distribuído, consulte Como executar o Kafka Connect na documentação do Apache Kafka.

Pré-requisitos

Instalar o Kafka

Siga o Guia de início rápido do Apache Kafka para instalar um nó único do Kafka na sua máquina local. Siga estas etapas no início rápido:

1. Faça o download da versão mais recente do Kafka e extraia o arquivo.
2. Inicie o ambiente do Kafka.
3. Crie um tópico do Kafka.

Autenticar

O conector do Kafka do grupo do Pub/Sub precisa ser autenticado com o Pub/Sub para enviar e receber mensagens do Pub/Sub. Para configurar a autenticação, siga estas etapas:

1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.
2. Install the Google Cloud CLI.

3. To initialize the gcloud CLI, run the following command:

   gcloud init

4. Create or select a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   • Create a Google Cloud project:

     gcloud projects create PROJECT_ID

     Replace PROJECT_ID with a name for the Google Cloud project you are creating.

   • Select the Google Cloud project that you created:

     gcloud config set project PROJECT_ID

     Replace PROJECT_ID with your Google Cloud project name.

5. Create local authentication credentials for your user account:

   gcloud auth application-default login

6. Grant roles to your user account. Run the following command once for each of the following IAM roles: roles/pubsublite.admin

   gcloud projects add-iam-policy-binding PROJECT_ID --member="user:USER_IDENTIFIER" --role=ROLE

   • Replace PROJECT_ID with your project ID.

   • Replace USER_IDENTIFIER with the identifier for your user account. For example, user:[e-mail].

   • Replace ROLE with each individual role.
7. Install the Google Cloud CLI.

8. To initialize the gcloud CLI, run the following command:

   gcloud init

9. Create or select a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   • Create a Google Cloud project:

     gcloud projects create PROJECT_ID

     Replace PROJECT_ID with a name for the Google Cloud project you are creating.

   • Select the Google Cloud project that you created:

     gcloud config set project PROJECT_ID

     Replace PROJECT_ID with your Google Cloud project name.

10. Create local authentication credentials for your user account:

    gcloud auth application-default login

11. Grant roles to your user account. Run the following command once for each of the following IAM roles: roles/pubsublite.admin

    gcloud projects add-iam-policy-binding PROJECT_ID --member="user:USER_IDENTIFIER" --role=ROLE

    • Replace PROJECT_ID with your project ID.

    • Replace USER_IDENTIFIER with the identifier for your user account. For example, user:[e-mail].

    • Replace ROLE with each individual role.

Observação: para cargas de trabalho de produção, recomendamos usar a federação de identidade da carga de trabalho para autenticação.

Fazer o download do JAR do conector

Faça o download do arquivo JAR do conector para sua máquina local. Para mais informações, consulte Adquirir o conector no readme do GitHub.

Copiar os arquivos de configuração do conector

1. Clone ou faça o download do repositório do GitHub para o conector.

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

2. Copie o conteúdo do diretório config para o subdiretório config da sua instalação do Kafka.

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

Esses arquivos contêm configurações para o conector.

Atualizar a configuração do Kafka Connect

1. Navegue até o diretório que contém o binário do Kafka Connect que você fez o download.
2. No diretório binário do Kafka Connect, abra o arquivo chamado config/connect-standalone.properties em um editor de texto.
3. Se o plugin.path property estiver comentado, remova o comentário.

4. Atualize o plugin.path property para incluir o caminho para o JAR do conector.

   Exemplo:

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

5. Defina a propriedade offset.storage.file.filename como um nome de arquivo local. No modo autônomo, o Kafka usa esse arquivo para armazenar dados de deslocamento.

   Exemplo:

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

Encaminhar eventos do Kafka para o Pub/Sub Lite

Esta seção descreve como iniciar o conector de coletor, publicar eventos no Kafka e ler as mensagens encaminhadas do Pub/Sub Lite.

1. Use a Google Cloud CLI para criar uma reserva do Pub/Sub Lite.

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

   Substitua:

   • RESERVATION_NAME: o nome da reserva do Pub/Sub Lite.
   • LOCATION: o local da reserva.

2. Use a Google Cloud CLI para criar um tópico do Pub/Sub Lite com uma assinatura.

   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

   Substitua:

   • LITE_TOPIC: o nome do tópico do Pub/Sub Lite para receber mensagens do Kafka.
   • LOCATION: o local do tópico. O valor precisa corresponder ao local da reserva.
   • RESERVATION_NAME: o nome da reserva do Pub/Sub Lite.
   • LITE_SUBSCRIPTION: o nome de uma assinatura do Pub/Sub Lite para o tópico.

3. Abra o arquivo /config/pubsub-lite-sink-connector.properties em um editor de texto. Adicione valores para as seguintes propriedades, marcadas como "TODO" nos comentários:

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

   Substitua:

   • KAFKA_TOPICS: uma lista separada por vírgulas de tópicos do Kafka para leitura.
   • PROJECT_ID: o projeto do Google Cloud que contém seu tópico do Pub/Sub Lite.
   • LOCATION: o local do tópico do Pub/Sub Lite.
   • LITE_TOPIC: o tópico do Pub/Sub Lite para receber mensagens do Kafka.

4. No diretório do Kafka, execute o seguinte comando:

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

5. Siga as etapas no Guia de início rápido do Apache Kafka para gravar alguns eventos no seu tópico do Kafka.

6. Assine a assinatura do Pub/Sub Lite usando qualquer um dos métodos mostrados em Como receber mensagens de assinaturas do Lite.

Encaminhar mensagens do Pub/Sub Lite para o Kafka

Esta seção descreve como iniciar o conector de origem, publicar mensagens no Pub/Sub Lite e ler as mensagens encaminhadas do Kafka.

1. Use a Google Cloud CLI para criar uma reserva do Pub/Sub Lite.

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

   Substitua:

   • RESERVATION_NAME: o nome da reserva do Pub/Sub Lite.
   • LOCATION: o local da reserva.

2. Use a Google Cloud CLI para criar um tópico do Pub/Sub Lite com uma assinatura.

   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

   Substitua:

   • LITE_TOPIC: o nome do tópico do Pub/Sub Lite.
   • LOCATION: o local do tópico. O valor precisa corresponder ao local da reserva.
   • RESERVATION_NAME: o nome da reserva do Pub/Sub Lite.
   • LITE_SUBSCRIPTION: o nome de uma assinatura do Pub/Sub Lite para o tópico.

3. Abra o arquivo chamado /config/pubsub-lite-source-connector.properties em um editor de texto. Adicione valores para as seguintes propriedades, marcadas como "TODO" nos comentários:

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

   Substitua:

   • KAFKA_TOPIC: os tópicos do Kafka para receber as mensagens do Pub/Sub.
   • PROJECT_ID: o projeto do Google Cloud que contém seu tópico do Pub/Sub.
   • LOCATION: o local do tópico do Pub/Sub Lite.
   • LITE_SUBSCRIPTION: o tópico do Pub/Sub Lite.

4. No diretório do Kafka, execute o seguinte comando:

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

5. Publique mensagens no tópico do Pub/Sub Lite usando qualquer um dos métodos mostrados em Como publicar mensagens em tópicos do Lite.

6. Leia a mensagem do Kafka. Siga as etapas no Guia de início rápido do Apache Kafka para ler as mensagens do tópico do Kafka.

Conversão de mensagem

Um registro do Kafka contém uma chave e um valor, que são matrizes de bytes de comprimento variável. Opcionalmente, um registro do Kafka também pode ter cabeçalhos, que são pares de chave-valor. Uma mensagem do Pub/Sub Lite tem os seguintes campos:

• key: chave de mensagem (bytes)
• data: dados da mensagem (bytes)
• attributes: zero ou mais atributos. Cada atributo é um mapa (key,values[]). Um único atributo pode ter vários valores.
• event_time: um carimbo de data/hora de evento opcional fornecido pelo usuário.

O Kafka Connect usa convertidores para serializar chaves e valores de e para o Kafka. Para controlar a serialização, defina as seguintes propriedades nos arquivos de configuração do conector:

• key.converter: o conversor usado para serializar chaves de registro.
• value.converter: o conversor usado para serializar valores de registro.

Conversão do Kafka para o Pub/Sub Lite

O conector do coletor converte os registros do Kafka em mensagens do Pub/Sub Lite da seguinte maneira.

Registro do Kafka (SinkRecord)	Mensagem do Pub/Sub Lite
Chave	key
Valor	data
Cabeçalhos	attributes
Carimbo de data/hora	eventTime
Tipo de carimbo de data/hora	attributes["x-goog-pubsublite-source-kafka-event-time-type"]
Tópico	attributes["x-goog-pubsublite-source-kafka-topic"]
Partição	attributes["x-goog-pubsublite-source-kafka-offset"]
Deslocamento	attributes["x-goog-pubsublite-source-kafka-partition"]

As chaves, os valores e os cabeçalhos são codificados da seguinte maneira:

• Os esquemas nulos são tratados como esquemas de string.
• Os payloads de bytes são gravados diretamente sem conversão.
• Os payloads de string, inteiro e ponto flutuante são codificados em uma sequência de bytes UTF-8.
• Todos os outros payloads são codificados em um tipo de buffer de protocolo Value e convertidos em uma string de bytes.
  • Os campos de string aninhados são codificados em um Value do protobuf.
  • Os campos de bytes aninhados são codificados em um Value protobuf que contém os bytes codificados em base64.
  • Os campos numéricos aninhados são codificados como um número duplo em um protobuf Value.
  • Mapas com chaves de matriz, mapa ou estrutura não são aceitos.

Conversão do Pub/Sub Lite para o Kafka

O conector de origem converte as mensagens do Pub/Sub Lite em registros do Kafka da seguinte maneira:

Mensagem do Pub/Sub Lite	Registro do Kafka (SourceRecord)
key	Chave
data	Valor
attributes	Cabeçalhos
event_time	Carimbo de data/hora Se event_time não estiver presente, o horário de publicação será usado.

Opções de configuração

Além das configurações fornecidas pela API Kafka Connect, o conector oferece suporte às seguintes configurações do Pub/Sub Lite.

Opções de configuração do conector de sumidouro

O conector de sink oferece suporte às seguintes opções de configuração.

Configuração	Tipo de dado	Descrição
connector.class	String	Obrigatório. A classe Java do conector. Para o conector de destino do Pub/Sub Lite, o valor precisa ser com.google.pubsublite.kafka.sink.PubSubLiteSinkConnector.
gcp.credentials.file.path	String	Opcional. O caminho para um arquivo que armazena credenciais do Google Cloud para autenticar o Pub/Sub Lite.
gcp.credentials.json	String	Opcional. Um blob JSON que contém o Google Cloud para autenticação do Pub/Sub Lite.
pubsublite.location	String	Obrigatório. O local do tópico do Pub/Sub Lite.
pubsublite.project	String	Obrigatório. O Google Cloud que contém o tópico do Pub/Sub Lite.
pubsublite.topic	String	Obrigatório. O tópico do Pub/Sub Lite em que os registros do Kafka serão publicados.
topics	String	Obrigatório. Uma lista separada por vírgulas de tópicos do Kafka para leitura.

Opções de configuração do conector de origem

O conector de origem é compatível com as seguintes opções de configuração.

Configuração	Tipo de dado	Descrição
connector.class	String	Obrigatório. A classe Java do conector. Para o conector de origem do Pub/Sub Lite, o valor precisa ser com.google.pubsublite.kafka.source.PubSubLiteSourceConnector.
gcp.credentials.file.path	String	Opcional. O caminho para um arquivo que armazena credenciais do Google Cloud para autenticar o Pub/Sub Lite.
gcp.credentials.json	String	Opcional. Um blob JSON que contém o Google Cloud para autenticação do Pub/Sub Lite.
kafka.topic	String	Obrigatório. O tópico do Kafka que recebe mensagens do Pub/Sub Lite.
pubsublite.location	String	Obrigatório. O local do tópico do Pub/Sub Lite.
pubsublite.partition_flow_control.bytes	Long	O número máximo de bytes pendentes por partição do Pub/Sub Lite. Padrão: 20.000.000
pubsublite.partition_flow_control.messages	Long	O número máximo de mensagens pendentes por partição do Pub/Sub Lite. Padrão: Long.MAX_VALUE
pubsublite.project	String	Obrigatório. O projeto do Google Cloud que contém o tópico do Pub/Sub Lite.
pubsublite.subscription	String	Obrigatório. O nome da assinatura do Pub/Sub Lite de onde as mensagens serão extraídas.

A seguir

• Entender as diferenças entre o Kafka e o Pub/Sub.
• Saiba mais sobre o conector do Kafka do grupo do Pub/Sub.
• Consulte o repositório do GitHub do conector do Kafka do Pub/Sub.