S'abonner aux événements d' Kafka

Grâce à ce tutoriel, vous apprendrez à vous abonner à des événements d' Kafka s à l'aide de l'interface de ligne de commande (CLI) d' IBM Cloud® Code Engine.

Souvent, dans les environnements distribués, vous avez besoin que vos applications ou vos travaux réagissent aux messages (événements) générés à partir d'autres composants, qui sont généralement appelés des producteurs d'événements. Avec Code Engine, vos applications ou vos travaux peuvent recevoir des événements d'intérêt grâce à un abonnement à des producteurs d'événements. Les informations relatives aux événements sont reçues sous forme de demandes HTTP POST pour les applications et sous forme de variables d'environnement pour les travaux.

Le producteur d'événement Kafka recherche les nouveaux messages à afficher dans une instance Kafka. Lorsque vous créez un abonnement Code Engine Kafka pour un ensemble de rubriques, votre application ou votre travail reçoit un événement distinct pour chaque nouveau message qui apparaît dans l'une des rubriques.

Bien que vous puissiez utiliser n'importe quelle instance d' Kafka, les exemples de ce tutoriel utilisent le service IBM® Event Streams for IBM Cloud®. Event Streams est un service de streaming d'événements IBM destiné aux événements Kafka. Pour plus d'informations sur ce service, consultez la documentation de Event Streams.

Avant de commencer

Tous les utilisateurs Code Engine doivent avoir un compte de paiement à la carte. Les tutoriels peuvent entraîner des coûts. Utilisez l'estimateur de coût pour générer une estimation du coût en fonction de l'utilisation envisagée. Pour plus d'informations, voir Tarification Code Engine.

Configuration du générateur d'événements « Kafka »

Vous pouvez configurer votre producteur de messages « Kafka » pour qu'il envoie des messages aux abonnements aux événements « Code Engine » et « Kafka ». Utilisez votre abonnement aux événements « Code Engine » ( Kafka ) pour déclencher des applications ou des tâches lorsqu'un message « Kafka » est reçu.

Pour commencer, créez une instance de service Event Streams pour votre service de diffusion en continu d'événements. Alors que vous pouvez utiliser la console ou l'interface de ligne de commande, les étapes suivantes décrivent comment configurer le fournisseur d'événements Event Streams avec l'interface de ligne de commande.

  1. Créez une instance de service pour Event Streams. Le nom du service CLI Event Streams est messagehub. Pour cet exemple, créez une instance de service Event Streams nommée myeventstream.

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

  2. Créez une clé de service pour fournir des données d'identification à votre instance de service.

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

    Exemple de sortie

    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

    Notez les valeurs de user, password et kafka-brokers_sasl pour votre clé de service. Vous avez besoin de ces informations lorsque vous configurez votre abonnement Code Engine Kafka. Les valeurs de password et apikey sont identiques dans la clé de service de votre instance de service Event Streams. Vous pouvez également utiliser la commande ibmcloud resource service-key myeventstream-key pour extraire les informations de clé de service.

  3. Initialisez le plug-in Event Streams relatif à votre instance de service Event Streams.

    ibmcloud es init --instance-name myeventstream

  4. Créer un sujet « Event Streams ».

    ibmcloud es topic-create kafka-topic1

Configuration d'un exemple d'application Code Engine pour produire des messages Kafka

Pour ce tutoriel, configurez une application Code Engine pour agir en tant que producteur d'événements des messages Kafka. L'objectif de cette application kafka-sender-app est de se connecter à votre instance Event Streams et de produire (envoyer) des messages Kafka à un destinataire des messages (consommateurKafka ). Cette application qui génère des événements pour les messages Kafka utilise l'Code Engine Kafka Kafka pour envoyer des messages Kafka. Cet exemple d'image d'expéditeur requiert la variable d'environnement BROKERS et un secret qui inclut les données d'identification password.

  1. Créez un secret avec les données d'identification requises par les exemples Code Engine Kafka. Par exemple, créez le secret kafka-subscription-secret pour qu'il contienne les données d'identification requises à la fois pour l'exemple d'application d'expéditeur Kafka et pour l'abonnement d'événement Kafka, qui utilise l'exemple de récepteur Kafka. Ces données d'identification sont requises pour l'exemple d'application d'expéditeur Kafka et l'abonnement à l'événement Kafka Code Engine pour communiquer avec l'instance de service pour Event Streams. Bien qu'il ne soit pas nécessaire de créer ce secret avant de créer l'application émettrice Kafka et l'abonnement à l'événement, cette action simplifie les étapes requises.

    Pour créer le secret kafka-subscription-secret, ajoutez une variable d'environnement littérale pour password et username. Pour plus d'informations, voir Création d'un secret avec l'interface de ligne de commande.

    • Spécifiez la clé username avec la valeur user répertoriée dans les détails des données d'identification du service dans l'instance de service Event Streams. Pour l'instance de service Event Streams, cette valeur est token. Cette clé est requise pour l'authentification entre l'abonnement à l'événement Code Engine Kafka et le courtier de messages Kafka.
    • Spécifiez la clé password avec la valeur apikey répertoriée dans les détails des données d'identification du service dans l'instance de service Event Streams. Cette clé est requise pour l'exemple de l'expéditeur et pour activer les communications entre l'abonnement à l'événement Kafka Code Engine et le courtier de messages Kafka.
        ibmcloud ce secret create --name kafka-subscription-secret --from-literal password=<value_of_apikey> --from-literal username=<value_of_user>
    ```
    Par exemple :

    ```txt {: pre}
    ibmcloud ce secret create --name kafka-subscription-secret --from-literal password=abcdeH9tu3qE5Sn8VbJfcDEWtjR_l0iPisB3abcdefgh --from-literal username=token
    ```

  2. Créez l' kafka-sender-app e en indiquant les informations suivantes.

    • Spécifiez l'option --image pour référencer l'image de conteneur icr.io/codeengine/kafka-sender. Cette image est générée à partir de sender.go, qui est disponible dans Exemples pour le référentiel IBM Cloud Code Engine GitHub. Cet exemple d'application d'expéditeur requiert les données d'identification password qui sont stockées dans votre kafka-subscription-secret et requiert la variable d'environnement BROKERS.
    • Spécifiez l'option --env-from-secret pour référencer le secret complet, kafka-subscription-secret, qui contient les données d'identification password.
    • Spécifiez l'option --env pour ajouter une variable d'environnement littérale, BROKERS, et indiquez le nom de l'un des hôtes de courtier répertoriés dans les détails des données d'identification du service dans l'instance de service Event Streams. Toutefois, si vous souhaitez spécifier plusieurs noms d'hôte de courtier, utilisez le format --env BROKERS-broker1,broker2,broker3.
    • (facultatif) Spécifiez l'option « --min-scale=1 » afin que l'application dispose toujours d'une instance en cours d'exécution et ne soit pas réduite à zéro. Le fait de configurer l'application afin de toujours avoir une instance en cours d'exécution est utile lorsque vous affichez les journaux. Si vous travaillez dans un environnement de production, prenez en compte le coût de la conservation d'une instance en cours d'exécution de votre application ou si vous souhaitez que Code Engine soit automatiquement réduit à zéro. Par défaut, l'application est mise à l'échelle à zéro lorsqu'elle n'est pas utilisée.
        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. Après avoir déployé cette application, exécutez la commande app get pour confirmer que l'application a le statut ready.

    ibmcloud ce app get -n kafka-sender-app

Vous avez créé l'application kafka-sender-app pour générer des messages Kafka pour les abonnements à des événements Code Engine et vous avez créé le secret kafka-subscription-secret qui contient les données d'identification requises.

Configuration d'un abonnement Code Engine Kafka

Pour que Code Engine fonctionne avec les événements Kafka, configurez un abonnement aux événements Code Engine Kafka afin de vous connecter aux courtiers d'événements Kafka et d'écouter les événements Kafka. Configurez également une application « Code Engine » qui servira de récepteur pour les événements « Kafka ». L'abonnement aux événements « Kafka » définit la relation entre le producteur (expéditeur) et le consommateur (destinataire) d'événements Kafka.

L'abonnement à l'événement « Code Engine » ( Kafka ) se connecte à votre courtier de messages Kafka et envoie des requêtes POST à l'adresse HTTP pour chaque message entrant provenant de Kafka à l'application réceptrice. Pour plus d'informations sur les données incluses dans les événements « Kafka », consultez la section « En-têtes et corps des messages » de HTTP concernant les événements transmis aux applications.

  1. Créez une application Code Engine pour agir en tant que consommateur d'événements des messages Kafka et recevoir les événements Kafka. Par exemple, créez une application appelée kafka-receiver-app qui utilise l'image icr.io/codeengine/kafka-receiver. Cette image est générée à partir de receiver.go, qui est disponible dans Exemples pour le référentiel IBM Cloud Code Engine GitHub. Cet exemple ne nécessite aucune variable d'environnement. Vous pouvez, si vous le souhaitez, spécifier l'option « --min-scale=1 » afin que l'application dispose toujours d'une instance en cours d'exécution et que son nombre d'instances ne tombe jamais à zéro. Le fait de configurer l'application afin de toujours avoir une instance en cours d'exécution est utile lorsque vous affichez les journaux. Si vous travaillez dans un environnement de production, prenez en compte le coût de la conservation d'une instance en cours d'exécution de votre application ou si vous souhaitez que Code Engine soit automatiquement réduit à zéro. Par défaut, l'application est mise à l'échelle à zéro lorsqu'elle n'est pas utilisée.

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

    Par défaut, les événements sont acheminés vers l'URL racine de l'application de destination. Vous pouvez envoyer des événements vers une autre destination dans l'application à l'aide de l'option --path. Par exemple, si votre abonnement indique --path /event, l'événement est envoyé à https://<base application URL>/events.

  2. Après avoir déployé cette application, exécutez la commande app get pour confirmer que l'application a le statut ready.

    ibmcloud ce app get -n kafka-receiver-app

  3. Créez un abonnement d'événement Code Engine Kafka pour vos événements Kafka à l'aide de la commande ibmcloud ce sub kafka create. Utilisez le secret kafka-subscription-secret que vous avez créé précédemment pour accéder au courtier de messages. Spécifiez les informations de courtier en fonction des informations de données d'identification du service pour votre ressource Kafka. Pour cet exemple, vous pouvez obtenir les informations de courtier à partir de la sortie de la commande ibmcloud resource service-key myeventstream-key. Notez que vous devez spécifier une option --broker pour chaque courtier de votre rubrique. L'option --destination spécifie la ressource Code Engine qui reçoit les événements.

    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. Afficher les détails de l'abonnement à l'événement « Kafka ».

    ibmcloud ce sub kafka get -n mykafkasubscription

    Exemple de sortie

    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

Test de votre abonnement

Maintenant que votre abonnement à l'événement « Kafka », qui fait référence à l'application « kafka-receiver-app », est créé, utilisez l'interface « kafka-sender-app » pour envoyer des événements de message à l'application réceptrice.

  1. Récupérez l' URL publique de l'application de destination, kafka-sender-app, à l'aide de la ibmcloud ce app getURL commande avec l'option « --output url » pour trouver l' de votre application.

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

    Exemple de sortie

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

  2. Exécutez l'application de fournisseur d'événements Kafka, kafka-sender-app pour envoyer des événements à l'application Code Engine de destination. Appelez l'application kafka-sender-app avec curl et spécifiez des valeurs pour la rubrique et le nombre de messages. Utilisez la sortie de la ibmcloud ce app get commande pour trouver l' URL publique de votre application. Veillez à encapsuler la valeur dans des guillemets pour vous assurer qu'elle est traitée comme une chaîne unique. Par exemple :

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

    Par exemple :

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

  3. Afficher les événements dans les journaux. Lorsque votre abonnement à des événements Kafka est créé avec un courtier, des rubriques et un secret d'accès valides, et que vous disposez d'une application Kafka qui génère des messages sur cette rubrique (par exemple, kafka-sender-app), vous pouvez afficher les événements dans les journaux de votre application Code Engine de destination qui reçoit des messages Kafka, tels que kafka-receiver-app. Lorsque vous utilisez l'application de récepteur Kafka (icr.io/codeengine/kafka-receiver), recherchez Event data dans les journaux de l'application de récepteur pour voir les messages reçus.

    ibmcloud ce app logs -n kafka-receiver-app

    Exemple de sortie

    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

    Notez que les informations de journalisation relatives aux applications ne sont conservées que pendant une heure. Pour plus d'informations sur l'affichage des journaux pour les applications (ou les travaux), voir Affichage des journaux.

Mise à jour de votre abonnement

Pour mettre à jour un abonnement à des événements à l'aide de l'interface de ligne de commande, utilisez la commande ibmcloud ce subscription kafka update. L'exemple suivant met à jour le nom de la rubrique.

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

Vous pouvez utiliser la ibmcloud ce subscription kafka update commande suivante pour mettre à jour les valeurs de l'abonnement « Kafka ». Toutefois, vous ne pouvez pas modifier la valeur du groupe de consommateurs à l'aide de cette commande. Si vous souhaitez mettre à jour l'abonnement pour qu'il fasse référence à un autre sujet, assurez-vous que le sujet « Kafka » existe bien avant de procéder à la mise à jour de l'abonnement.

Tutoriel sur l'abonnement à « Clean up for Kafka »

Prêt à supprimer votre abonnement Kafka, les applications d'envoi et de réception et le secret? Vous pouvez utiliser les commandes ibmcloud ce app delete, ibmcloud ce sub kafka delete et ibmcloud ce sub kafka delete. Vous pouvez, si vous le souhaitez, utiliser l'option « -f » pour forcer la suppression du composant sans confirmation.

Lorsque vous supprimez l'abonnement « Kafka », cette suppression n'entraîne pas la suppression de l'application à laquelle cet abonnement fait référence.

Pour retirer votre abonnement, entrez :

ibmcloud ce sub kafka delete --name mykafkasubscription -f

Pour supprimer votre application de réception de messages Kafka,

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

De même, vous pouvez supprimer le kafka-sender-app.

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

Pour supprimer le kafka-subscription-secret,

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

Vous êtes prêt à supprimer votre instance de service Event Streams ? L'option --recursive permet de supprimer toutes les ressources de l'instance de service, qui inclut la clé de service associée.

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

Etapes suivantes

Pour plus d'informations sur l'utilisation des abonnements aux événements Kafka, voir Utilisation du fournisseur d'événements Kafka.

Vous recherchez d'autres exemples de code ? Découvrez le site Exemples pour le dépôt « IBM Cloud Code Engine GitHub ».