Monedula GitOps :
la gestion déclarative de Kafka pour la CLI et Kubernetes

La configuration de Kafka vit rarement au même endroit.

Les topics sont créés par un script, les ACL par un autre, les schémas par les pipelines applicatifs, les quotas par l’administration et les role bindings RBAC de Confluent par un outil encore différent. Avec le temps, le cluster en production devient la seule description fiable du système — mais une description ni intentionnelle ni relisible.

C’est pourquoi nous avons créé Monedula GitOps : un outil open source pour gérer les ressources Kafka sous forme de YAML déclaratif et versionné.

L’objectif est simple :

Décrire l’état Kafka souhaité dans Git, le relire comme du code, le comparer au cluster en production et faire converger le cluster vers lui.

Cet article présente la première version publique, v0.1.0. Il se concentre sur le modèle et le flux de travail de base plutôt que de répéter toute la documentation.

Pourquoi encore un outil GitOps pour Kafka ?

GitOps donne à l’infrastructure une source de vérité claire, un historique de revue, des changements reproductibles et une détection de drift. Mais Kafka, ce n’est pas seulement des topics. Un outil de gestion utile doit aussi comprendre les règles d’accès, les groupes de consommateurs, les quotas, les schémas, les identifiants et — dans Confluent Platform — les role bindings RBAC.

Il y a en plus un problème d’adoption : la plupart des clusters Kafka existent déjà. Recréer à la main l’intégralité de leur état sous forme de manifestes avant d’adopter GitOps crée une barrière de migration considérable.

Monedula GitOps a été conçu autour de ces deux problèmes :

• couvrir les ressources propres à Kafka qui vont généralement ensemble ;
• rendre simple le cas courant, en particulier un topic et les applications autorisées à l’utiliser ;
• prendre en charge les clusters existants grâce à un flux d’import ;
• fonctionner avec ou sans Kubernetes.

Un modèle déclaratif, deux façons de l’exécuter

La décision de conception centrale : la CLI et l’opérateur Kubernetes utilisent le même modèle de ressources et le même moteur de réconciliation.

En mode CLI, les manifestes peuvent être validés, comparés, appliqués et vérifiés depuis un poste de développement ou un pipeline CI/CD. En mode opérateur, ces mêmes ressources de style Kubernetes sont installées en tant que CRD et réconciliées en continu à l’intérieur d’un cluster Kubernetes.

Un KafkaTopic utilisé par la CLI peut donc aussi être appliqué comme ressource personnalisée Kubernetes. Les identifiants sont naturellement fournis différemment dans chaque runtime — par exemple des références d’environnement ou de fichiers pour la CLI et des Secrets Kubernetes pour l’opérateur — mais l’état souhaité, les règles de drift et la sémantique d’exécution restent cohérents.

Une équipe peut ainsi commencer par des changements pilotés par le pipeline, puis adopter l’opérateur sans concevoir un second modèle de configuration.

Un topic et ses accès dans un seul manifeste

La ressource que l’on manipule le plus souvent devrait aussi être la plus facile à décrire.

Un KafkaTopic peut contenir son nombre de partitions, sa configuration de topic, son schéma Schema Registry et les règles d’accès habituelles des producteurs et des consommateurs :

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

À partir de ce manifeste, Monedula GitOps gère le topic et génère les ACL de topic et de groupe de consommateurs correspondantes.

Monedula GitOps prend en charge à la fois les ACL Kafka standard et les role bindings RBAC propres à Confluent Platform. Les ACL locales au topic les plus courantes se définissent directement dans KafkaTopic ; pour les cas avancés — ressources préfixées, groupes de consommateurs partagés, restrictions d’hôte ou opérations ACL brutes — le modèle inclut une ressource distincte, KafkaAccessPolicy. Les role bindings RBAC de Confluent se gèrent avec KafkaRoleBinding.

Que peut-il gérer ?

La première version couvre les principales entités Kafka et Confluent nécessaires à une gestion déclarative :

• KafkaCluster — détails de connexion, authentification, valeurs par défaut, Schema Registry et configuration Confluent MDS optionnelle ;
• KafkaTopic — cycle de vie du topic, partitions, configuration, accès local au topic et schémas ;
• KafkaAccessPolicy — règles ACL Kafka avancées et partagées ;
• KafkaQuota — quotas par utilisateur, client-id et IP ;
• KafkaUser — identifiants SCRAM Kafka ;
• KafkaRoleBinding — role bindings MDS/RBAC de Confluent Platform.

La CLI fournit également des commandes de validation, de détection de drift, d’aperçu sûr, de vérifications préalables, d’application, de vérification et d’import.

Installation

Installer la CLI avec Homebrew :

brew install monedula-dev/tap/monedula-gitops

Ou avec Go :

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

Des binaires précompilés sont disponibles dans les releases GitHub. Une image de conteneur est publiée sur ghcr.io/monedula-dev/monedula-gitops.

Installer l’opérateur Kubernetes avec Helm :

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

Voir le dépôt pour la configuration complète de la CLI et l’installation de l’opérateur.

Démarrage rapide

Une fois que vous disposez d’une configuration KafkaCluster et d’un ou plusieurs manifestes, le flux de base tient en peu de chose :

# Prévisualiser l'écart entre Git et le cluster en production
monedula-gitops diff -f ./manifests \
  --cluster-config-file ./cluster.yaml

# Appliquer l'état souhaité
monedula-gitops apply -f ./manifests \
  --cluster-config-file ./cluster.yaml

# Confirmer qu'il ne reste aucun drift
monedula-gitops verify -f ./manifests \
  --cluster-config-file ./cluster.yaml

verify renvoie un code de sortie non nul lorsqu’un drift est détecté, ce qui en fait un bon garde-fou de CI. Les opérations risquées sont protégées, tandis que la suppression et le pruning exigent une activation explicite.

Pour un environnement local complet, le dépôt inclut deux quickstarts exécutables : un terrain de jeu CLI avec Docker Compose, Kafka et Schema Registry, et un terrain de jeu opérateur sur un cluster Kubernetes local.

Partir d’un cluster existant avec Import

Les outils GitOps se démontrent facilement sur un cluster vide. Les environnements réels le sont rarement.

La commande import cluster lit l’état Kafka actuel et en génère des manifestes Monedula :

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

L’importeur reconstitue les topics, les règles d’accès, les quotas, les schémas, les utilisateurs SCRAM et, là où c’est pris en charge, les role bindings RBAC de Confluent. Les ACL simples de producteur et de consommateur sont repliées dans le KafkaTopic concerné ; les règles avancées ou ambiguës deviennent des ressources autonomes.

Kafka ne peut pas révéler les mots de passe SCRAM existants : les utilisateurs importés contiennent donc des références de secrets fictives, à renseigner avant de les appliquer.

La propriété importante, c’est l’aller-retour : vérifier le répertoire importé face au même cluster ne devrait signaler aucun drift.

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

Import n’est donc pas qu’une fonction d’export. C’est un chemin d’adoption pour faire évoluer un environnement Kafka existant vers un état souhaité géré dans Git.

Les exemples font partie du projet

La documentation de référence n’est pas toujours la meilleure façon d’apprendre une configuration Kafka compliquée.

Le dépôt inclut un riche catalogue de scénarios comptant 25 jeux de configuration autonomes. Ils couvrent les topics, les règles d’accès inline et avancées, les quotas, les schémas, le drift et la réconciliation, le pruning, les politiques de suppression, la multi-location, l’import, les utilisateurs SCRAM, SASL_SSL, mTLS, OAuth et le MDS/RBAC de Confluent.

Chaque scénario contient des manifestes, une explication, les résultats attendus et des instructions de nettoyage. On peut les exécuter comme exemples, les adapter comme points de départ ou s’en inspirer pour ses propres réglages.

C’est la première version — merci de la tester

v0.1.0 est la première version publique de Monedula GitOps.

L’outil couvre plusieurs API Kafka, modèles d’autorisation, méthodes d’authentification et cycles de vie de ressources. C’est un logiciel assez compliqué, et certaines combinaisons ou certains cas limites peuvent ne pas encore se comporter exactement comme prévu.

Commencez par un environnement jetable ou hors production, examinez attentivement la sortie de diff ou d’apply --dry-run, et n’activez les opérations destructrices qu’après avoir relu les changements planifiés.

Surtout, testez-la. Les différentes distributions Kafka, configurations de sécurité et modèles d’exploitation sont précisément là où les retours du terrain ont de la valeur. Si vous trouvez un bug, un comportement flou ou un cas d’usage manquant, ouvrez une issue sur GitHub.

Résumé

Monedula GitOps réunit les topics Kafka, les accès, les quotas, les schémas, les utilisateurs et le RBAC Confluent dans un seul modèle déclaratif, utilisable via une CLI adaptée à la CI ou via un opérateur Kubernetes. Vous pouvez partir d’un cluster vide, en importer un existant et apprendre l’outil grâce à des quickstarts exécutables et des scénarios détaillés.

La première version est disponible dès maintenant sur GitHub.