Kafka — broker de streaming de eventos de un solo nodo para Kubernetes
Este ejemplo compila un stack pequeño y real — un broker de streaming de eventos Apache Kafka en su estructura KRaft de un solo nodo — a partir de un único Aggregate escrito por el desarrollador para Kubernetes, sintetizado directamente a partir de la imagen oficial de Apache Kafka sin ningún chart upstream.
Kafka es un broker de streaming de eventos: los productores añaden registros a topics y los consumidores los vuelven a leer en orden. En la estructura KRaft de un solo nodo, los roles de broker y de controlador se ejecutan dentro de un único proceso — sin ZooKeeper y sin un segundo servicio incluido — así que todo el servidor es una única carga de trabajo con estado. El commit log persiste en un volumen de datos local. Un productor o consumidor se conecta al endpoint de bootstrap de clientes e intercambia registros allí.
Archivos
| Archivo | Rol |
|---|---|
aggregate.yaml | Intención del desarrollador: un único componente broker (core/messaging/kafka). |
manifest.yaml | Asigna el tipo de componente a la Recipe de síntesis de Kafka (kafka). |
release.yaml | Documento del operador para el destino Kubernetes: el cómputo del servidor y el tamaño del volumen del commit log. |
Lo que demuestra
- Una única superficie de autoría. Un único Aggregate es la fuente de verdad sobre qué es Kafka; el Manifest dice cómo realizarlo.
- Un broker KRaft de un solo nodo. La Recipe de síntesis renderiza Kafka como un único
StatefulSetcon un volumen de datos y dos objetosService— unClusterIPque expone el puerto de bootstrap de clientes, y un Service headless de gobierno para el StatefulSet. - KRaft, sin ZooKeeper. El nodo ejecuta tanto el rol de broker como el de controlador en un único proceso, configurado por completo mediante variables de entorno.
- Una identidad de clúster fijada. La identidad del clúster es un valor fijo del desarrollador que se pasa literalmente a la imagen, que la lee tal cual sin ninguna generación aleatoria, así que el manifiesto renderizado es idéntico byte a byte entre compilaciones.
- Una dirección anunciada estable. El broker anuncia el nombre del Service interno del clúster, así que los clientes se reconectan a través de la dirección estable en lugar del nombre de host propio del pod.
- Log persistente. El commit log escribe en el volumen persistente en
/var/lib/kafka/data, así que los datos de los registros sobreviven a los reinicios. - Un contrato de bootstrap exportado. El componente exporta su host de bootstrap y su puerto de clientes mediante la topología
uses, así que un productor o consumidor se cablea a él y se conecta allí. - Imágenes reproducibles. La Recipe fija la imagen del servidor Kafka a una etiqueta resoluble, así que la carga de trabajo renderizada hace referencia a una versión fijada.
Generar el ejemplo
Puedes compilar este ejemplo con los comandos de abajo, o hacer que tu asistente de IA lo compile por ti.
Escribe el ejemplo en una carpeta nueva con su nombre:
aggrega scaffold --example kafka-brokerDespués imprime los comandos que hay que ejecutar a continuación. El primero entra en la carpeta nueva:
cd kafka-brokerCompilación
Este espacio de trabajo no contiene ningún .aggrega-config.yaml, así que las entidades de la biblioteca estándar se resuelven desde el registro del hub, hub.aggrega.ai, y no hace falta ningún flag de catálogo:
aggrega pull --release release.yamlaggrega build --release release.yamlLos artefactos renderizados quedan en dist/. El destino Kubernetes renderiza manifiestos simples sin conexión — no se requiere ningún pull de chart.
Con un asistente de IA
Un asistente de IA configurado con las herramientas de Aggrega puede hacer lo mismo: pégale este prompt.
Usa solo las herramientas de Aggrega y no crees tú ninguna carpeta. Si la carpeta del espacio de trabajo aún no contiene una carpeta `kafka-broker`, llama una vez a la herramienta `scaffold` con `example` establecido en `kafka-broker` y sin `dir`: escribe el ejemplo en una nueva carpeta `kafka-broker`. Después llama a la herramienta `build` con `workspace_root` establecido en `kafka-broker`, `release` establecido en `release.yaml`, `auto_pull` establecido en true y `write` establecido en true. Dime qué archivos escribió la compilación; están en `kafka-broker/dist/`.Qué se renderiza
La compilación emite el servidor Kafka como tres objetos de Kubernetes:
- un
StatefulSet— el proceso de Kafka de un solo nodo, con su commit log en un volumen persistente montado en/var/lib/kafka/datay toda la configuración de KRaft suministrada mediante variables de entorno, - un
ServiceClusterIP— que expone el puerto de bootstrap de clientes en el 9092, - un
Serviceheadless — el Service de gobierno que el StatefulSet requiere para una identidad estable por réplica.
La imagen de Kafka está fijada a su etiqueta de release, así que la carga de trabajo hace referencia a una etiqueta de imagen fijada.