---
title: "Monedula GitOps: deklaratives Kafka-Management für CLI und Kubernetes"
date: 2026-08-24T00:00:00.000Z
author: "grzegorz"
excerpt: "Monedula GitOps verwaltet Kafka-Topics, Zugriff, Quotas, Schemas, Benutzer und Confluent RBAC aus versionierten Manifesten heraus — wahlweise über eine CLI oder einen Kubernetes-Operator."
---
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](https://github.com/monedula-dev/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:

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

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:

```bash
brew install monedula-dev/tap/monedula-gitops
```

Oder mit Go:

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

Vorgebaute Binaries gibt es in den [GitHub-Releases](https://github.com/monedula-dev/monedula-gitops/releases/latest). Ein Container-Image wird unter `ghcr.io/monedula-dev/monedula-gitops` veröffentlicht.

Den Kubernetes-Operator mit Helm installieren:

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

Die vollständige [CLI-Konfiguration](https://github.com/monedula-dev/monedula-gitops/blob/main/docs/cli.md) und die [Operator-Installation](https://github.com/monedula-dev/monedula-gitops/blob/main/docs/operator.md) stehen im Repository.

## Schnellstart

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

```bash
# 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](https://github.com/monedula-dev/monedula-gitops/tree/main/quickstart): 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:

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

```bash
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](https://github.com/monedula-dev/monedula-gitops/tree/main/scenarios) 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](https://github.com/monedula-dev/monedula-gitops/issues).

## 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](https://github.com/monedula-dev/monedula-gitops) verfügbar.