Unidad 4.3: Integración de streaming de eventos
Introducción
Cuando un usuario completa una tarea, TaskBoard debe notificar a los observadores de la tarea. Enviar esas notificaciones dentro de la solicitud de la API hace que la solicitud sea lenta y frágil. En su lugar, la API publica un evento task.completed, y el servicio de trabajadores lo consume y envía las notificaciones a su propio ritmo.
En la Unidad 2.5, aprovisionó un clúster de Event Streams for Apache Kafka y el tema task-events con Terraform. Ahora escribe el lado del cliente. Configura TLS mutuo (mTLS) con los certificados del clúster, escribe un productor confiable, ejecuta un grupo de consumidores con confirmaciones explícitas de desplazamientos y enruta los mensajes con errores a temas de reintentos y de mensajes no procesables. También define el contrato del evento y escala el servicio de trabajadores en Kubernetes. En el Code Lab, produce y consume eventos de TaskBoard de extremo a extremo.
1. Conexión con mTLS
1.1 Credenciales y brokers desde Terraform
La comunicación con el clúster está protegida mediante TLS, y ambos lados se autentican mutuamente a través de mTLS. El clúster no cuenta con certificados firmados públicamente, por lo que su cliente valida al servidor mediante la autoridad de certificación (CA) del clúster. El proveedor lee la CA, el certificado del cliente y la clave para un usuario:
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
}
El atributo calculado broker_addresses contiene la dirección IP y el puerto de cada broker, por ejemplo 10.10.2.2:9093. Las credenciales pertenecen al usuario administrador de Kafka, por lo que debe tratarlas como secretos de administrador. La fuente de datos las almacena en el estado; el recurso efímero ionoscloud_kafka_user_credentials lee los mismos valores sin almacenarlos.
Sin Terraform, los mismos valores provienen de la 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
Los campos .metadata.certificate y .metadata.privateKey contienen el certificado y la clave del cliente. Obtenga el identificador de usuario desde GET /clusters/{clusterId}/users.
1.2 Configuración del cliente
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 configuración del cliente para el clúster utiliza security.protocol=SSL y un ssl.endpoint.identification.algorithm vacío, lo que desactiva la verificación del nombre del host mientras la CA sigue verificando la cadena de certificados. En librdkafka, el valor para "off" es none. Los brokers se encuentran en su LAN privada de bases de datos, por lo que la API y el worker deben ejecutarse en servidores o grupos de nodos conectados a esa LAN (Unidad 3.2).
Cada certificado de cliente es válido durante 365 días. Treinta días antes de su vencimiento, un certificado renovado está disponible a través de la API de credenciales de usuario. Lea las credenciales según un horario programado y recicle sus pods, o los clientes dejarán de conectarse en la fecha de vencimiento.
2. Producción de eventos de tarea de forma fiable
2.1 Diseño del tema
Utilice un tema por familia de eventos y asigne una clave a cada mensaje según la entidad cuyo orden sea importante. TaskBoard asigna la clave task-events por ID de tarea, por lo que todos los eventos de una tarea se ubican en una sola partición, en orden. El tema de la Unidad 2.5 tiene 6 particiones y un factor de replicación de 3.
Cree los temas de reintentos y de mensajes no procesables de la misma manera:
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
}
Cada clúster tiene tres brokers, por lo que debe utilizar números de particiones que sean múltiplos de 3 para lograr una distribución uniforme. Sin retention_time, un tema conserva los mensajes durante 604800000 ms (7 días); -1 elimina el límite de tiempo.
2.2 El productor
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=allespera hasta que todas las réplicas sincronizadas tengan la escritura, de modo que la falla de un solo broker no provoca ninguna pérdida.enable.idempotenceimpide que las reintentos creen duplicados y mantiene el orden por partición.linger.msybatch.sizeintercambian unos pocos milisegundos de latencia por solicitudes menos frecuentes y de mayor tamaño.
Llame a producer.flush(10) al cerrar, por ejemplo en su controlador de ciclo de vida de FastAPI, o el último lote se perderá cuando Kubernetes detenga el pod.
3. Consumo con control de desplazamiento
3.1 Grupo de consumidores y confirmaciones
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()
Todos los pods de worker comparten el group.id, por lo que Kafka divide las particiones entre ellos. Con enable.auto.commit desactivado, el worker confirma un desplazamiento solo después de haber procesado el mensaje.
3.2 Semántica de entrega
| Punto de confirmación | Entrega | Efecto ante una falla |
|---|---|---|
| Después del procesamiento (este código) | Al menos una vez | Una falla entre el procesamiento y la confirmación reproduce el mensaje |
| Antes del procesamiento | Como máximo una vez | Una falla después de la confirmación pierde el mensaje |
Como muestra la tabla, la entrega al menos una vez puede entregar un mensaje dos veces, por lo que debe hacer que el manejador sea idempotente. El notificador registra cada event_id en PostgreSQL con una restricción de unicidad y omite los eventos que ya ha enviado.
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. Reintentos, mensajes muertos y contratos de eventos
4.1 Enrutamiento de reintentos y mensajes muertos
Un mensaje que siempre falla, un mensaje tóxico, no debe bloquear su partición. El trabajador reintenta algunas veces a través del tema de reintentos y luego estaciona el mensaje en el tema de mensajes muertos:
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)
El offset original se confirma después de que el mensaje se haya almacenado de forma segura en el siguiente tema, por lo que la partición continúa. Un JSON no válido o una verificación de esquema fallida se envía de inmediato al tema de mensajes no procesados, porque un reintento no puede corregirlo. Una herramienta pequeña puede leer el tema de mensajes no procesados, corregir la causa y volver a producir los mensajes en task-events.
4.2 Gestión de esquemas
Kafka almacena bytes; el contrato entre la API y el worker es su responsabilidad. Defínalo como un JSON Schema en un paquete compartido y vérfiquelo en ambos lados:
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)
Evolucione el esquema de forma aditiva: agregue campos opcionales, nunca cambie el nombre ni elimine uno. Para un cambio que rompe la compatibilidad, incremente schema_version y mantenga al consumidor leyendo ambas versiones hasta que no quede ningún productor antiguo. Avro con un registro de esquemas ofrece la misma disciplina con soporte del compilador.
5. Escalado de consumidores en Kubernetes
La cantidad de particiones es el límite de paralelismo de un grupo de consumidores: cada partición es leída por como máximo un consumidor dentro del grupo. Con 6 particiones, un séptimo pod de trabajador permanece inactivo.
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
Cuando un pod se inicia o se detiene, el grupo se reequilibra y las particiones se mueven entre pods. Maneje SIGTERM abandonando el bucle de sondeo y llamando a consumer.close(), de modo que el grupo se reequilibre de inmediato en lugar de esperar a que venza el tiempo de espera de la sesión. Mantenga el procesamiento de cada mensaje bien por debajo de max.poll.interval.ms, o el broker eliminará al consumidor del grupo. Para elevar el límite, agregue particiones en múltiplos de 3; tenga en cuenta que esto cambia a qué partición se asigna una clave.
Tarjeta rápida de referencia de la API
Endpoints clave de la API de Kafka para esta unidad:
| Método | Endpoint | Descripción |
|---|---|---|
GET |
/clusters/{clusterId} |
Leer el estado del clúster y brokerAddresses |
GET |
/clusters/{clusterId}/users |
Listar usuarios y sus identificadores |
GET |
/clusters/{clusterId}/users/{userId}/access |
Obtener la CA, el certificado del cliente y la clave privada |
POST |
/clusters/{clusterId}/topics |
Crear un tema |
DELETE |
/clusters/{clusterId}/topics/{topicId} |
Eliminar un tema y sus datos |
URL base: regional, por ejemplo https://kafka.de-txl.ionos.com
Autenticación: Authorization: Bearer <token> para la API; mTLS para productores y consumidores
Laboratorio de código
Objetivo: Producir y consumir eventos de cambios de tareas de TaskBoard en Event Streams for Apache Kafka mediante un grupo de consumidores, confirmaciones manuales de desplazamientos y un tema de mensajes no procesados.
Requisitos previos:
- El clúster de Kafka y el tema
task-eventsde la Unidad 2.5, además de los temas de reintentos y de mensajes no procesados de la Sección 2.1 - Las salidas de la Sección 1.1, aplicadas
- Una VM o un pod en la LAN del clúster con Python 3.12,
confluent-kafkayjsonschema
Paso 1: Escribir los certificados
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
Salida esperada:
notAfter=<date about one year from issue>
Paso 2: Enumere los temas
from confluent_kafka.admin import AdminClient
print(sorted(AdminClient(KAFKA_TLS).list_topics(timeout=10).topics))
Salida esperada:
['task-events', 'task-events-dlq', 'task-events-retry', ...]
Paso 3: Producir tres eventos
for tid in (1, 2, 3):
publish_task_event(tid, "task.completed", {"title": f"Task {tid}"})
print("unflushed:", producer.flush(10))
Salida esperada:
unflushed: 0
Paso 4: Generar un mensaje de envenenamiento
producer.produce("task-events", key="99", value=b"not json"); producer.flush(10)
Salida esperada:
(no output)
Paso 5: Ejecutar el consumidor
Ejecute el bucle de la sección 3.1 con send_notifications = lambda e: print("notify", e["task_id"]) y deténgalo después de unos segundos.
Salida esperada:
notify 1
notify 2
notify 3
Paso 6: Inspeccionar el tema de mensajes no procesados
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()))
Salida esperada:
b'not json' {'attempt': b'1', 'error': b'JSONDecodeError', 'source': b'task-events/...'}
Paso 7: Verificar los desplazamientos confirmados
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)])
Salida esperada:
[<offset or -1001 per partition>, ...]
Ejecute esto con un nuevo consumidor en el grupo taskboard-notifier; las particiones que recibieron eventos muestran un desplazamiento confirmado.
Lista de verificación de validación:
- [ ] El cliente se conecta con mTLS utilizando el CA del clúster
- [ ] Cada evento válido se notifica una sola vez, incluso después de un reinicio del consumidor
- [ ] El mensaje defectuoso termina en
task-events-dlqcon su recuento de intentos y su origen - [ ] Los desplazamientos se confirman solo después del procesamiento
Limpieza:
rm -f /etc/kafka/client-key.pem
terraform destroy -auto-approve -target=ionoscloud_kafka_cluster_topic.task_events_dlq
Errores comunes
Errores de desarrollo que debe evitar con el tema de esta unidad:
-
Fallos de negociación (handshake) después de un año
- Problema: Los productores y consumidores fallan de repente con errores de negociación SSL, aunque no se haya cambiado nada.
- Por qué ocurre: Los certificados del cliente son válidos por 365 días, y los pods siguen montando el certificado antiguo.
- Solución: Obtenga el certificado renovado, que está disponible 30 días antes de su vencimiento, actualice el Secret de Kubernetes y realice el despliegue (roll) de los Deployments.
-
Verificación del nombre de host contra direcciones IP
- Problema: El cliente no puede conectarse y registra un fallo de verificación del certificado para el broker.
- Por qué ocurre: Las versiones recientes de librdkafka verifican el nombre de host del broker de forma predeterminada, mientras que la configuración del cliente documentada para el cluster desactiva esa verificación.
- Solución: Establezca
ssl.endpoint.identification.algorithmennoney mantengassl.ca.locationapuntando a la CA del cluster.
-
Más consumidores, pero no más rendimiento
- Problema: Escala el worker a 10 réplicas, y la demora (lag) no disminuye.
- Por qué ocurre: Solo tantos consumidores como particiones reciben trabajo; el resto permanece inactivo.
- Solución: Mantenga las réplicas en o por debajo del número de particiones, o agregue particiones en múltiplos de 3.
Resumen
Ahora puede conectar los servicios de TaskBoard a Event Streams for Apache Kafka con calidad de producción. Los clientes se autentican mediante mTLS utilizando el CA, el certificado y la clave que proporciona Terraform o la API, y los brokers se alcanzan en la LAN privada. La API genera eventos con clave y validados por esquema mediante un productor idempotente acks=all. El worker confirma los offsets después del procesamiento, elimina duplicados por ID de evento y transfiere los mensajes defectuosos a través de un tema de reintentos a un tema de mensajes no procesados.
Puntos clave:
- Autentíquese mediante mTLS; valide el servidor con el CA del clúster y desactive las comprobaciones de nombre de host
- Los certificados de cliente tienen una duración de 365 días; automatice su renovación
- Utilice
acks=ally la idempotencia para los productores; confirme los offsets después del procesamiento para garantizar al menos una vez - Dirija los fallos a temas de reintentos y de mensajes no procesados para que un mensaje defectuoso nunca bloquee una partición
- El número de particiones limita la paralelización de los consumidores; use múltiplos de 3 para los tres brokers
Terminología importante:
- mTLS: TLS mutuo, donde tanto el cliente como el broker presentan certificados que la otra parte verifica
- Grupo de consumidores: Consumidores que comparten un
group.idy que dividen las particiones de un tema entre ellos - Confirmación de offset: La posición almacenada en una partición desde la cual un grupo reanuda tras un reinicio
- Tema de mensajes no procesados: Un tema que almacena mensajes que han fallado en todos los reintentos, para su inspección posterior
- Productor idempotente: Un productor cuyos reintentos nunca escriben un duplicado y mantienen el orden de la partición
Próximos pasos
Continuar aprendiendo: Unidad 4.4: Integración de AI Model Hub
Temas relacionados: