---
title: "monedula-gitops"
repo: https://github.com/monedula-dev/monedula-gitops
language: Go
license: AGPL-3.0
status: active
maintainers: ["grzegorz", "michal"]
---> **Articolo di accompagnamento:** [Monedula GitOps: gestione dichiarativa di Kafka per CLI e Kubernetes](/blog/monedula-gitops/) presenta la release `v0.1.0`, il modello di risorse e il flusso di lavoro di base.

## Perché

La configurazione di Kafka vive raramente in un unico posto. I topic arrivano
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.

`monedula-gitops` rende esplicita quella descrizione: descrivi lo stato Kafka
desiderato in Git, rivedilo come codice, confrontalo con il cluster in
esecuzione e fai convergere il cluster verso di esso.

Kafka non è solo topic, quindi il modello copre le risorse che di solito
stanno insieme: regole di accesso, consumer group, quote, schemi, credenziali
e, su Confluent Platform, i role binding RBAC.

## Un modello, due runtime

La CLI e l'operator Kubernetes usano lo stesso modello di risorse e lo stesso
motore di riconciliazione.

- **CLI** — valida, confronta, applica e verifica i manifest da una macchina
  di sviluppo o da una pipeline CI/CD. `verify` restituisce un exit code
  diverso da zero quando trova drift, quindi funziona come gate di CI.
- **Operator** — installa le stesse risorse in stile Kubernetes come CRD e le
  riconcilia di continuo dentro un cluster.

Le credenziali vengono fornite in modo diverso nei due runtime — riferimenti a
variabili d'ambiente o a file per la CLI, Secret di Kubernetes per l'operator
— ma lo stato desiderato, le regole di drift e la semantica di esecuzione
restano coerenti. Un team può iniziare con cambiamenti guidati dalla pipeline
e adottare l'operator più avanti, senza progettare un secondo modello di
configurazione.

## Che cosa gestisce

`KafkaCluster` (connessione, autenticazione, valori predefiniti, Schema
Registry, Confluent MDS opzionale), `KafkaTopic` (ciclo di vita, partizioni,
configurazione, accesso locale al topic, schemi), `KafkaAccessPolicy` (regole
ACL avanzate e condivise), `KafkaQuota` (quote per utente, client-id e IP),
`KafkaUser` (credenziali SCRAM) e `KafkaRoleBinding` (MDS/RBAC di Confluent).

Il caso comune resta piccolo: un topic e le applicazioni autorizzate a usarlo
stanno in un solo manifest, da cui vengono generate le corrispondenti ACL di
topic e di consumer group:

```yaml
apiVersion: gitops.monedula.dev/v1alpha1
kind: KafkaTopic
metadata:
  name: orders
spec:
  clusterRef:
    name: prod
  topicName: orders
  partitions: 6
  access:
    producers:
      - principal: User:svc-checkout
    consumers:
      - principal: User:svc-fraud
        group: fraud-orders
```

## Installazione

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

Disponibile anche via `go install`, come binari precompilati nelle release su
GitHub e come immagine container su `ghcr.io/monedula-dev/monedula-gitops`.
L'operator si installa con Helm da
`oci://ghcr.io/monedula-dev/charts/monedula-gitops`.

## Partire da un cluster esistente

Gli ambienti reali sono raramente vuoti, così `import cluster` legge lo stato
attuale di Kafka e ne genera i manifest — topic, regole di accesso, quote,
schemi, utenti SCRAM e, dove supportati, i role binding RBAC di Confluent. Il
punto è il round trip: verificare la directory importata contro lo stesso
cluster non dovrebbe segnalare alcun drift.

Le operazioni rischiose sono protette, mentre cancellazione e pruning
richiedono un consenso esplicito. Nel repository ci sono due quickstart
eseguibili (un playground CLI su Docker Compose e un playground per l'operator
su Kubernetes locale) e un catalogo di 25 scenari autonomi.