La configuración de Kafka rara vez vive en un solo sitio.
Los topics los crea un script, las ACL otro, los esquemas los pipelines de las aplicaciones, las cuotas alguien de administración y los role bindings de RBAC de Confluent otra herramienta más. Con el tiempo, el clúster en marcha acaba siendo la única descripción fiable del sistema, pero no una descripción intencionada ni revisable.
Por eso creamos Monedula GitOps: una herramienta de código abierto para gestionar recursos de Kafka como YAML declarativo y versionado.
El objetivo es sencillo:
Describe el estado deseado de Kafka en Git, revísalo como si fuera código, compáralo con el clúster en marcha y haz converger el clúster hacia él.
Este artículo presenta la primera versión pública, v0.1.0. Se centra en el modelo y en el flujo de trabajo básico, en lugar de repetir la documentación completa.
¿Por qué otra herramienta GitOps para Kafka?
GitOps aporta a la infraestructura una fuente de verdad clara, historial de revisiones, cambios repetibles y detección de drift. Kafka, sin embargo, no son solo topics. Una herramienta de gestión útil también tiene que entender reglas de acceso, grupos de consumidores, cuotas, esquemas, credenciales y —en Confluent Platform— role bindings de RBAC.
Hay además un problema de adopción: la mayoría de los clústeres de Kafka ya existen. Recrear a mano todo su estado en forma de manifiestos antes de adoptar GitOps supone una barrera de migración enorme.
Monedula GitOps se diseñó alrededor de ambos problemas:
- cubrir los recursos específicos de Kafka que suelen ir juntos;
- hacer sencillo el caso común, sobre todo un topic y las aplicaciones autorizadas a usarlo;
- dar soporte a clústeres existentes mediante un flujo de importación;
- funcionar con y sin Kubernetes.
Un modelo declarativo, dos formas de ejecutarlo
La decisión de diseño central es que la CLI y el operador de Kubernetes usan el mismo modelo de recursos y el mismo motor de reconciliación.
En modo CLI, los manifiestos se pueden validar, comparar, aplicar y verificar desde la máquina de desarrollo o desde un pipeline de CI/CD. En modo operador, esos mismos recursos al estilo Kubernetes se instalan como CRD y se reconcilian de forma continua dentro de un clúster de Kubernetes.
Por eso un KafkaTopic usado por la CLI también puede aplicarse como recurso personalizado de Kubernetes. Las credenciales se proporcionan, naturalmente, de forma distinta en cada entorno de ejecución —por ejemplo, referencias a variables de entorno o a ficheros en la CLI y Secrets de Kubernetes en el operador—, pero el estado deseado, las reglas de drift y la semántica de ejecución se mantienen coherentes.
Esto permite que un equipo empiece con cambios impulsados por el pipeline y adopte más tarde el operador sin diseñar un segundo modelo de configuración.
Un topic y su acceso en un único manifiesto
El recurso con el que más se trabaja debería ser también el más fácil de describir.
Un KafkaTopic puede contener su número de particiones, la configuración del topic, el esquema del Schema Registry y las reglas de acceso habituales de productores y consumidores:
apiVersion: gitops.monedula.dev/v1alpha1
kind: KafkaTopic
metadata:
name: orders
spec:
clusterRef:
name: prod
topicName: orders
partitions: 6
config:
retention.ms: "604800000"
access:
producers:
- principal: User:svc-checkout
consumers:
- principal: User:svc-fraud
group: fraud-ordersA partir de este manifiesto, Monedula GitOps gestiona el topic y genera las ACL correspondientes de topic y de grupo de consumidores.
Monedula GitOps admite tanto las ACL estándar de Kafka como los role bindings de RBAC específicos de Confluent Platform. Las ACL locales al topic más habituales se pueden definir directamente en KafkaTopic; para casos avanzados —recursos con prefijo, grupos de consumidores compartidos, restricciones de host u operaciones ACL en crudo— el modelo incluye un recurso aparte, KafkaAccessPolicy. Los role bindings de RBAC de Confluent se gestionan con KafkaRoleBinding.
¿Qué puede gestionar?
La primera versión cubre las principales entidades de Kafka y Confluent necesarias para una gestión declarativa:
KafkaCluster— datos de conexión, autenticación, valores por defecto, Schema Registry y configuración opcional de Confluent MDS;KafkaTopic— ciclo de vida del topic, particiones, configuración, acceso local al topic y esquemas;KafkaAccessPolicy— reglas ACL de Kafka avanzadas y compartidas;KafkaQuota— cuotas por usuario, client-id e IP;KafkaUser— credenciales SCRAM de Kafka;KafkaRoleBinding— role bindings MDS/RBAC de Confluent Platform.
La CLI ofrece además comandos de validación, detección de drift, previsualizaciones seguras, comprobaciones preflight, aplicación, verificación e importación.
Instalación
Instala la CLI con Homebrew:
brew install monedula-dev/tap/monedula-gitopsO con Go:
go install github.com/monedula-dev/monedula-gitops/cmd/monedula-gitops@latestHay binarios precompilados en las releases de GitHub. La imagen de contenedor se publica en ghcr.io/monedula-dev/monedula-gitops.
Instala el operador de Kubernetes con Helm:
helm install monedula-gitops \
oci://ghcr.io/monedula-dev/charts/monedula-gitopsConsulta el repositorio para la configuración completa de la CLI y la instalación del operador.
Inicio rápido
Cuando ya tienes una configuración de KafkaCluster y uno o varios manifiestos, el flujo básico es corto:
# Previsualiza la diferencia entre Git y el clúster en marcha
monedula-gitops diff -f ./manifests \
--cluster-config-file ./cluster.yaml
# Aplica el estado deseado
monedula-gitops apply -f ./manifests \
--cluster-config-file ./cluster.yaml
# Confirma que no queda drift
monedula-gitops verify -f ./manifests \
--cluster-config-file ./cluster.yamlverify devuelve un código de salida distinto de cero cuando encuentra drift, lo que lo hace adecuado como gate de CI. Las operaciones arriesgadas están protegidas, y el borrado y el pruning requieren activarlos explícitamente.
Para un entorno local completo, el repositorio incluye dos quickstarts ejecutables: un playground de CLI con Docker Compose, Kafka y Schema Registry, y un playground del operador sobre un clúster local de Kubernetes.
Empieza desde un clúster existente con Import
Las herramientas GitOps son fáciles de demostrar en un clúster vacío. Los entornos reales rara vez lo están.
El comando import cluster lee el estado actual de Kafka y genera manifiestos de Monedula a partir de él:
monedula-gitops import cluster \
--cluster-config-file ./cluster.yaml \
--output-dir ./importedEl importador reconstruye topics, reglas de acceso, cuotas, esquemas, usuarios SCRAM y role bindings de RBAC de Confluent allí donde hay soporte. Las ACL simples de productor y consumidor se pliegan dentro del KafkaTopic correspondiente; las reglas avanzadas o ambiguas pasan a ser recursos independientes.
Kafka no puede revelar las contraseñas SCRAM existentes, así que los usuarios importados contienen referencias a secretos de marcador de posición que hay que rellenar antes de aplicarlos.
La propiedad importante es el viaje de ida y vuelta: verificar el directorio importado contra el mismo clúster no debería reportar ningún drift.
monedula-gitops verify -f ./imported -R \
--cluster-config-file ./cluster.yamlPor eso Import no es solo una función de exportación. Es una vía de adopción para llevar un entorno de Kafka existente hacia un estado deseado gestionado desde Git.
Los ejemplos forman parte del proyecto
La documentación de referencia no siempre es la mejor manera de aprender una configuración complicada de Kafka.
El repositorio incluye un completo catálogo de escenarios con 25 conjuntos de configuración autocontenidos. Cubren topics, reglas de acceso en línea y avanzadas, cuotas, esquemas, drift y reconciliación, pruning, políticas de borrado, multi-tenancy, Import, usuarios SCRAM, SASL_SSL, mTLS, OAuth y MDS/RBAC de Confluent.
Cada escenario contiene manifiestos, una explicación, los resultados esperados e instrucciones de limpieza. Se pueden ejecutar como ejemplos, adaptar como punto de partida o usar como inspiración para tus propios ajustes.
Es la primera versión: pruébala, por favor
v0.1.0 es la primera versión pública de Monedula GitOps.
La herramienta cubre varias API de Kafka, modelos de autorización, métodos de autenticación y ciclos de vida de recursos. Es una pieza de software bastante complicada, y puede que algunas combinaciones o casos límite todavía no funcionen exactamente como se espera.
Empieza por un entorno desechable o no productivo, revisa con atención la salida de diff o de apply --dry-run y habilita las operaciones destructivas solo después de repasar los cambios previstos.
Y sobre todo, pruébala. Las distintas distribuciones de Kafka, configuraciones de seguridad y modelos operativos son justo donde el feedback del mundo real resulta valioso. Si encuentras un fallo, un comportamiento poco claro o un caso de uso que falta, abre una issue en GitHub.
Resumen
Monedula GitOps reúne topics de Kafka, accesos, cuotas, esquemas, usuarios y RBAC de Confluent en un único modelo declarativo que funciona mediante una CLI apta para CI o un operador de Kubernetes. Puedes partir de un clúster vacío, importar uno existente y aprender la herramienta con quickstarts ejecutables y escenarios resueltos.
La primera versión ya está disponible en GitHub.