Kafka-Konfiguration liegt selten an einem einzigen Ort.

Topics werden von einem Skript angelegt, ACLs von einem anderen, Schemas von Anwendungs-Pipelines, Quotas von der Administration, und Confluent-RBAC-Rollenbindungen über wieder ein anderes Werkzeug. Mit der Zeit ist der laufende Cluster die einzige verlässliche Beschreibung des Systems — aber keine beabsichtigte und keine, die man reviewen könnte.

Deshalb haben wir Monedula GitOps entwickelt: ein Open-Source-Werkzeug, das Kafka-Ressourcen als deklaratives, versioniertes YAML verwaltet.

Das Ziel ist einfach:

Beschreibe den gewünschten Kafka-Zustand in Git, reviewe ihn wie Code, vergleiche ihn mit dem laufenden Cluster und führe den Cluster darauf zu.

Dieser Artikel stellt das erste öffentliche Release vor, v0.1.0. Er konzentriert sich auf das Modell und den grundlegenden Workflow, statt die vollständige Dokumentation zu wiederholen.

Warum noch ein GitOps-Werkzeug für Kafka?

GitOps gibt Infrastruktur eine klare Source of Truth, eine Review-Historie, wiederholbare Änderungen und Drift-Erkennung. Kafka besteht aber nicht nur aus Topics. Ein brauchbares Management-Werkzeug muss auch Zugriffsregeln, Consumer Groups, Quotas, Schemas, Credentials und — in der Confluent Platform — RBAC-Rollenbindungen verstehen.

Dazu kommt ein Einführungsproblem: Die meisten Kafka-Cluster existieren bereits. Ihren vollständigen Zustand vor der GitOps-Einführung von Hand als Manifeste nachzubauen, ist eine hohe Migrationshürde.

Monedula GitOps wurde um beide Probleme herum entworfen:

  • die Kafka-spezifischen Ressourcen abdecken, die üblicherweise zusammengehören;
  • den häufigsten Fall einfach halten, insbesondere ein Topic und die Anwendungen, die es nutzen dürfen;
  • bestehende Cluster über einen Import-Workflow unterstützen;
  • mit und ohne Kubernetes funktionieren.

Ein deklaratives Modell, zwei Betriebsarten

Die zentrale Designentscheidung: CLI und Kubernetes-Operator nutzen dasselbe Ressourcenmodell und dieselbe Reconciliation-Engine.

Im CLI-Modus lassen sich Manifeste von einem Entwicklungsrechner oder aus einer CI/CD-Pipeline heraus validieren, vergleichen, anwenden und verifizieren. Im Operator-Modus werden dieselben Kubernetes-artigen Ressourcen als CRDs installiert und innerhalb eines Kubernetes-Clusters fortlaufend abgeglichen.

Ein KafkaTopic, das die CLI verwendet, kann deshalb auch als Kubernetes Custom Resource angewendet werden. Credentials werden in beiden Laufzeiten naturgemäß unterschiedlich bereitgestellt — etwa als Umgebungs- oder Dateireferenzen für die CLI und als Kubernetes Secrets für den Operator —, aber gewünschter Zustand, Drift-Regeln und Ausführungssemantik bleiben konsistent.

So kann ein Team mit Pipeline-getriebenen Änderungen beginnen und später den Operator einführen, ohne ein zweites Konfigurationsmodell entwerfen zu müssen.

Ein Topic und sein Zugriff in einem Manifest

Die Ressource, mit der am häufigsten gearbeitet wird, sollte sich auch am einfachsten beschreiben lassen.

Ein KafkaTopic kann seine Partitionsanzahl, die Topic-Konfiguration, das Schema Registry-Schema sowie übliche Producer- und Consumer-Zugriffsregeln enthalten:

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

Aus diesem Manifest verwaltet Monedula GitOps das Topic und erzeugt die zugehörigen Topic- und Consumer-Group-ACLs.

Monedula GitOps unterstützt sowohl Standard-Kafka-ACLs als auch die Confluent-Platform-spezifischen RBAC-Rollenbindungen. Übliche topic-lokale ACLs lassen sich direkt in KafkaTopic definieren; für fortgeschrittene Fälle wie präfixierte Ressourcen, gemeinsam genutzte Consumer Groups, Host-Einschränkungen oder rohe ACL-Operationen enthält das Modell eine eigene Ressource KafkaAccessPolicy. Confluent-RBAC-Rollenbindungen werden mit KafkaRoleBinding verwaltet.

Was kann es verwalten?

Das erste Release deckt die wichtigsten Kafka- und Confluent-Entitäten ab, die für deklaratives Management nötig sind:

  • KafkaCluster — Verbindungsdaten, Authentifizierung, Defaults, Schema Registry und optionale Confluent-MDS-Konfiguration;
  • KafkaTopic — Topic-Lebenszyklus, Partitionen, Konfiguration, topic-lokaler Zugriff und Schemas;
  • KafkaAccessPolicy — fortgeschrittene und gemeinsam genutzte Kafka-ACL-Regeln;
  • KafkaQuota — Quotas für Benutzer, Client-ID und IP;
  • KafkaUser — Kafka-SCRAM-Credentials;
  • KafkaRoleBinding — MDS/RBAC-Rollenbindungen der Confluent Platform.

Die CLI bietet außerdem Befehle für Validierung, Drift-Erkennung, sichere Vorschauen, Preflight-Checks, Apply, Verify und Import.

Installation

Die CLI mit Homebrew installieren:

brew install monedula-dev/tap/monedula-gitops

Oder mit Go:

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

Vorgebaute Binaries gibt es in den GitHub-Releases. Ein Container-Image wird unter ghcr.io/monedula-dev/monedula-gitops veröffentlicht.

Den Kubernetes-Operator mit Helm installieren:

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

Die vollständige CLI-Konfiguration und die Operator-Installation stehen im Repository.

Schnellstart

Sobald eine KafkaCluster-Konfiguration und ein oder mehrere Manifeste vorliegen, ist der grundlegende Workflow kurz:

# Den Unterschied zwischen Git und dem laufenden Cluster ansehen
monedula-gitops diff -f ./manifests \
  --cluster-config-file ./cluster.yaml

# Den gewünschten Zustand anwenden
monedula-gitops apply -f ./manifests \
  --cluster-config-file ./cluster.yaml

# Bestätigen, dass kein Drift übrig bleibt
monedula-gitops verify -f ./manifests \
  --cluster-config-file ./cluster.yaml

verify liefert bei erkanntem Drift einen Exit-Code ungleich null und eignet sich damit als CI-Gate. Riskante Operationen sind abgesichert, Löschen und Pruning erfordern eine ausdrückliche Freigabe.

Für eine vollständige lokale Umgebung enthält das Repository zwei lauffähige Quickstarts: einen CLI-Spielplatz mit Docker Compose, Kafka und Schema Registry sowie einen Operator-Spielplatz auf einem lokalen Kubernetes-Cluster.

Mit Import bei einem bestehenden Cluster starten

GitOps-Werkzeuge lassen sich auf einem leeren Cluster leicht vorführen. Echte Umgebungen sind selten leer.

Der Befehl import cluster liest den aktuellen Kafka-Zustand und erzeugt daraus Monedula-Manifeste:

monedula-gitops import cluster \
  --cluster-config-file ./cluster.yaml \
  --output-dir ./imported

Der Importer rekonstruiert Topics, Zugriffsregeln, Quotas, Schemas, SCRAM-Benutzer und — wo unterstützt — Confluent-RBAC-Rollenbindungen. Einfache Producer- und Consumer-ACLs werden in das jeweilige KafkaTopic eingefaltet; fortgeschrittene oder mehrdeutige Regeln werden zu eigenständigen Ressourcen.

Kafka kann bestehende SCRAM-Passwörter nicht offenlegen, deshalb enthalten importierte Benutzer Platzhalter-Secret-Referenzen, die vor dem Anwenden gefüllt werden müssen.

Entscheidend ist der Round Trip: Wird das importierte Verzeichnis gegen denselben Cluster verifiziert, sollte kein Drift gemeldet werden.

monedula-gitops verify -f ./imported -R \
  --cluster-config-file ./cluster.yaml

Import ist damit nicht nur eine Export-Funktion. Es ist ein Onboarding-Pfad, um eine bestehende Kafka-Umgebung in Richtung eines Git-verwalteten Zielzustands zu bewegen.

Beispiele sind Teil des Projekts

Referenzdokumentation ist nicht immer der beste Weg, eine komplizierte Kafka-Konfiguration zu lernen.

Das Repository enthält einen umfangreichen Szenarienkatalog mit 25 in sich geschlossenen Konfigurationssätzen. Sie decken Topics, inline und fortgeschrittene Zugriffsregeln, Quotas, Schemas, Drift und Reconciliation, Pruning, Löschrichtlinien, Mandantenfähigkeit, Import, SCRAM-Benutzer, SASL_SSL, mTLS, OAuth sowie Confluent MDS/RBAC ab.

Jedes Szenario enthält Manifeste, eine Erläuterung, erwartete Ergebnisse und Aufräumhinweise. Man kann sie als Beispiele ausführen, als Ausgangspunkt anpassen oder als Anregung für eigene Einstellungen nutzen.

Das ist das erste Release — bitte testet es

v0.1.0 ist das erste öffentliche Release von Monedula GitOps.

Das Werkzeug deckt mehrere Kafka-APIs, Autorisierungsmodelle, Authentifizierungsmethoden und Ressourcen-Lebenszyklen ab. Es ist ein recht kompliziertes Stück Software, und manche Kombinationen oder Randfälle funktionieren womöglich noch nicht genau wie erwartet.

Beginnt bitte mit einer Wegwerf- oder Nicht-Produktionsumgebung, seht euch die Ausgabe von diff oder apply --dry-run genau an und aktiviert destruktive Operationen erst, nachdem ihr die geplanten Änderungen geprüft habt.

Vor allem aber: Testet es. Unterschiedliche Kafka-Distributionen, Sicherheitskonfigurationen und Betriebsmodelle sind genau die Stellen, an denen Rückmeldungen aus der Praxis wertvoll sind. Wenn ihr einen Bug, unklares Verhalten oder einen fehlenden Anwendungsfall findet, eröffnet ein Issue auf GitHub.

Fazit

Monedula GitOps bringt Kafka-Topics, Zugriff, Quotas, Schemas, Benutzer und Confluent RBAC in ein einziges deklaratives Modell, das entweder über eine CI-freundliche CLI oder einen Kubernetes-Operator funktioniert. Ihr könnt bei einem leeren Cluster beginnen, einen bestehenden importieren und das Werkzeug anhand lauffähiger Quickstarts und durchgearbeiteter Szenarien kennenlernen.

Das erste Release ist ab sofort auf GitHub verfügbar.