14 min de lectura

Objetivos de aprendizaje

Al final de este módulo, podrás:

  • Conectar un productor y un consumidor de confluent-kafka a Event Streams for Apache Kafka con TLS mutuo, utilizando credenciales y direcciones de brokers de Terraform
  • Configurar un productor idempotente con `acks=all` y lotes optimizados para los eventos de cambios de tareas de TaskBoard
  • Implementar un grupo de consumidores con confirmaciones manuales de offsets y entrega al menos una vez
  • Crear temas de reintento y temas de mensajes no procesables que aíslen mensajes defectuosos sin bloquear una partición
  • Escalar consumidores en Managed Kubernetes dentro del límite de número de particiones

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=all espera 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.idempotence impide que las reintentos creen duplicados y mantiene el orden por partición.
  • linger.ms y batch.size intercambian 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-events de 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-kafka y jsonschema

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

  1. 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.
  2. 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.algorithm en none y mantenga ssl.ca.location apuntando a la CA del cluster.
  3. 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=all y 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.id y 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: