Monedula GitOps:
gestione dichiarativa di Kafka per CLI e 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: 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:

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:

brew install monedula-dev/tap/monedula-gitops

Oppure con Go:

go install github.com/monedula-dev/monedula-gitops/cmd/monedula-gitops@latest

I binari precompilati sono disponibili nelle release su GitHub. L’immagine container è pubblicata su ghcr.io/monedula-dev/monedula-gitops.

Installa l’operator Kubernetes con Helm:

helm install monedula-gitops \
  oci://ghcr.io/monedula-dev/charts/monedula-gitops

Nel repository trovi la configurazione completa della CLI e l’installazione dell’operator.

Avvio rapido

Una volta che hai una configurazione KafkaCluster e uno o più manifest, il flusso di base è breve:

# 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 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:

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.

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 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.

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.