--- title: "Monedula GitOps: Declarative Kafka Management for CLI and Kubernetes" date: 2026-08-24T00:00:00.000Z author: "grzegorz" excerpt: "Monedula GitOps manages Kafka topics, access, quotas, schemas, users, and Confluent RBAC from version-controlled manifests, through either a CLI or a Kubernetes operator." --- Kafka configuration rarely lives in one place. Topics may be created by one script, ACLs by another, schemas by application pipelines, quotas by an administrator, and Confluent RBAC role bindings through yet another tool. Over time, the live cluster becomes the only reliable description of the system - but not an intentional or reviewable one. That is why we created [Monedula GitOps](https://github.com/monedula-dev/monedula-gitops): an open source tool for managing Kafka resources as declarative, version-controlled YAML. The goal is simple: > Describe the desired Kafka state in Git, review it like code, compare it with the live cluster, and converge the cluster toward it. This article introduces the first public release, `v0.1.0`. It focuses on the model and the basic workflow rather than repeating the full documentation. ## Why another Kafka GitOps tool? GitOps gives infrastructure a clear source of truth, review history, repeatable changes, and drift detection. Kafka, however, is not only about topics. A useful management tool also has to understand access rules, consumer groups, quotas, schemas, credentials, and - in Confluent Platform - RBAC role bindings. There is also an adoption problem: most Kafka clusters already exist. Manually recreating their complete state as manifests before adopting GitOps creates a large migration barrier. Monedula GitOps was designed around both problems: * cover the Kafka-specific resources that usually belong together; * make the common case simple, especially a topic and the applications allowed to use it; * support existing clusters through an import workflow; * work both with and without Kubernetes. ## One declarative model, two ways to run it The central design decision is that the CLI and the Kubernetes operator use the same resource model and the same reconciliation engine. In CLI mode, manifests can be validated, compared, applied, and verified from a developer machine or a CI/CD pipeline. In operator mode, the same Kubernetes-style resources are installed as CRDs and continuously reconciled inside a Kubernetes cluster. A `KafkaTopic` used by the CLI can therefore also be applied as a Kubernetes custom resource. Credentials are naturally supplied differently in each runtime - for example, environment or file references for the CLI and Kubernetes Secrets for the operator - but the desired state, drift rules, and execution semantics remain consistent. This lets a team begin with pipeline-driven changes and later adopt the operator without designing a second configuration model. ## A topic and its access in one manifest The resource people work with most often should also be the easiest one to describe. A `KafkaTopic` can contain its partition count, topic configuration, Schema Registry schema, and common producer and consumer access rules: ```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 ``` From this manifest, Monedula GitOps manages the topic and generates the corresponding topic and consumer-group ACLs. Monedula GitOps supports both standard Kafka ACLs and Confluent Platform-specific RBAC role bindings. Common topic-local ACLs can be defined directly in `KafkaTopic`; for advanced cases such as prefixed resources, shared consumer groups, host restrictions, or raw ACL operations, the model includes a separate `KafkaAccessPolicy` resource. Confluent RBAC role bindings are managed with `KafkaRoleBinding`. ## What can it manage? The first release covers the main Kafka and Confluent entities needed for declarative management: * `KafkaCluster` - connection details, authentication, defaults, Schema Registry, and optional Confluent MDS configuration; * `KafkaTopic` - topic lifecycle, partitions, configuration, topic-local access, and schemas; * `KafkaAccessPolicy` - advanced and shared Kafka ACL rules; * `KafkaQuota` - user, client-id, and IP quotas; * `KafkaUser` - Kafka SCRAM credentials; * `KafkaRoleBinding` - Confluent Platform MDS/RBAC role bindings. The CLI also provides validation, drift detection, safe previews, preflight checks, apply, verify, and import commands. ## Installation Install the CLI with Homebrew: ```bash brew install monedula-dev/tap/monedula-gitops ``` Or with Go: ```bash go install github.com/monedula-dev/monedula-gitops/cmd/monedula-gitops@latest ``` Prebuilt binaries are available from the [GitHub releases](https://github.com/monedula-dev/monedula-gitops/releases/latest). A container image is published at `ghcr.io/monedula-dev/monedula-gitops`. Install the Kubernetes operator with Helm: ```bash helm install monedula-gitops \ oci://ghcr.io/monedula-dev/charts/monedula-gitops ``` See the repository for full [CLI configuration](https://github.com/monedula-dev/monedula-gitops/blob/main/docs/cli.md) and [operator installation](https://github.com/monedula-dev/monedula-gitops/blob/main/docs/operator.md). ## Quick start Once you have a `KafkaCluster` configuration and one or more manifests, the basic workflow is small: ```bash # Preview the difference between Git and the live cluster monedula-gitops diff -f ./manifests \ --cluster-config-file ./cluster.yaml # Apply the desired state monedula-gitops apply -f ./manifests \ --cluster-config-file ./cluster.yaml # Confirm that no drift remains monedula-gitops verify -f ./manifests \ --cluster-config-file ./cluster.yaml ``` `verify` returns a non-zero exit code when drift is found, making it suitable as a CI gate. Risky operations are guarded, while deletion and pruning require explicit opt-in. For a complete local environment, the repository includes two runnable [quickstarts](https://github.com/monedula-dev/monedula-gitops/tree/main/quickstart): a CLI playground with Docker Compose, Kafka, and Schema Registry, and an operator playground on a local Kubernetes cluster. ## Start from an existing cluster with Import GitOps tools are easy to demonstrate on an empty cluster. Real environments are rarely empty. The `import cluster` command reads the current Kafka state and generates Monedula manifests from it: ```bash monedula-gitops import cluster \ --cluster-config-file ./cluster.yaml \ --output-dir ./imported ``` The importer reconstructs topics, access rules, quotas, schemas, SCRAM users, and Confluent RBAC role bindings where supported. Simple producer and consumer ACLs are folded into the relevant `KafkaTopic`; advanced or ambiguous rules become standalone resources. Kafka cannot reveal existing SCRAM passwords, so imported users contain placeholder secret references that must be supplied before applying them. The important property is the round trip: verifying the imported directory against the same cluster should report no drift. ```bash monedula-gitops verify -f ./imported -R \ --cluster-config-file ./cluster.yaml ``` Import is therefore not only an export feature. It is an onboarding path for moving an existing Kafka environment toward a Git-managed desired state. ## Examples are part of the project Reference documentation is not always the best way to learn a complicated Kafka configuration. The repository includes a rich [scenarios catalog](https://github.com/monedula-dev/monedula-gitops/tree/main/scenarios) with 25 self-contained configuration sets. They cover topics, inline and advanced access rules, quotas, schemas, drift and reconciliation, pruning, deletion policies, multi-tenancy, Import, SCRAM users, SASL_SSL, mTLS, OAuth, and Confluent MDS/RBAC. Each scenario contains manifests, an explanation, expected results, and cleanup instructions. They can be run as examples, adapted as starting points, or used as inspiration for your own settings. ## This is the first release - please test it `v0.1.0` is the first public release of Monedula GitOps. The tool covers several Kafka APIs, authorization models, authentication methods, and resource lifecycles. It is a fairly complicated piece of software, and some combinations or edge cases may not yet work exactly as expected. Please begin with a disposable or non-production environment, inspect `diff` or `apply --dry-run` output carefully, and enable destructive operations only after reviewing the planned changes. Most importantly, please test it. Different Kafka distributions, security configurations, and operating models are exactly where real-world feedback is valuable. If you find a bug, unclear behavior, or a missing use case, open an [issue on GitHub](https://github.com/monedula-dev/monedula-gitops/issues). ## Summary Monedula GitOps brings Kafka topics, access, quotas, schemas, users, and Confluent RBAC into one declarative model that works through either a CI-friendly CLI or a Kubernetes operator. You can start from an empty cluster, import an existing one, and learn the tool through runnable quickstarts and worked scenarios. The first release is available now on [GitHub](https://github.com/monedula-dev/monedula-gitops).