12 Min. Lesezeit

Lernziele

Am Ende dieses Moduls werden Sie in der Lage sein:

  • Einen confluent-kafka-Producer und -Consumer mit Event Streams for Apache Kafka unter Verwendung von gegenseitigem TLS verbinden, wobei Sie die Anmeldeinformationen und Broker-Adressen aus Terraform nutzen
  • Einen idempotenten Producer mit `acks=all` und optimiertem Batching für die Task-Änderungsereignisse von TaskBoard konfigurieren
  • Eine Consumer-Gruppe mit manuellen Offset-Commits und At-Least-Once-Zustellung implementieren
  • Retry- und Dead-Letter-Topics erstellen, die Gift-Nachrichten isolieren, ohne eine Partition zu blockieren
  • Consumer auf Managed Kubernetes innerhalb der Obergrenze der Partitionsanzahl skalieren

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=all wartet, bis alle synchronen Replikate den Schreibvorgang haben, sodass bei einem einzelnen Broker-Ausfall nichts verloren geht.
  • enable.idempotence verhindert, dass Wiederholungen Duplikate erzeugen, und erhält die Reihenfolge pro Partition.
  • linger.ms und batch.size opfern 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-kafka und jsonschema

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-dlq mit 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:

  1. 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.
  2. 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.algorithm auf none setzen und ssl.ca.location auf die Cluster-CA verweisen lassen.
  3. 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=all und 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.id teilen 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: