15 min de lecture

Objectifs d'apprentissage

À la fin de ce module, vous serez en mesure de:

  • Connecter un producteur et un consommateur confluent-kafka à Event Streams for Apache Kafka avec TLS mutuel, en utilisant les identifiants et les adresses des courtiers issues de Terraform
  • Configurer un producteur idempotent avec `acks=all` et un lotage optimisé pour les événements de modification de tâches de TaskBoard
  • Mettre en œuvre un groupe de consommateurs avec des engagements manuels des décalages et une livraison au moins une fois
  • Créer des sujets de réessai et de lettre morte qui isolent les messages toxiques sans bloquer une partition
  • Ajuster la taille des consommateurs sur Managed Kubernetes dans la limite du nombre de partitions

Unité 4.3 : Intégration du flux d'événements

Introduction

Lorsqu'un utilisateur termine une tâche, TaskBoard doit notifier les observateurs de la tâche. L'envoi de ces notifications à l'intérieur de la requête API rend la requête lente et fragile. À la place, l'API publie un événement task.completed, et le service worker le consomme et envoie les notifications à son propre rythme.

Dans l'unité 2.5, vous avez provisionné un cluster Event Streams for Apache Kafka et le sujet task-events avec Terraform. Vous rédigez maintenant le côté client. Vous configurez le TLS mutuel (mTLS) avec les certificats du cluster, écrivez un producteur fiable, exécutez un groupe de consommateurs avec des engagements explicites de décalages, et acheminez les messages en échec vers des sujets de nouvelle tentative et de lettre morte. Vous définissez également le contrat d'événement et mettez à l'échelle le worker sur Kubernetes. Dans le Code Lab, vous produisez et consommez les événements TaskBoard de bout en bout.

1. Connexion avec mTLS

1.1 Identifiants et courtiers à partir de Terraform

La communication avec le cluster est sécurisée par TLS, et les deux parties s'authentifient mutuellement via mTLS. Le cluster ne dispose pas de certificats signés publiquement, votre client valide donc le serveur à l'aide de l'autorité de certification (CA) du cluster. Le fournisseur lit la CA, le certificat client et la clé pour un utilisateur :

data "ionoscloud_kafka_users" "events" {
  cluster_id = ionoscloud_kafka_cluster.events.id
  location   = ionoscloud_kafka_cluster.events.location
}

data "ionoscloud_kafka_user_credentials" "admin" {
  cluster_id = ionoscloud_kafka_cluster.events.id
  location   = ionoscloud_kafka_cluster.events.location
  username   = "admin"
}

output "kafka_bootstrap" {
  value = join(",", ionoscloud_kafka_cluster.events.broker_addresses)
}

output "kafka_ca"   {
  value = data.ionoscloud_kafka_user_credentials.admin.certificate_authority
  sensitive = true
}
output "kafka_cert" {
  value = data.ionoscloud_kafka_user_credentials.admin.certificate
  sensitive = true
}
output "kafka_key"  {
  value = data.ionoscloud_kafka_user_credentials.admin.private_key
  sensitive = true
}

L'attribut calculé broker_addresses contient l'adresse IP et le port de chaque broker, par exemple 10.10.2.2:9093. Les identifiants appartiennent à l'utilisateur administrateur Kafka, il convient donc de les traiter comme des secrets d'administrateur. La source de données les stocke dans l'état ; la ressource éphémère ionoscloud_kafka_user_credentials lit les mêmes valeurs sans les stocker.

Sans Terraform, les mêmes valeurs proviennent de l'API :

curl -s https://kafka.de-txl.ionos.com/clusters/$CLUSTER_ID/users/$USER_ID/access \
  -H "Authorization: Bearer $IONOS_TOKEN" \
  | jq -r '.metadata.certificateAuthority' > ca-cert.pem

Les champs .metadata.certificate et .metadata.privateKey contiennent le certificat et la clé du client. Obtenez l'identifiant utilisateur à partir de GET /clusters/{clusterId}/users.

1.2 Configuration du client

import os
from confluent_kafka import Producer

KAFKA_TLS = {
    "bootstrap.servers": os.environ["KAFKA_BOOTSTRAP"],
    "security.protocol": "SSL",
    "ssl.ca.location": "/etc/kafka/ca-cert.pem",
    "ssl.certificate.location": "/etc/kafka/client-cert.pem",
    "ssl.key.location": "/etc/kafka/client-key.pem",
    "ssl.endpoint.identification.algorithm": "none",
}

La configuration du client pour le cluster utilise security.protocol=SSL et un ssl.endpoint.identification.algorithm vide, ce qui désactive la vérification du nom d'hôte, tandis que l'autorité de certification (CA) vérifie toujours la chaîne de certificats. Dans librdkafka, la valeur pour « off » est none. Les brokers sont situés dans votre LAN privée de base de données, de sorte que l'API et les workers doivent s'exécuter sur des serveurs ou des pools de nœuds attachés à cette LAN (Unité 3.2).

Chaque certificat client est valide pendant 365 jours. Trente jours avant son expiration, un certificat renouvelé est disponible via l'API des identifiants utilisateur. Relisez les identifiants selon un calendrier défini et effectuez le remplacement de vos pods, sinon les clients cessent de se connecter à la date d'expiration.

2. Production fiable des événements de tâche

2.1 Conception du sujet

Utilisez un sujet par famille d'événements et identifiez chaque message par l'entité dont l'ordre est important. TaskBoard identifie task-events par identifiant de tâche, de sorte que tous les événements d'une même tâche aboutissent dans une seule partition, dans l'ordre. Le sujet de l'unité 2.5 comporte 6 partitions et un facteur de réplication de 3.

Créez les sujets de nouvelle tentative et de lettre morte de la même manière :

resource "ionoscloud_kafka_cluster_topic" "task_events_retry" {
  cluster_id           = ionoscloud_kafka_cluster.events.id
  location             = ionoscloud_kafka_cluster.events.location
  name                 = "task-events-retry"
  replication_factor   = 3
  number_of_partitions = 6
}

resource "ionoscloud_kafka_cluster_topic" "task_events_dlq" {
  cluster_id           = ionoscloud_kafka_cluster.events.id
  location             = ionoscloud_kafka_cluster.events.location
  name                 = "task-events-dlq"
  replication_factor   = 3
  number_of_partitions = 3
  retention_time       = 2592000000   # 30 days to investigate failures
}

Chaque cluster comporte trois brokers ; utilisez donc des nombres de partitions qui sont des multiples de 3 pour obtenir une répartition uniforme. Sans retention_time, un sujet conserve les messages pendant 604800000 ms (7 jours) ; -1 supprime la limite de temps.

2.2 Le producteur

import json, uuid, datetime

producer = Producer({
    **KAFKA_TLS,
    "acks": "all",
    "enable.idempotence": True,
    "linger.ms": 20,
    "batch.size": 65536,
    "compression.type": "lz4",
})

def publish_task_event(task_id: int, event_type: str, data: dict) -> None:
    event = {
        "event_id": str(uuid.uuid4()),
        "type": event_type,                 # "task.completed"
        "schema_version": 1,
        "occurred_at": datetime.datetime.now(datetime.UTC).isoformat(),
        "task_id": task_id,
        "data": data,
    }
    producer.produce("task-events", key=str(task_id), value=json.dumps(event),
                     on_delivery=_report)
    producer.poll(0)

def _report(err, msg):
    if err is not None:
        log.error("delivery failed: %s", err)   # alert; the event is not stored
  • acks=all attend que toutes les répliques synchronisées disposent de l'écriture, de sorte qu'une défaillance d'un seul courtier ne provoque aucune perte.
  • enable.idempotence empêche les nouvelles tentatives de créer des doublons et préserve l'ordre par partition.
  • linger.ms et batch.size sacrifient quelques millisecondes de latence au profit de requêtes moins nombreuses mais plus volumineuses.

Appelez producer.flush(10) lors de l'arrêt, par exemple dans votre gestionnaire de durée de vie FastAPI, sinon le dernier lot est perdu lorsque Kubernetes arrête le pod.

3. Consommation avec contrôle des décalages

3.1 Groupe de consommateurs et confirmations

from confluent_kafka import Consumer, KafkaException

consumer = Consumer({
    **KAFKA_TLS,
    "group.id": "taskboard-notifier",
    "enable.auto.commit": False,
    "auto.offset.reset": "earliest",
    "max.poll.interval.ms": 300000,
})
consumer.subscribe(["task-events", "task-events-retry"])

while running:
    msg = consumer.poll(1.0)
    if msg is None:
        continue
    if msg.error():
        raise KafkaException(msg.error())
    handle_with_retry(msg)                       # Section 4
    consumer.commit(message=msg, asynchronous=False)
consumer.close()

Tous les pods de travail partagent le group.id, de sorte que Kafka répartit les partitions entre eux. Lorsque enable.auto.commit est désactivé, le pod de travail n'engage un décalage qu'après avoir traité le message.

3.2 Sémantique de livraison

Point d'engagement Livraison Effet en cas d'échec
Après le traitement (ce code) Au moins une fois Un plantage entre le traitement et l'engagement rejoue le message
Avant le traitement Au plus une fois Un plantage après l'engagement entraîne la perte du message

Comme le montre le tableau, la livraison au moins une fois peut livrer un message deux fois, il faut donc que le gestionnaire soit idempotent. Le notificateur enregistre chaque event_id dans PostgreSQL avec une contrainte d'unicité et ignore les événements qu'il a déjà envoyés.

def already_sent(event_id: str) -> bool:
    with engine.begin() as c:
        r = c.execute(text("insert into sent_events (event_id) values (:e) on conflict do nothing"),
                      {"e": event_id})
        return r.rowcount == 0

4. Nouvelles tentatives, lettres mortes et contrats d'événements

4.1 Routage des nouvelles tentatives et des lettres mortes

Un message qui échoue systématiquement, un message toxique, ne doit pas bloquer sa partition. Le travailleur effectue quelques nouvelles tentatives via le sujet de nouvelles tentatives, puis place le message dans le sujet de lettres mortes :

from confluent_kafka import Message
from jsonschema import ValidationError

MAX_ATTEMPTS = 3

def handle_with_retry(msg: Message) -> None:
    headers = dict(msg.headers() or [])
    attempt = int(headers.get("attempt", b"0"))
    try:
        event = json.loads(msg.value())
        validate_event(event)                     # Section 4.2
        if not already_sent(event["event_id"]):
            send_notifications(event)
    except (json.JSONDecodeError, ValidationError) as exc:
        forward(msg, "task-events-dlq", attempt, exc)   # a retry cannot fix bad data
    except Exception as exc:
        target = "task-events-retry" if attempt + 1 < MAX_ATTEMPTS else "task-events-dlq"
        forward(msg, target, attempt, exc)

def forward(msg: Message, target: str, attempt: int, exc: Exception) -> None:
    producer.produce(target, key=msg.key(), value=msg.value(), headers={
        "attempt": str(attempt + 1),
        "error": type(exc).__name__,
        "source": f"{msg.topic()}/{msg.partition()}/{msg.offset()}",
    })
    producer.flush(5)

Le décalage d'origine est validé après que le message est en sécurité dans le sujet suivant, de sorte que la partition passe à la suite. Un JSON invalide ou un échec de la vérification du schéma est envoyé immédiatement au sujet des messages en échec, car une nouvelle tentative ne peut pas le corriger. Un petit outil peut lire le sujet des messages en échec, corriger la cause et produire à nouveau les messages vers task-events.

4.2 Gestion des schémas

Kafka stocke des octets ; le contrat entre l'API et le travailleur est de votre responsabilité. Définissez-le en tant que schéma JSON dans un package partagé et validez-le des deux côtés :

from jsonschema import validate

TASK_EVENT_V1 = {
    "type": "object",
    "required": ["event_id", "type", "schema_version", "task_id", "occurred_at"],
    "properties": {
        "event_id": {"type": "string"},
        "type": {"enum": ["task.created", "task.updated", "task.completed"]},
        "schema_version": {"const": 1},
        "task_id": {"type": "integer"},
    },
}

def validate_event(event: dict) -> None:
    validate(instance=event, schema=TASK_EVENT_V1)

Évoluez le schéma de manière additive : ajoutez des champs facultatifs, ne renommez jamais un champ et n'en supprimez jamais. Pour une modification cassante, augmentez schema_version et maintenez la lecture des deux versions par le consommateur jusqu'à ce qu'aucun producteur ancien ne subsiste. Avro avec un registre de schémas offre la même discipline avec un support de compilateur.

5. Mise à l'échelle des consommateurs sur Kubernetes

Le nombre de partitions constitue la limite de parallélisme d'un groupe de consommateurs : chaque partition est lue par au plus un consommateur au sein du groupe. Avec 6 partitions, un septième pod de travailleur reste inactif.

apiVersion: apps/v1
kind: Deployment
metadata: { name: taskboard-worker }
spec:
  replicas: 3                  # at most 6, the partition count of task-events
  template:
    spec:
      terminationGracePeriodSeconds: 45
      containers:
        - name: worker
          image: <registry-hostname>/taskboard/worker:<git-sha>
          envFrom:
            - secretRef: { name: taskboard-kafka }   # KAFKA_BOOTSTRAP
          volumeMounts:
            - { name: kafka-tls, mountPath: /etc/kafka, readOnly: true }
      volumes:
        - name: kafka-tls
          secret: { secretName: taskboard-kafka-tls }  # ca-cert.pem, client-cert.pem, client-key.pem

Lorsqu'un pod démarre ou s'arrête, le groupe est rééquilibré et les partitions se déplacent entre les pods. Gérez SIGTERM en quittant la boucle de sondage et en appelant consumer.close(), afin que le groupe soit rééquilibré immédiatement au lieu d'attendre l'expiration de la session. Assurez-vous que le traitement de chaque message reste bien inférieur à max.poll.interval.ms, sinon le broker retire le consommateur du groupe. Pour augmenter cette limite, ajoutez des partitions par multiples de 3 ; notez que cela modifie la partition à laquelle une clé est associée.

Fiche de référence rapide de l'API

Points de terminaison des API Kafka clés pour cette unité :

Méthode Point de terminaison Description
GET /clusters/{clusterId} Lire l'état du cluster et brokerAddresses
GET /clusters/{clusterId}/users Lister les utilisateurs et leurs identifiants
GET /clusters/{clusterId}/users/{userId}/access Récupérer l'autorité de certification, le certificat client et la clé privée
POST /clusters/{clusterId}/topics Créer un sujet
DELETE /clusters/{clusterId}/topics/{topicId} Supprimer un sujet et ses données

URL de base : régionale, par exemple https://kafka.de-txl.ionos.com Authentification : Authorization: Bearer <token> pour l'API ; mTLS pour les producteurs et les consommateurs

Atelier de code

Objectif : Produire et consommer des événements de modification de tâches TaskBoard sur Event Streams for Apache Kafka à l'aide d'un groupe de consommateurs, d'engagements manuels des décalages et d'un sujet de lettres mortes.

Prérequis :

  • Le cluster Kafka et le sujet task-events de l'Unité 2.5, ainsi que les sujets de nouvelle tentative et de lettres mortes de la Section 2.1
  • Les résultats de la Section 1.1, appliqués
  • Une VM ou un pod dans le LAN du cluster, avec Python 3.12, confluent-kafka et jsonschema

Étape 1 : Écrire les certificats

mkdir -p /etc/kafka && cd /etc/kafka
terraform -chdir=$TF_DIR output -raw kafka_ca   > ca-cert.pem
terraform -chdir=$TF_DIR output -raw kafka_cert > client-cert.pem
terraform -chdir=$TF_DIR output -raw kafka_key  > client-key.pem && chmod 600 client-key.pem
export KAFKA_BOOTSTRAP=$(terraform -chdir=$TF_DIR output -raw kafka_bootstrap)
openssl x509 -in client-cert.pem -noout -enddate

Sortie attendue :

notAfter=<date about one year from issue>

Étape 2 : Lister les sujets

from confluent_kafka.admin import AdminClient
print(sorted(AdminClient(KAFKA_TLS).list_topics(timeout=10).topics))

Sortie attendue :

['task-events', 'task-events-dlq', 'task-events-retry', ...]

Étape 3 : Produire trois événements

for tid in (1, 2, 3):
    publish_task_event(tid, "task.completed", {"title": f"Task {tid}"})
print("unflushed:", producer.flush(10))

Sortie attendue :

unflushed: 0

Étape 4 : Produire un message empoisonné

producer.produce("task-events", key="99", value=b"not json"); producer.flush(10)

Sortie attendue :

(no output)

Étape 5 : Exécuter le consommateur

Exécutez la boucle de la section 3.1 avec send_notifications = lambda e: print("notify", e["task_id"]) et arrêtez-la après quelques secondes. Sortie attendue :

notify 1
notify 2
notify 3

Étape 6 : Inspecter le sujet de messages en échec

dlq = Consumer({**KAFKA_TLS, "group.id": "lab-dlq-reader", "auto.offset.reset": "earliest"})
dlq.subscribe(["task-events-dlq"]); m = dlq.poll(10)
print(m.value(), dict(m.headers()))

Sortie attendue :

b'not json' {'attempt': b'1', 'error': b'JSONDecodeError', 'source': b'task-events/...'}

Étape 7 : Vérifier les décalages confirmés

from confluent_kafka import TopicPartition
parts = [TopicPartition("task-events", p) for p in range(6)]
print([tp.offset for tp in consumer.committed(parts, timeout=10)])

Sortie attendue :

[<offset or -1001 per partition>, ...]

Exécutez cette commande avec un nouveau consommateur dans le groupe taskboard-notifier ; les partitions qui ont reçu des événements affichent un décalage confirmé.

Liste de vérification :

  • [ ] Le client se connecte avec mTLS en utilisant l'AC du cluster
  • [ ] Chaque événement valide est signalé une seule fois, même après un redémarrage du consommateur
  • [ ] Le message toxique aboutit dans task-events-dlq avec son nombre de tentatives et sa source
  • [ ] Les décalages ne sont confirmés qu'après le traitement

Nettoyage :

rm -f /etc/kafka/client-key.pem
terraform destroy -auto-approve -target=ionoscloud_kafka_cluster_topic.task_events_dlq

Erreurs courantes

Erreurs de développement à éviter concernant le sujet de cette unité :

  1. Échecs de poignée de main après un an

    • Problème : Les producteurs et les consommateurs échouent soudainement avec des erreurs de poignée de main SSL, bien que rien n'ait changé.
    • Pourquoi cela se produit : Les certificats client sont valides pendant 365 jours, et les pods montent encore l'ancien certificat.
    • Correction : Récupérez le certificat renouvelé, disponible 30 jours avant son expiration, mettez à jour le Secret Kubernetes et relancez les Deployments.
  2. Vérification du nom d'hôte par rapport aux adresses IP

    • Problème : Le client ne peut pas se connecter et consigne une erreur d'échec de vérification du certificat pour le broker.
    • Pourquoi cela se produit : Les versions récentes de librdkafka vérifient le nom d'hôte du broker par défaut, tandis que la configuration client documentée pour le cluster désactive cette vérification.
    • Correction : Définissez ssl.endpoint.identification.algorithm sur none et maintenez ssl.ca.location pointant vers l'AC du cluster.
  3. Plus de consommateurs, pas plus de débit

    • Problème : Vous passez le worker à 10 répliques, et le retard ne diminue pas.
    • Pourquoi cela se produit : Seuls autant de consommateurs que de partitions reçoivent du travail ; les autres restent inactifs.
    • Correction : Maintenez le nombre de répliques inférieur ou égal au nombre de partitions, ou ajoutez des partitions par multiples de 3.

Résumé

Vous pouvez désormais connecter les services de TaskBoard à Event Streams for Apache Kafka avec une qualité de production. Les clients s'authentifient via mTLS en utilisant le CA, le certificat et la clé fournis par Terraform ou l'API, et les brokers sont atteints dans le LAN privé. L'API génère des événements avec clé et validés par schéma à l'aide d'un producteur idempotent acks=all. Le travailleur confirme les décalages après traitement, déduplique par identifiant d'événement et transfère les messages toxiques via un sujet de réessai vers un sujet de messages morts.

Points clés :

  • S'authentifier avec mTLS ; valider le serveur avec le CA du cluster et désactiver les vérifications de nom d'hôte
  • Les certificats clients ont une durée de validité de 365 jours ; automatiser leur renouvellement
  • Utiliser acks=all et l'idempotence pour les producteurs ; confirmer les décalages après traitement pour un traitement au moins une fois
  • Aiguiller les échecs vers les sujets de réessai et de messages morts afin qu'un seul message défectueux ne bloque jamais une partition
  • Le nombre de partitions limite la parallélisation des consommateurs ; utiliser des multiples de 3 pour les trois brokers

Terminologie importante :

  • mTLS : TLS mutuel, où le client et le broker présentent tous deux des certificats vérifiés par l'autre partie
  • Groupe de consommateurs : Consommateurs partageant un group.id qui se répartissent les partitions d'un sujet entre eux
  • Confirmation de décalage : La position stockée dans une partition à partir de laquelle un groupe reprend après un redémarrage
  • Sujet de messages morts : Un sujet qui contient les messages ayant échoué à tous les réessais, pour inspection ultérieure
  • Producteur idempotent : Un producteur dont les réessais n'écrivent jamais de doublon et qui préserve l'ordre des partitions

Prochaines étapes

Continuer l'apprentissage : Unité 4.4 : Intégration d'AI Model Hub

Sujets connexes :