Einheit 4.3: Event-Streaming-Integration
Einführung
Wenn ein Benutzer eine Aufgabe abschließt, sollte TaskBoard die Beobachter der Aufgabe benachrichtigen. Das Senden dieser Benachrichtigungen innerhalb des API-Anrufs macht den Anruf langsam und anfällig. Stattdessen veröffentlicht die API ein task.completed-Ereignis, und der Worker-Dienst konsumiert es und sendet die Benachrichtigungen in eigenem Tempo.
In Einheit 2.5 haben Sie einen Event Streams for Apache Kafka-Cluster und das task-events-Thema mit Terraform provisioniert. Jetzt schreiben Sie die Client-Seite. Sie konfigurieren gegenseitiges TLS (mTLS) mit den Zertifikaten des Clusters, schreiben einen zuverlässigen Producer, führen eine Consumer-Gruppe mit expliziten Offset-Commits aus und leiten fehlerhafte Nachrichten an Retry- und Dead-Letter-Themen weiter. Sie definieren auch den Event-Vertrag und skalieren den Worker auf Kubernetes. Im Code Lab produzieren und konsumieren Sie TaskBoard-Ereignisse von Anfang bis Ende.
1. Verbindung über mTLS
1.1 Zugangsdaten und Broker aus Terraform
Die Kommunikation mit dem Cluster ist TLS-gesichert, und beide Seiten authentifizieren sich gegenseitig über mTLS. Das Cluster verfügt nicht über öffentlich signierte Zertifikate, daher validiert Ihr Client den Server anhand der Zertifizierungsstelle (CA) des Clusters. Der Provider liest die CA, das Clientzertifikat und den Schlüssel für einen Benutzer:
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
}
Das berechnete Attribut broker_addresses enthält die IP-Adresse und den Port jedes Brokers, beispielsweise 10.10.2.2:9093. Die Anmeldeinformationen gehören zum Kafka-Administratorbenutzer und sind daher als Administrator-Geheimnisse zu behandeln. Die Datenquelle speichert sie im State; die ephemere Ressource ionoscloud_kafka_user_credentials liest dieselben Werte, ohne sie zu speichern.
Ohne Terraform stammen dieselben Werte aus der 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
Die Felder .metadata.certificate und .metadata.privateKey enthalten das Clientzertifikat und den Schlüssel. Rufen Sie die Benutzerkennung aus GET /clusters/{clusterId}/users ab.
1.2 Client-Konfiguration
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",
}
Die Client-Konfiguration für den Cluster verwendet security.protocol=SSL und ein leeres ssl.endpoint.identification.algorithm, wodurch der Hostname-Check deaktiviert wird, während die CA weiterhin die Zertifikatskette prüft. In librdkafka ist der Wert für „off" none. Die Broker befinden sich in Ihrem privaten DB-LAN, daher müssen die API und der Worker auf Servern oder Node-Pools ausgeführt werden, die an dieses LAN angeschlossen sind (Einheit 3.2).
Jedes Client-Zertifikat ist 365 Tage gültig. 30 Tage vor Ablauf ist ein erneuertes Zertifikat über die User-Credentials-API verfügbar. Lesen Sie die Credentials regelmäßig ein und starten Sie Ihre Pods neu, da die Clients andernfalls am Ablaufdatum keine Verbindung mehr herstellen.
2. Zuverlässige Erzeugung von Task-Events
2.1 Themen-Design
Verwenden Sie ein Thema pro Event-Familie und kennzeichnen Sie jede Nachricht anhand der Entität, deren Reihenfolge relevant ist. TaskBoard kennzeichnet task-events anhand der Task-ID, sodass alle Events einer einzelnen Task in einer Partition landen, in der richtigen Reihenfolge. Das Thema aus Einheit 2.5 verfügt über 6 Partitionen und einen Replikationsfaktor von 3.
Erstellen Sie das Retry- und das Dead-Letter-Topic auf dieselbe Weise:
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
}
Jeder Cluster verfügt über drei Broker, daher sollten Partitionszahlen verwendet werden, die Vielfache von 3 sind, um eine gleichmäßige Verteilung zu gewährleisten. Ohne retention_time speichert ein Topic Nachrichten für 604800000 ms (7 Tage); -1 hebt das Zeitlimit auf.
2.2 Der Producer
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=allwartet, bis alle synchronen Replikate den Schreibvorgang haben, sodass bei einem einzelnen Broker-Ausfall nichts verloren geht.enable.idempotenceverhindert, dass Wiederholungen Duplikate erzeugen, und erhält die Reihenfolge pro Partition.linger.msundbatch.sizeopfern einige Millisekunden Latenz für weniger, größere Anfragen.
Rufen Sie producer.flush(10) beim Herunterfahren auf, beispielsweise in Ihrem FastAPI-Lifespan-Handler, andernfalls geht das letzte Batch verloren, wenn Kubernetes den Pod stoppt.
3. Konsumierung mit Offset-Steuerung
3.1 Consumer Group und Commits
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()
Alle Worker-Pods teilen sich das group.id, daher verteilt Kafka die Partitionen unter ihnen. Wenn enable.auto.commit deaktiviert ist, meldet der Worker einen Offset erst, nachdem er die Nachricht verarbeitet hat.
3.2 Liefersemantik
| Commit-Punkt | Lieferung | Auswirkung bei einem Fehler |
|---|---|---|
| Nach der Verarbeitung (dieser Code) | At-least-once | Ein Absturz zwischen Verarbeitung und Commit führt dazu, dass die Nachricht erneut zugestellt wird |
| Vor der Verarbeitung | At-most-once | Ein Absturz nach dem Commit führt zum Verlust der Nachricht |
Wie die Tabelle zeigt, kann At-least-once eine Nachricht zweimal zustellen. Daher muss der Handler idempotent sein. Der Notifier erfasst jede event_id in PostgreSQL mit einer eindeutigen Einschränkung und überspringt Ereignisse, die er bereits gesendet hat.
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. Wiederholte Versuche, Dead-Letters und Event-Verträge
4.1 Routing für Wiederholte Versuche und Dead-Letters
Eine Nachricht, die immer fehlschlägt, eine Gift-Nachricht, darf ihre Partition nicht blockieren. Der Worker wiederholt die Verarbeitung einige Male über das Retry-Topic und parkt die Nachricht anschließend im Dead-Letter-Topic:
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)
Der ursprüngliche Offset wird erst nach der sicheren Ablage der Nachricht im nächsten Topic bestätigt, sodass die Partition weiterarbeitet. Ungültiges JSON oder ein fehlgeschlagener Schema-Check wird sofort in das Dead-Letter-Topic geleitet, da ein erneuter Versuch das Problem nicht beheben kann. Ein kleines Tool kann das Dead-Letter-Topic lesen, die Ursache beheben und die Nachrichten erneut in task-events einspeisen.
4.2 Schema-Verwaltung
Kafka speichert Bytes; der Vertrag zwischen API und Worker ist Ihre Verantwortung. Definieren Sie ihn als JSON Schema in einem gemeinsamen Paket und validieren Sie auf beiden Seiten:
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)
Evolvieren Sie das Schema additiv: Fügen Sie optionale Felder hinzu, benennen Sie niemals ein Feld um oder entfernen Sie es. Bei einer brechenden Änderung erhöhen Sie schema_version und lassen Sie den Consumer beide Versionen lesen, bis kein alter Producer mehr vorhanden ist. Avro mit einem Schema-Registry bietet dieselbe Disziplin mit Compilerunterstützung.
5. Skalierung von Consumern auf Kubernetes
Die Anzahl der Partitionen ist die Obergrenze für den Parallelismus einer Consumer-Gruppe: Jede Partition wird von höchstens einem Consumer innerhalb der Gruppe gelesen. Bei 6 Partitionen bleibt ein siebter Worker-Pod ungenutzt.
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
Wenn ein Pod startet oder gestoppt wird, erfolgt ein Rebalancing der Gruppe, und Partitionen werden zwischen den Pods verschoben. Behandeln Sie SIGTERM, indem Sie die Poll-Schleife verlassen und consumer.close() aufrufen, damit die Gruppe sofort neu balanciert wird, anstatt auf ein Session-Timeout zu warten. Halten Sie die Verarbeitungsdauer jeder Nachricht deutlich unter max.poll.interval.ms, da der Broker den Consumer andernfalls aus der Gruppe entfernt. Um die Obergrenze zu erhöhen, fügen Sie Partitionen in Vielfachen von 3 hinzu; beachten Sie, dass sich dadurch die Zuordnung einer Key zu einer Partition ändert.
API-Referenz Schnellkarte
Wichtige Kafka-API-Endpunkte für diese Einheit:
| Methode | Endpunkt | Beschreibung |
|---|---|---|
GET |
/clusters/{clusterId} |
Clusterzustand und brokerAddresses lesen |
GET |
/clusters/{clusterId}/users |
Benutzer und deren IDs auflisten |
GET |
/clusters/{clusterId}/users/{userId}/access |
CA, Clientzertifikat und privaten Schlüssel abrufen |
POST |
/clusters/{clusterId}/topics |
Thema erstellen |
DELETE |
/clusters/{clusterId}/topics/{topicId} |
Thema und dessen Daten löschen |
Basis-URL: regional, beispielsweise https://kafka.de-txl.ionos.com
Authentifizierung: Authorization: Bearer <token> für die API; mTLS für Producer und Consumer
Code-Labor
Ziel: Erzeugen und Verarbeiten von TaskBoard-Aufgabenänderungsereignissen in Event Streams for Apache Kafka mit einer Consumer Group, manuellen Offset-Commits und einem Dead-Letter-Topic.
Voraussetzungen:
- Der Kafka-Cluster und das
task-events-Topic aus Einheit 2.5, sowie die Retry- und Dead-Letter-Topics aus Abschnitt 2.1 - Die Ausgaben aus Abschnitt 1.1, angewendet
- Eine VM oder ein Pod im LAN des Clusters mit Python 3.12,
confluent-kafkaundjsonschema
Schritt 1: Zertifikate schreiben
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
Erwartete Ausgabe:
notAfter=<date about one year from issue>
Schritt 2: Die Themen auflisten
from confluent_kafka.admin import AdminClient
print(sorted(AdminClient(KAFKA_TLS).list_topics(timeout=10).topics))
Erwartete Ausgabe:
['task-events', 'task-events-dlq', 'task-events-retry', ...]
Schritt 3: Drei Ereignisse erzeugen
for tid in (1, 2, 3):
publish_task_event(tid, "task.completed", {"title": f"Task {tid}"})
print("unflushed:", producer.flush(10))
Erwartete Ausgabe:
unflushed: 0
Schritt 4: Erzeugen einer Gift-Nachricht
producer.produce("task-events", key="99", value=b"not json"); producer.flush(10)
Erwartete Ausgabe:
(no output)
Schritt 5: Verbraucher ausführen
Führen Sie die Schleife aus Abschnitt 3.1 mit send_notifications = lambda e: print("notify", e["task_id"]) aus und stoppen Sie sie nach einigen Sekunden.
Erwartete Ausgabe:
notify 1
notify 2
notify 3
Schritt 6: Das Dead-Letter-Topic untersuchen
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()))
Erwartete Ausgabe:
b'not json' {'attempt': b'1', 'error': b'JSONDecodeError', 'source': b'task-events/...'}
Schritt 7: Die festgelegten Offsets überprüfen
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)])
Erwartete Ausgabe:
[<offset or -1001 per partition>, ...]
Führen Sie dies mit einem neuen Consumer in der Gruppe taskboard-notifier aus; Partitionen, die Ereignisse erhalten haben, weisen einen committen Offset auf.
Prüfliste:
- [ ] Der Client verbindet sich mit mTLS unter Verwendung der Cluster-CA
- [ ] Jedes gültige Ereignis wird genau einmal gemeldet, auch nach einem Neustart des Consumers
- [ ] Die Gift-Nachricht endet in
task-events-dlqmit ihrer Versuchszahl und ihrer Quelle - [ ] Offsets werden nur nach der Verarbeitung commitet
Bereinigung:
rm -f /etc/kafka/client-key.pem
terraform destroy -auto-approve -target=ionoscloud_kafka_cluster_topic.task_events_dlq
Häufige Fehler
Fehler von Entwicklerinnen und Entwicklern, die bei dem Thema dieser Einheit zu vermeiden sind:
-
Handshake-Fehler nach einem Jahr
- Problem: Produzenten und Konsumenten scheitern plötzlich mit SSL-Handshake-Fehlern, obwohl sich nichts geändert hat.
- Ursache: Client-Zertifikate sind 365 Tage gültig, und die Pods mounten weiterhin das alte Zertifikat.
- Lösung: Das erneuerte Zertifikat abrufen, das 30 Tage vor Ablauf verfügbar ist, das Kubernetes-Secret aktualisieren und die Deployments neu starten.
-
Hostname-Prüfung gegen IP-Adressen
- Problem: Der Client kann keine Verbindung herstellen und protokolliert einen Zertifikatsprühfehler für den Broker.
- Ursache: Neuere librdkafka-Versionen prüfen standardmäßig den Hostnamen des Brokers, während die dokumentierte Client-Konfiguration für den Cluster diese Prüfung deaktiviert.
- Lösung:
ssl.endpoint.identification.algorithmaufnonesetzen undssl.ca.locationauf die Cluster-CA verweisen lassen.
-
Mehr Konsumenten, keine höhere Durchsatzrate
- Problem: Sie skalieren den Worker auf 10 Replikate hoch, und der Rückstau sinkt nicht.
- Ursache: Nur so viele Konsumenten wie Partitionen erhalten Arbeit; die übrigen bleiben untätig.
- Lösung: Die Anzahl der Replikate auf oder unter der Partitionszahl halten oder Partitionen in Vielfachen von 3 hinzufügen.
Zusammenfassung
Sie können die Dienste von TaskBoard nun in produktionsreifer Qualität mit Event Streams for Apache Kafka verbinden. Clients authentifizieren sich mit mTLS, wobei die von Terraform oder der API bereitgestellten CA, das Zertifikat und der Schlüssel verwendet werden, und die Broker werden im privaten LAN erreicht. Die API erzeugt ereignisbasierte, schemavalidierte Events mit einem idempotenten acks=all-Producer. Der Worker commitet die Offsets nach der Verarbeitung, dedupliziert anhand der Event-ID und leitet fehlerhafte Nachrichten über ein Retry-Topic in ein Dead-Letter-Topic.
Wichtige Punkte:
- Authentifizierung mit mTLS; Validierung des Servers mit der Cluster-CA und Deaktivierung der Hostnamenprüfung
- Client-Zertifikate haben eine Gültigkeitsdauer von 365 Tagen; deren Erneuerung sollte automatisiert werden
- Verwendung von
acks=allund Idempotenz für Producer; Commit der Offsets nach der Verarbeitung für At-Least-Once-Semantik - Weiterleitung von Fehlern an Retry- und Dead-Letter-Topics, damit eine fehlerhafte Nachricht nie eine Partition blockiert
- Die Anzahl der Partitionen begrenzt die Parallelität der Consumer; verwenden Sie Vielfache von 3 für die drei Broker
Wichtige Begriffe:
- mTLS: Gegenseitiges TLS, bei dem sowohl Client als auch Broker Zertifikate vorlegen, die von der jeweils anderen Seite verifiziert werden
- Consumer group: Consumer, die eine
group.idteilen und die Partitionen eines Themas unter sich aufteilen - Offset commit: Die gespeicherte Position in einer Partition, von der eine Gruppe nach einem Neustart fortsetzt
- Dead-letter topic: Ein Topic, das Nachrichten enthält, die alle Wiederholungen nicht bestanden haben, zur späteren Untersuchung
- Idempotent producer: Ein Producer, dessen Wiederholungen niemals Duplikate schreiben und die Partitionenreihenfolge beibehalten
Nächste Schritte
Weiter lernen: Einheit 4.4: AI Model Hub Integration
Verwandte Themen: