Conectar o Pub/Sub Lite ao Apache Kafka

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

• Clientes atuais: o Pub/Sub Lite vai continuar funcionando 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 Conecte 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. É comum usadas em arquiteturas distribuídas para permitir a comunicação entre acoplados. O Pub/Sub Lite é um serviço gerenciado para enviar e receber mensagens de forma assíncrona. Assim como no Kafka, é possível usar Pub/Sub Lite para comunicação entre componentes em sua nuvem do Terraform.

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 os 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 registros de uma solução Kafka local e os envia para 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 exige Kafka Connect (em inglês), que é um framework para streaming de dados entre o Kafka e outros sistemas. Para usar é necessário executar o Kafka Connect junto com o cluster do Kafka.

Para seguir este documento, é necessário ter familiaridade com o Kafka 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. Enviar 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

Instale o Kafka

Siga o Guia de início rápido do Apache Kafka para instalar um Kafka de nó único na máquina local. Conclua essas etapas em guia de 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 de Kafka do grupo do Pub/Sub precisa ser autenticado com o Pub/Sub para 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_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_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.

Copie 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 de da instalação do Kafka.

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

Esses arquivos contêm as configurações do 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ê baixado.
2. No diretório binário do Kafka Connect, abra o arquivo chamado config/connect-standalone.properties em um editor de texto.
3. Se a plugin.path property estiver comentada, remova a marca de 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 independente, 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 do coletor, publicar eventos no Kafka e ler as mensagens encaminhadas do Pub/Sub Lite.

1. Use a CLI do Google Cloud 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 do Pub/Sub Lite reserva.
   • LOCATION: o local da reserva.

2. Use a CLI do Google Cloud 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 deve corresponder ao local da reserva.
   • RESERVATION_NAME: o nome da reserva do Pub/Sub Lite.
   • LITE_SUBSCRIPTION: o nome de um Pub/Sub Lite uma assinatura 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 se originou.
   • 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 que será recebido do Kafka.

4. No diretório 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 CLI do Google Cloud 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 do Pub/Sub Lite reserva.
   • LOCATION: o local do 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 deve corresponder ao local da reserva.
   • RESERVATION_NAME: o nome da reserva do Pub/Sub Lite.
   • LITE_SUBSCRIPTION: o nome de um Pub/Sub Lite uma assinatura para o tópico.

3. Abra o arquivo /config/pubsub-lite-source-connector.properties em um editor de texto. Adicione valores para as seguintes propriedades, que estão marcadas "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 que receberão o 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 Publicação de 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 Kafka; contém uma chave e um valor, que são matrizes de bytes de comprimento variável. Opcionalmente, um O registro 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 da 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 conversores 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 registros do Kafka em mensagens do Pub/Sub Lite da seguinte forma.

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"]

Chaves, valores e 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 para um protobuf Value que contém a bytes codificados em base64.
  • Campos numéricos aninhados são codificados como um 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 Kafka (SourceRecord)
key	Chave
data	Valor
attributes	Cabeçalhos
event_time	Carimbo de data/hora Se event_time não estiver presente, o editor tempo é usado.

Opções de configuração

Além das configurações fornecidas pela API Kafka Connect, a Ele é compatível com as configurações do Pub/Sub Lite a seguir.

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

O conector do coletor é compatível com as opções de configuração a seguir.

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 as 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 para autenticar o Pub/Sub Lite.
pubsublite.location	String	Obrigatório. A localização do Tópico do Pub/Sub Lite.
pubsublite.project	String	Obrigatório. O Google Cloud que contém os 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 Kafka para ler.

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

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

Configuração	Tipo de dado	Descrição
connector.class	String	Obrigatório. A classe Java do conector. Para 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 as 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 para autenticar o Pub/Sub Lite.
kafka.topic	String	Obrigatório. O tópico Kafka que recebe mensagens 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 a Tópico do Pub/Sub Lite.
pubsublite.subscription	String	Obrigatório. O nome do Pub/Sub Lite uma assinatura para receber mensagens.

A seguir

• Entenda 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.