--- title: "Monedula GitOps: gestione dichiarativa di Kafka per CLI e Kubernetes" date: 2026-08-24T00:00:00.000Z author: "grzegorz" excerpt: "Monedula GitOps gestisce topic Kafka, accessi, quote, schemi, utenti e RBAC di Confluent a partire da manifest versionati, tramite una CLI oppure un operator Kubernetes." --- La configurazione di Kafka vive raramente in un unico posto. I topic vengono creati da uno script, le ACL da un altro, gli schemi dalle pipeline applicative, le quote da chi amministra il sistema e i role binding RBAC di Confluent da un ulteriore strumento. Con il tempo il cluster in esecuzione diventa l'unica descrizione affidabile del sistema, ma non una descrizione intenzionale né revisionabile. Per questo abbiamo creato [Monedula GitOps](https://github.com/monedula-dev/monedula-gitops): uno strumento open source per gestire le risorse Kafka come YAML dichiarativo e versionato. L'obiettivo è semplice: > Descrivi lo stato Kafka desiderato in Git, rivedilo come codice, confrontalo con il cluster in esecuzione e fai convergere il cluster verso di esso. Questo articolo presenta la prima release pubblica, `v0.1.0`. Si concentra sul modello e sul flusso di lavoro di base, senza ripetere l'intera documentazione. ## Perché un altro strumento GitOps per Kafka? GitOps dà all'infrastruttura una fonte di verità chiara, uno storico di revisioni, cambiamenti ripetibili e il rilevamento del drift. Kafka, però, non è solo topic. Uno strumento di gestione utile deve capire anche regole di accesso, consumer group, quote, schemi, credenziali e — in Confluent Platform — i role binding RBAC. C'è poi un problema di adozione: la maggior parte dei cluster Kafka esiste già. Ricostruire a mano il loro stato completo sotto forma di manifest prima di adottare GitOps crea una barriera di migrazione notevole. Monedula GitOps è stato progettato attorno a entrambi i problemi: * coprire le risorse specifiche di Kafka che di solito stanno insieme; * rendere semplice il caso comune, in particolare un topic e le applicazioni autorizzate a usarlo; * supportare i cluster esistenti tramite un flusso di import; * funzionare sia con sia senza Kubernetes. ## Un modello dichiarativo, due modi di eseguirlo La decisione di progettazione centrale è che la CLI e l'operator Kubernetes usano lo stesso modello di risorse e lo stesso motore di riconciliazione. In modalità CLI i manifest si possono validare, confrontare, applicare e verificare da una macchina di sviluppo o da una pipeline CI/CD. In modalità operator le stesse risorse in stile Kubernetes vengono installate come CRD e riconciliate di continuo dentro un cluster Kubernetes. Un `KafkaTopic` usato dalla CLI può quindi essere applicato anche come custom resource di Kubernetes. Le credenziali vengono naturalmente fornite in modo diverso nei due runtime — per esempio riferimenti a variabili d'ambiente o a file per la CLI e Secret di Kubernetes per l'operator — ma lo stato desiderato, le regole di drift e la semantica di esecuzione restano coerenti. Così un team può iniziare con cambiamenti guidati dalla pipeline e adottare l'operator più avanti, senza progettare un secondo modello di configurazione. ## Un topic e i suoi accessi in un unico manifest La risorsa con cui si lavora più spesso dovrebbe essere anche la più facile da descrivere. Un `KafkaTopic` può contenere il numero di partizioni, la configurazione del topic, lo schema dello Schema Registry e le regole di accesso più comuni per producer e consumer: ```yaml 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-orders ``` Da questo manifest Monedula GitOps gestisce il topic e genera le corrispondenti ACL di topic e di consumer group. Monedula GitOps supporta sia le ACL standard di Kafka sia i role binding RBAC specifici di Confluent Platform. Le ACL locali al topic più comuni si possono definire direttamente in `KafkaTopic`; per i casi avanzati — risorse con prefisso, consumer group condivisi, restrizioni sugli host o operazioni ACL grezze — il modello include una risorsa separata, `KafkaAccessPolicy`. I role binding RBAC di Confluent si gestiscono con `KafkaRoleBinding`. ## Che cosa può gestire? La prima release copre le principali entità Kafka e Confluent necessarie a una gestione dichiarativa: * `KafkaCluster` — dettagli di connessione, autenticazione, valori predefiniti, Schema Registry e configurazione opzionale di Confluent MDS; * `KafkaTopic` — ciclo di vita del topic, partizioni, configurazione, accesso locale al topic e schemi; * `KafkaAccessPolicy` — regole ACL Kafka avanzate e condivise; * `KafkaQuota` — quote per utente, client-id e IP; * `KafkaUser` — credenziali SCRAM di Kafka; * `KafkaRoleBinding` — role binding MDS/RBAC di Confluent Platform. La CLI mette a disposizione anche comandi di validazione, rilevamento del drift, anteprime sicure, controlli preflight, apply, verify e import. ## Installazione Installa la CLI con Homebrew: ```bash brew install monedula-dev/tap/monedula-gitops ``` Oppure con Go: ```bash go install github.com/monedula-dev/monedula-gitops/cmd/monedula-gitops@latest ``` I binari precompilati sono disponibili nelle [release su GitHub](https://github.com/monedula-dev/monedula-gitops/releases/latest). L'immagine container è pubblicata su `ghcr.io/monedula-dev/monedula-gitops`. Installa l'operator Kubernetes con Helm: ```bash helm install monedula-gitops \ oci://ghcr.io/monedula-dev/charts/monedula-gitops ``` Nel repository trovi la [configurazione completa della CLI](https://github.com/monedula-dev/monedula-gitops/blob/main/docs/cli.md) e l'[installazione dell'operator](https://github.com/monedula-dev/monedula-gitops/blob/main/docs/operator.md). ## Avvio rapido Una volta che hai una configurazione `KafkaCluster` e uno o più manifest, il flusso di base è breve: ```bash # Anteprima della differenza tra Git e il cluster in esecuzione monedula-gitops diff -f ./manifests \ --cluster-config-file ./cluster.yaml # Applica lo stato desiderato monedula-gitops apply -f ./manifests \ --cluster-config-file ./cluster.yaml # Conferma che non resti alcun drift monedula-gitops verify -f ./manifests \ --cluster-config-file ./cluster.yaml ``` `verify` restituisce un exit code diverso da zero quando trova drift, il che lo rende adatto come gate di CI. Le operazioni rischiose sono protette, mentre cancellazione e pruning richiedono un consenso esplicito. Per un ambiente locale completo, il repository include due [quickstart](https://github.com/monedula-dev/monedula-gitops/tree/main/quickstart) eseguibili: un playground CLI con Docker Compose, Kafka e Schema Registry, e un playground per l'operator su un cluster Kubernetes locale. ## Partire da un cluster esistente con Import Gli strumenti GitOps sono facili da mostrare su un cluster vuoto. Gli ambienti reali sono raramente vuoti. Il comando `import cluster` legge lo stato attuale di Kafka e ne genera i manifest Monedula: ```bash monedula-gitops import cluster \ --cluster-config-file ./cluster.yaml \ --output-dir ./imported ``` L'importer ricostruisce topic, regole di accesso, quote, schemi, utenti SCRAM e, dove supportati, i role binding RBAC di Confluent. Le ACL semplici di producer e consumer vengono ripiegate nel relativo `KafkaTopic`; le regole avanzate o ambigue diventano risorse a sé stanti. Kafka non può rivelare le password SCRAM esistenti, quindi gli utenti importati contengono riferimenti a segreti segnaposto, da fornire prima di applicarli. La proprietà importante è il round trip: verificare la directory importata contro lo stesso cluster non dovrebbe segnalare alcun drift. ```bash monedula-gitops verify -f ./imported -R \ --cluster-config-file ./cluster.yaml ``` Import non è quindi solo una funzione di esportazione. È un percorso di adozione per portare un ambiente Kafka esistente verso uno stato desiderato gestito in Git. ## Gli esempi fanno parte del progetto La documentazione di riferimento non è sempre il modo migliore per imparare una configurazione Kafka complicata. Il repository include un ricco [catalogo di scenari](https://github.com/monedula-dev/monedula-gitops/tree/main/scenarios) con 25 set di configurazione autonomi. Coprono topic, regole di accesso inline e avanzate, quote, schemi, drift e riconciliazione, pruning, politiche di cancellazione, multi-tenancy, Import, utenti SCRAM, SASL_SSL, mTLS, OAuth e MDS/RBAC di Confluent. Ogni scenario contiene manifest, una spiegazione, i risultati attesi e le istruzioni per la pulizia. Si possono eseguire come esempi, adattare come punti di partenza o usare come ispirazione per le proprie impostazioni. ## Questa è la prima release: provala `v0.1.0` è la prima release pubblica di Monedula GitOps. Lo strumento copre diverse API Kafka, modelli di autorizzazione, metodi di autenticazione e cicli di vita delle risorse. È un software piuttosto complicato e alcune combinazioni o casi limite potrebbero non funzionare ancora esattamente come previsto. Inizia da un ambiente usa e getta o non di produzione, esamina con attenzione l'output di `diff` o di `apply --dry-run` e abilita le operazioni distruttive solo dopo aver rivisto le modifiche pianificate. Soprattutto, provala. Distribuzioni Kafka diverse, configurazioni di sicurezza e modelli operativi sono esattamente il terreno in cui il riscontro dal campo è prezioso. Se trovi un bug, un comportamento poco chiaro o un caso d'uso mancante, apri una [issue su GitHub](https://github.com/monedula-dev/monedula-gitops/issues). ## Riepilogo Monedula GitOps porta topic Kafka, accessi, quote, schemi, utenti e RBAC di Confluent in un unico modello dichiarativo, che funziona tramite una CLI adatta alla CI oppure tramite un operator Kubernetes. Puoi partire da un cluster vuoto, importarne uno esistente e imparare lo strumento con quickstart eseguibili e scenari già svolti. La prima release è disponibile da subito su [GitHub](https://github.com/monedula-dev/monedula-gitops).