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=allattend 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.idempotenceempêche les nouvelles tentatives de créer des doublons et préserve l'ordre par partition.linger.msetbatch.sizesacrifient 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-eventsde 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-kafkaetjsonschema
É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-dlqavec 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é :
-
É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.
-
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.algorithmsurnoneet maintenezssl.ca.locationpointant vers l'AC du cluster.
-
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=allet 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.idqui 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 :