Assinatura de eventos Kafka

Configuração do produtor de eventos Kafka

Você pode configurar o seu produtor de mensagens Kafka para enviar mensagens para Code Engine Kafka. Use sua assinatura de eventos Code Engine Kafka para acionar aplicativos ou jobs quando uma mensagem Kafka for recebida.

Para começar, crie uma instância de serviço Event Streams para o seu serviço de streaming de eventos. Enquanto você pode usar o console ou a CLI, as etapas a seguir descrevem como configurar o produtor de eventos Event Streams com o CLI.

1. Crie uma instância de serviço para Event Streams. O nome do serviço CLI Event Streams é messagehub. Para este exemplo, crie uma instância de serviço Event Streams que é denominada myeventstream.

   ibmcloud resource service-instance-create myeventstream messagehub lite us-south
   

2. Crie uma chave de serviço para fornecer credenciais à sua instância de serviço.

   ibmcloud resource service-key-create myeventstream-key Manager --instance-name myeventstream
   

   Saída de exemplo

   Creating service key of service instance myeventstream under account <user_account>...
   OK
   Service key crn:v1:bluemix:public:messagehub:us-south:a/e43abfcbd191404cb17ef650e9681dd3:c0736069-3f4a-438a-b614-6846877d692d:resource-key:4c8edfdb-abcd-abcd-abcd-abcdabcdabcd was created.
   
   Name:          myeventstream-key
   ID:            crn:v1:bluemix:public:messagehub:us-south:a/e43abfcbd191404cb17ef650e9681dd3:c0736069-3f4a-438a-b614-6846877d692d:resource-key:4c8edfdb-abcd-abcd-abcd-abcdabcdabcd
   Created At:    Mon Mar 21 18:36:09 UTC 2022
   State:         active
   Credentials:
               api_key:                  abcdeH9tu3qE5Sn8VbJfcDEWtjR_l0iPisB3abcdefgh
               apikey:                   abcdeH9tu3qE5Sn8VbJfcDEWtjR_l0iPisB3abcdefgh
               iam_apikey_description:   Auto-generated for key crn:v1:bluemix:public:messagehub:us-south:a/e43abfcbd191404cb17ef650e9681dd3:c0736069-3f4a-438a-b614-6846877d692d:resource-key:4c8edfdb-abcd-abcd-abcd-abcdabcdabcd
               iam_apikey_name:          myeventstream-key
               iam_role_crn:             crn:v1:bluemix:public:iam::::serviceRole:Manager
               iam_serviceid_crn:        crn:v1:bluemix:public:iam-identity::a/e43abfcbd191404cb17ef650e9681dd3::serviceid:ServiceId-3e99caa5-b174-4f04-9845-5c5d783b8bc7
               instance_id:              c0736069-3f4a-438a-b614-6846877d692d
               kafka_admin_url:          https://abcdabcdabcdabcd.svc07.us-south.eventstreams.cloud.ibm.com
               kafka_brokers_sasl:       [broker-1-abcdabcdabcdabcd.kafka.svc07.us-south.eventstreams.cloud.ibm.com:9093 broker-2-abcdabcdabcdabcd.kafka.svc07.us-south.eventstreams.cloud.ibm.com:9093 broker-5-abcdabcdabcdabcd.kafka.svc07.us-south.eventstreams.cloud.ibm.com:9093 broker-3-abcdabcdabcdabcd.kafka.svc07.us-south.eventstreams.cloud.ibm.com:9093 broker-4-abcdabcdabcdabcd.kafka.svc07.us-south.eventstreams.cloud.ibm.com:9093 broker-0-abcdabcdabcdabcd.kafka.svc07.us-south.eventstreams.cloud.ibm.com:9093]
               kafka_http_url:           https://abcdabcdabcdabcd.svc07.us-south.eventstreams.cloud.ibm.com
               password:                 abcdeH9tu3qE5Sn8VbJfcDEWtjR_l0iPisB3abcdefgh
               user:                     token
   

   Anote os valores para user, password e kafka-brokers_sasl para a sua chave de serviço. Você precisa desta informação quando configurar sua assinatura Code Engine Kafka. Os valores para password e apikey são os mesmos na chave de serviço para a sua instância de serviço Event Streams. Você também pode usar o comando ibmcloud resource service-key myeventstream-key para recuperar as informações da chave de serviço.

3. Inicialize o plug-in Event Streams em relação à sua instância de serviço Event Streams.

   ibmcloud es init --instance-name myeventstream
   

4. Crie um tópico Event Streams.

   ibmcloud es topic-create kafka-topic1
   

Configuração de um app de amostra Code Engine para produzir mensagens Kafka

Para este tutorial, configure um aplicativo Code Engine para atuar como um produtor de eventos de mensagens Kafka. O objetivo deste app kafka-sender-app é conectar-se à sua instância Event Streams e produzir (enviar) mensagens Kafka para um receptor das mensagens (consumidorKafka ). Este app que produz eventos para mensagens Kafka usa o Code Engine Kafka sender sample app para enviar mensagens Kafka. Esta imagem de remetente de amostra requer a variável de ambiente BROKERS e um segredo que inclui as credenciais password.

1. Crie um segredo com credenciais que são necessárias pelas amostras Code Engine Kafka. Por exemplo, crie o segredo kafka-subscription-secret, para conter as credenciais necessárias tanto para o app de amostra do remetente Kafka quanto para a assinatura de eventos Kafka, que usa a amostra do receptor Kafka. Essas credenciais são necessárias para a amostra do app do emissor Kafka e para a assinatura de eventos Code Engine Kafka para se comunicar com a instância de serviço para Event Streams. Enquanto não é necessário que você crie este segredo antes de criar o app do remetente Kafka e a assinatura do evento, esta ação simplifica as etapas necessárias.

   Para criar o segredo kafka-subscription-secret, inclua uma variável de ambiente literal para password, e username. Para obter mais informações, consulte crie um segredo com a CLI.

   • Especifique a chave username com o valor de user que está listado nos detalhes das credenciais de serviço na instância de serviço Event Streams. Para a instância de serviço Event Streams, este valor é token. Esta chave é necessária para autenticação entre a assinatura de eventos Code Engine Kafka e o intermediário de mensagens Kafka.

   • Especifique a chave password com o valor de apikey que está listado nos detalhes das credenciais de serviço na instância de serviço Event Streams. Esta chave é necessária para a amostra do remetente, e para ativar as comunicações entre a assinatura de eventos Code Engine Kafka e o intermediário de mensagens Kafka.

     ibmcloud ce secret create --name kafka-subscription-secret --from-literal password=<value_of_apikey> --from-literal username=<value_of_user>
     

     Por exemplo,

     ibmcloud ce secret create --name kafka-subscription-secret --from-literal password=abcdeH9tu3qE5Sn8VbJfcDEWtjR_l0iPisB3abcdefgh --from-literal username=token
     

2. Crie o kafka-sender-app com as seguintes informações.

   • Especifique a opção --image para referencia a imagem do contêiner icr.io/codeengine/kafka-sender. Essa imagem é construída a partir do sender.go, que está disponível a partir do Amostras para IBM Cloud Code Engine GitHub repo. Este app de remetente de amostra requer as credenciais password que são armazenadas em seu kafka-subscription-secret, e ele requer a variável de ambiente BROKERS.

   • Especifique a opção --env-from-secret para referenciar o segredo completo, kafka-subscription-secret, que contém as credenciais password.

   • Especifique a opção --env para adicionar uma variável de ambiente literal, BROKERS, e forneça o nome de um dos hosts dos intermediários listados nos detalhes das credenciais de serviço na instância de serviço Event Streams. No entanto, se você quiser especificar mais de um hostname do intermediário, use o formato --env BROKERS-broker1,broker2,broker3.

   • (opcional) Especifique a opção --min-scale=1 para que o aplicativo sempre tenha uma instância em execução e não seja dimensionado para zero. Configurar o app para sempre ter uma instância em execução é útil quando você visualiza logs. Se você estiver em execução em um ambiente de produção, considere o custo de manter uma instância em execução de seu app ou se deseja Code Engine para autoscale a zero. Por padrão, o app escala para zero quando não em uso.

     ibmcloud ce app create --name kafka-sender-app --image icr.io/codeengine/kafka-sender --env-from-secret kafka-subscription-secret --env BROKERS=broker-4-abcdabcdabcdabcd.kafka.svc07.us-south.eventstreams.cloud.ibm.com:9093 --min-scale 1
     

3. Depois de implementar este app, execute o comando app get para confirmar se o app está em ready status.

   ibmcloud ce app get -n kafka-sender-app
   

Você criou o app kafka-sender-app para produzir mensagens Kafka para as assinaturas de eventos Code Engine, e você criou o segredo kafka-subscription-secret que contém as credenciais necessárias.

Configuração de uma assinatura Code Engine Kafka

Para Code Engine para trabalhar com eventos Kafka, configure uma assinatura de eventos Code Engine Kafka para conectar-se a Kafka intermediários de eventos e ouvir eventos Kafka. Além disso, configure um app Code Engine para agir como o receptor dos eventos Kafka. A assinatura de eventos Kafka define a relação entre o produtor Kafka (emissor) e o consumidor (receptor) de eventos.

A assinatura de eventos Code Engine Kafka conecta-se ao seu intermediário de mensagens Kafka e envia pedidos de HTTP Post para cada mensagem de entrada Kafka para o aplicativo receptor. Para obter mais informações sobre as informações que estão incluídas com os eventos Kafka, consulte cabeçalhos HTTP e informações do corpo para eventos que são entregues a apps.

1. Crie um aplicativo Code Engine para agir como um consumidor de eventos de mensagens Kafka e receber os eventos Kafka. Por exemplo, crie um aplicativo que seja chamado kafka-receiver-app e que use a imagem icr.io/codeengine/kafka-receiver. Essa imagem é construída a partir do receiver.go, que está disponível a partir do Amostras para IBM Cloud Code Engine GitHub repo. Esta amostra não requer nenhuma variável de ambiente. Opcionalmente, você pode especificar a opção --min-scale=1, de modo que o aplicativo sempre tenha uma instância em execução e não seja dimensionado para zero. Configurar o app para sempre ter uma instância em execução é útil quando você visualiza logs. Se você estiver em execução em um ambiente de produção, considere o custo de manter uma instância em execução de seu app ou se deseja Code Engine para autoscale a zero. Por padrão, o app escala para zero quando não em uso.

   ibmcloud ce app create -n kafka-receiver-app --image icr.io/codeengine/kafka-receiver --min-scale 1
   

   Por padrão, os eventos são encaminhados para a URL raiz do aplicativo de destino. É possível enviar eventos para um destino diferente dentro do app, usando a opção --path. Por exemplo, se a sua assinatura especificar --path /event, o evento será enviado para https://<base application URL>/events.

2. Depois de implementar este app, execute o comando app get para confirmar se o app está em ready status.

   ibmcloud ce app get -n kafka-receiver-app
   

3. Crie uma assinatura de eventos Code Engine Kafka para os seus eventos Kafka usando o comando ibmcloud ce sub kafka create. Use o segredo kafka-subscription-secret que você criou anteriormente para acessar o intermediário de mensagens. Especifique as informações do intermediário com base nas informações de credenciais de serviço para o seu recurso Kafka. Para este exemplo, é possível obter as informações do intermediário a partir da saída do comando ibmcloud resource service-key myeventstream-key. Observe que você deve especificar uma opção --broker para cada intermediário para o seu tópico. A opção --destination especifica o recurso Code Engine que recebe os eventos.

   ibmcloud ce sub kafka create --name mykafkasubscription --destination kafka-receiver-app --secret kafka-subscription-secret --topic kafka-topic1 --broker broker-3-abcdabcdabcdabcd.kafka.svc07.us-south.eventstreams.cloud.ibm.com:9093 --broker broker-5-abcdabcdabcdabcd.kafka.svc07.us-south.eventstreams.cloud.ibm.com:9093 --broker  broker-0-abcdabcdabcdabcd.kafka.svc07.us-south.eventstreams.cloud.ibm.com:9093 --broker broker-1-abcdabcdabcdabcd.kafka.svc07.us-south.eventstreams.cloud.ibm.com:9093 --broker broker-4-abcdabcdabcdabcd.kafka.svc07.us-south.eventstreams.cloud.ibm.com:9093 --broker broker-2-abcdabcdabcdabcd.kafka.svc07.us-south.eventstreams.cloud.ibm.com:9093
   

4. Exibir os detalhes da assinatura do evento Kafka.

   ibmcloud ce sub kafka get -n mykafkasubscription
   

   Saída de exemplo

   Getting Kafka event subscription 'mykafkasubscription'...
   OK
   
   Name:          mykafkasubscription
   [...]
   Destination Type:                 app
   Destination:                      kafka-receiver-app
   Brokers:
   broker-3-abcdabcdabcdabcd.kafka.svc07.us-south.eventstreams.cloud.ibm.com:9093
   broker-5-abcdabcdabcdabcd.kafka.svc07.us-south.eventstreams.cloud.ibm.com:9093
   broker-0-abcdabcdabcdabcd.kafka.svc07.us-south.eventstreams.cloud.ibm.com:9093
   broker-1-abcdabcdabcdabcd.kafka.svc07.us-south.eventstreams.cloud.ibm.com:9093
   broker-4-abcdabcdabcdabcd.kafka.svc07.us-south.eventstreams.cloud.ibm.com:9093
   broker-2-abcdabcdabcdabcd.kafka.svc07.us-south.eventstreams.cloud.ibm.com:9093
   Consumer Group:                   knative-kafka-source-a4072fe1-1dfa-4470-9d07-bf7a0ff8e340
   Topics:
   kafka-topic1
   Secret key reference (user):      kafka-subscription-secret.username
   Secret key reference (password):  kafka-subscription-secret.password
   Ready:                            true
   
   Conditions:
   Type                     OK    Age  Reason
   ConnectionEstablished    true  24s
   InitialOffsetsCommitted  true  24s
   Ready                    true  24s
   Scheduled                true  24s
   SinkProvided             true  24s
   
   Events:
   Type     Reason           Age  Source                  Messages
   Normal   FinalizerUpdate  26s  kafkasource-controller  Updated "mykafkasubscription" finalizers
   

Testando a sua assinatura

Agora que a sua assinatura de eventos Kafka, que faz referência ao aplicativo kafka-receiver-app, é criada, use o kafka-sender-app para enviar eventos de mensagem para o aplicativo receptor.

1. Obtenha a URL pública do app de destino, kafka-sender-app usando o comando ibmcloud ce app get com a opção --output url para encontrar a URL do seu app.

   ibmcloud ce app get -n kafka-sender-app --output url
   

   Saída de exemplo

   https://kafka-sender-app.abcdabcdabc.us-south.codeengine.appdomain.cloud
   

2. Execute o aplicativo de produtor de eventos Kafka, kafka-sender-app para enviar eventos para o aplicativo Code Engine. Ligue para o aplicativo kafka-sender-app com curl e especifique valores para o tópico e o número de mensagens. Use a saída do comando ibmcloud ce app get para encontrar a URL pública do seu aplicativo. Certifique-se de agrupar o valor para curl entre aspas para garantir que ele seja tratado como uma única string. Por exemplo,

   curl "<public_URL_of_Kafka_sender_app>?topic=<your_topic_name>&num=<number_of_messages_to_produce>"
   

   Por exemplo,

   curl "https://kafka-sender-app.abcdabcdabc.us-south.codeengine.appdomain.cloud?topic=kafka-topic1&num=1"
   

3. Visualizar eventos em logs. Quando a sua assinatura de eventos Kafka é criada com um intermediário, tópicos e um segredo de acesso que são válidos, e você tem um aplicativo Kafka que produz mensagens naquele tópico (como kafka-sender-app), então você pode ver eventos em logs para o seu destino Code Engine aplicativo que recebe mensagens Kafka, como kafka-receiver-app. Ao utilizar o app do receptor Kafka (icr.io/codeengine/kafka-receiver), procure por Event data nos logs para o aplicativo receptor ver as mensagens que são recebidas.

   ibmcloud ce app logs -n kafka-receiver-app
   

   Saída de exemplo

   Getting logs for all instances of application 'kafka-receiver-app'...
   OK
   
   kafka-receiver-app-00001-deployment-66976f7988-9xttm/user-container:
   2022/03/31 22:19:45 Listening on port 8080
   2022/03/31 22:19:46 ----------
   2022/03/31 22:19:46 Path: /
   2022/03/31 22:19:46 Header: Accept-Encoding=[gzip]
   2022/03/31 22:19:46 Header: Ce-Id=[partition:0/offset:167]
   2022/03/31 22:19:46 Header: Ce-Source=[/apis/v1/namespaces/glxo4k7nj7d/kafkasources/mykafkasubscription#kafka-topic1]
   2022/03/31 22:19:46 Header: Ce-Specversion=[1.0]
   2022/03/31 22:19:46 Header: Ce-Subject=[partition:0#167]
   2022/03/31 22:19:46 Header: Ce-Time=[2022-03-31T22:19:36.499Z]
   2022/03/31 22:19:46 Header: Ce-Type=[dev.knative.kafka.event]
   2022/03/31 22:19:46 Header: Content-Length=[8]
   2022/03/31 22:19:46 Header: Forwarded=[for=172.30.208.213;proto=http, for=127.0.0.6]
   2022/03/31 22:19:46 Header: K-Proxy-Request=[activator]
   2022/03/31 22:19:46 Header: Traceparent=[00-b033708685c715a7c2384cdf05797785-65540b0937e9b0ce-00]
   2022/03/31 22:19:46 Header: User-Agent=[Go-http-client/1.1]
   2022/03/31 22:19:46 Header: X-B3-Parentspanid=[e1a785d7fdbead6c]
   2022/03/31 22:19:46 Header: X-B3-Sampled=[1]
   2022/03/31 22:19:46 Header: X-B3-Spanid=[abcde9901e6bf83f]
   2022/03/31 22:19:46 Header: X-B3-Traceid=[abcde490a426573772fa0bf60caf5ddb]
   2022/03/31 22:19:46 Header: X-Envoy-Attempt-Count=[1]
   2022/03/31 22:19:46 Header: X-Forwarded-For=[172.30.208.213, 127.0.0.6, 127.0.0.6]
   2022/03/31 22:19:46 Header: X-Forwarded-Proto=[http]
   2022/03/31 22:19:46 Header: X-Request-Id=[abcdeb4e-c5ac-abcd-abcd-60e6278abcde]
   2022/03/31 22:19:46 Event data: test1: 1
   

   Observe que as informações de registro dos aplicativos duram apenas uma hora. Para obter mais informações sobre visualização de logs para apps (ou jobs), consulte Visualizações de logs.

Atualizando sua assinatura

Para atualizar uma assinatura de evento com a CLI, use o comando ibmcloud ce subscription kafka update. O exemplo a seguir atualiza o nome do tópico.

ibmcloud ce sub kafka update -n mykafkasubscription --topic kafka-topic2

Você pode usar o comando ibmcloud ce subscription kafka update para atualizar os valores para a assinatura Kafka. No entanto, não é possível modificar o valor para o grupo de consumidores com este comando. Se você deseja atualizar a assinatura para referencia um tópico diferente, certise-se de que o tópico Kafka existe antes de atualizar a assinatura.

Tutorial de limpeza para assinatura Kafka

Pronto para excluir sua assinatura Kafka, o envio e recebimento de apps, e o segredo? Você pode usar os comandos ibmcloud ce app delete, o ibmcloud ce sub kafka delete e os comandos ibmcloud ce sub kafka delete. Opcionalmente, você pode usar a opção -f para forçar a exclusão do componente sem confirmação.

Quando você exclui a assinatura Kafka, o delete não exclui o app que é referenciado pela assinatura.

Para remover a sua assinatura,

ibmcloud ce sub kafka delete --name mykafkasubscription -f

Para remover o seu aplicativo de recebimento de mensagens Kafka,

ibmcloud ce app delete --name kafka-receiver-app -f

Da mesma forma, é possível remover o kafka-sender-app.

ibmcloud ce app delete --name kafka-sender-app -f

Para remover o kafka-subscription-secret,

ibmcloud ce secret delete --name kafka-subscription-secret -f

Pronto para excluir a sua instância de serviço para a instância de serviço Event Streams ? A opção --recursive especifica para remover todos os recursos para a instância de serviço, o que inclui a chave de serviço associada.

ibmcloud resource service-instance-delete myeventstream --recursive -f

Próximas etapas

Para obter mais informações sobre como trabalhar com inscrições de eventos Kafka, consulte Trabalhando com o produtor de eventos Kafka.

Procurando mais exemplos de código? Confira as Amostras para IBM Cloud Code Engine GitHub repo.