---
title: "monedula-gitops"
repo: https://github.com/monedula-dev/monedula-gitops
language: Go
license: AGPL-3.0
status: active
maintainers: ["grzegorz", "michal"]
---> **Post complementar:** [Monedula GitOps: gestão declarativa do Kafka para CLI e Kubernetes](/blog/monedula-gitops/) apresenta a versão `v0.1.0`, o modelo de recursos e o fluxo de trabalho básico.

## Porquê

A configuração do Kafka raramente vive num só sítio. Os tópicos vêm de um
script, as ACL de outro, os esquemas dos pipelines das aplicações, as quotas
de quem administra o sistema e os role bindings de RBAC da Confluent de mais
outra ferramenta. Com o tempo, o cluster em produção passa a ser a única
descrição fiável do sistema — mas não uma descrição intencional nem revisível.

O `monedula-gitops` torna essa descrição explícita: descreve o estado desejado
do Kafka no Git, revê-o como código, compara-o com o cluster em produção e faz
o cluster convergir para ele.

O Kafka não é só tópicos, por isso o modelo cobre os recursos que costumam
andar juntos: regras de acesso, grupos de consumidores, quotas, esquemas,
credenciais e, na Confluent Platform, role bindings de RBAC.

## Um modelo, dois runtimes

A CLI e o operador de Kubernetes usam o mesmo modelo de recursos e o mesmo
motor de reconciliação.

- **CLI** — valida, compara, aplica e verifica manifestos a partir de uma
  máquina de desenvolvimento ou de um pipeline de CI/CD. O `verify` devolve um
  código de saída diferente de zero quando encontra drift, por isso serve de
  gate de CI.
- **Operador** — instala esses mesmos recursos ao estilo Kubernetes como CRD e
  reconcilia-os continuamente dentro de um cluster.

As credenciais são fornecidas de maneira diferente em cada runtime —
referências a variáveis de ambiente ou a ficheiros na CLI, Secrets do
Kubernetes no operador — mas o estado desejado, as regras de drift e a
semântica de execução mantêm-se consistentes. Uma equipa pode começar com
mudanças conduzidas pelo pipeline e adotar o operador mais tarde, sem desenhar
um segundo modelo de configuração.

## O que gere

`KafkaCluster` (ligação, autenticação, valores por omissão, Schema Registry,
Confluent MDS opcional), `KafkaTopic` (ciclo de vida, partições, configuração,
acesso local ao tópico, esquemas), `KafkaAccessPolicy` (regras ACL avançadas e
partilhadas), `KafkaQuota` (quotas por utilizador, client-id e IP),
`KafkaUser` (credenciais SCRAM) e `KafkaRoleBinding` (MDS/RBAC da Confluent).

O caso comum continua pequeno: um tópico e as aplicações autorizadas a usá-lo
cabem num único manifesto, e daí são geradas as ACL correspondentes de tópico
e de grupo de consumidores:

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

## Instalação

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

Também disponível via `go install`, como binários pré-compilados nas releases
do GitHub e como imagem de contentor em
`ghcr.io/monedula-dev/monedula-gitops`. O operador instala-se com Helm a
partir de `oci://ghcr.io/monedula-dev/charts/monedula-gitops`.

## Começar a partir de um cluster existente

Os ambientes reais raramente estão vazios, por isso o `import cluster` lê o
estado atual do Kafka e gera manifestos a partir dele — tópicos, regras de
acesso, quotas, esquemas, utilizadores SCRAM e, onde há suporte, os role
bindings de RBAC da Confluent. O que interessa é a ida e volta: verificar a
diretoria importada contra o mesmo cluster não deve reportar qualquer drift.

As operações arriscadas estão protegidas, e a eliminação e o pruning exigem
ativação explícita. O repositório inclui dois quickstarts executáveis (um
playground de CLI com Docker Compose e um playground do operador em Kubernetes
local) e um catálogo de 25 cenários autónomos.