Conectar o Pub/Sub Lite ao Apache Kafka

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

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.

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.

    • 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:myemail@example.com.

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

    • 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:myemail@example.com.

    • Replace ROLE with each individual role.

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