A configuração do Kafka raramente vive num só sítio.

Os tópicos são criados por um script, as ACL por outro, os esquemas pelos pipelines das aplicações, as quotas por quem administra o sistema e os role bindings de RBAC da Confluent por 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.

Foi por isso que criámos o Monedula GitOps: uma ferramenta de código aberto para gerir recursos do Kafka como YAML declarativo e versionado.

O objetivo é simples:

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.

Este artigo apresenta a primeira versão pública, v0.1.0. Concentra-se no modelo e no fluxo de trabalho básico, em vez de repetir a documentação completa.

Porquê mais uma ferramenta GitOps para Kafka?

O GitOps dá à infraestrutura uma fonte de verdade clara, histórico de revisão, mudanças repetíveis e deteção de drift. O Kafka, porém, não é só tópicos. Uma ferramenta de gestão útil tem também de perceber regras de acesso, grupos de consumidores, quotas, esquemas, credenciais e — na Confluent Platform — role bindings de RBAC.

Há ainda um problema de adoção: a maioria dos clusters Kafka já existe. Recriar à mão o seu estado completo em manifestos antes de adotar GitOps cria uma enorme barreira de migração.

O Monedula GitOps foi desenhado à volta destes dois problemas:

  • cobrir os recursos específicos do Kafka que costumam andar juntos;
  • tornar simples o caso comum, sobretudo um tópico e as aplicações autorizadas a usá-lo;
  • suportar clusters existentes através de um fluxo de importação;
  • funcionar com e sem Kubernetes.

Um modelo declarativo, duas formas de o executar

A decisão de desenho central é que a CLI e o operador de Kubernetes usam o mesmo modelo de recursos e o mesmo motor de reconciliação.

Em modo CLI, os manifestos podem ser validados, comparados, aplicados e verificados a partir de uma máquina de desenvolvimento ou de um pipeline de CI/CD. Em modo operador, esses mesmos recursos ao estilo Kubernetes são instalados como CRD e reconciliados continuamente dentro de um cluster de Kubernetes.

Um KafkaTopic usado pela CLI pode, por isso, ser aplicado também como recurso personalizado do Kubernetes. As credenciais são naturalmente fornecidas de maneira diferente em cada runtime — por exemplo, referências a variáveis de ambiente ou a ficheiros na CLI e Secrets do Kubernetes no operador — mas o estado desejado, as regras de drift e a semântica de execução mantêm-se consistentes.

Assim, 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.

Um tópico e o seu acesso num único manifesto

O recurso com que mais se trabalha devia ser também o mais fácil de descrever.

Um KafkaTopic pode conter o número de partições, a configuração do tópico, o esquema do Schema Registry e as regras de acesso habituais de produtores e consumidores:

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

A partir deste manifesto, o Monedula GitOps gere o tópico e gera as ACL correspondentes de tópico e de grupo de consumidores.

O Monedula GitOps suporta tanto as ACL padrão do Kafka como os role bindings de RBAC específicos da Confluent Platform. As ACL locais ao tópico mais comuns podem ser definidas diretamente em KafkaTopic; para casos avançados — recursos com prefixo, grupos de consumidores partilhados, restrições de host ou operações ACL em bruto — o modelo inclui um recurso separado, KafkaAccessPolicy. Os role bindings de RBAC da Confluent são geridos com KafkaRoleBinding.

O que consegue gerir?

A primeira versão cobre as principais entidades do Kafka e da Confluent necessárias a uma gestão declarativa:

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

A CLI oferece ainda comandos de validação, deteção de drift, pré-visualizações seguras, verificações preflight, aplicação, verificação e importação.

Instalação

Instala a CLI com o Homebrew:

brew install monedula-dev/tap/monedula-gitops

Ou com Go:

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

Há binários pré-compilados nas releases do GitHub. A imagem de contentor é publicada em ghcr.io/monedula-dev/monedula-gitops.

Instala o operador de Kubernetes com o Helm:

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

Consulta o repositório para a configuração completa da CLI e a instalação do operador.

Arranque rápido

Assim que tiveres uma configuração de KafkaCluster e um ou mais manifestos, o fluxo básico é curto:

# Pré-visualiza a diferença entre o Git e o cluster em produção
monedula-gitops diff -f ./manifests \
  --cluster-config-file ./cluster.yaml

# Aplica o estado desejado
monedula-gitops apply -f ./manifests \
  --cluster-config-file ./cluster.yaml

# Confirma que não sobra qualquer drift
monedula-gitops verify -f ./manifests \
  --cluster-config-file ./cluster.yaml

O verify devolve um código de saída diferente de zero quando encontra drift, o que o torna adequado como gate de CI. As operações arriscadas estão protegidas, e a eliminação e o pruning exigem ativação explícita.

Para um ambiente local completo, o repositório inclui dois quickstarts executáveis: um playground de CLI com Docker Compose, Kafka e Schema Registry, e um playground do operador num cluster local de Kubernetes.

Começar a partir de um cluster existente com o Import

As ferramentas GitOps são fáceis de demonstrar num cluster vazio. Os ambientes reais raramente o são.

O comando import cluster lê o estado atual do Kafka e gera manifestos Monedula a partir dele:

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

O importador reconstrói tópicos, regras de acesso, quotas, esquemas, utilizadores SCRAM e, onde há suporte, os role bindings de RBAC da Confluent. As ACL simples de produtor e consumidor são dobradas no KafkaTopic respetivo; as regras avançadas ou ambíguas passam a recursos autónomos.

O Kafka não consegue revelar as palavras-passe SCRAM existentes, por isso os utilizadores importados contêm referências a segredos de marcador de posição, que têm de ser preenchidas antes de os aplicar.

A propriedade importante é a ida e volta: verificar a diretoria importada contra o mesmo cluster não deve reportar qualquer drift.

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

O Import não é, portanto, apenas uma funcionalidade de exportação. É um caminho de adoção para levar um ambiente Kafka existente na direção de um estado desejado gerido a partir do Git.

Os exemplos fazem parte do projeto

A documentação de referência nem sempre é a melhor forma de aprender uma configuração complicada do Kafka.

O repositório inclui um rico catálogo de cenários com 25 conjuntos de configuração autónomos. Cobrem tópicos, regras de acesso inline e avançadas, quotas, esquemas, drift e reconciliação, pruning, políticas de eliminação, multi-tenancy, Import, utilizadores SCRAM, SASL_SSL, mTLS, OAuth e MDS/RBAC da Confluent.

Cada cenário contém manifestos, uma explicação, os resultados esperados e instruções de limpeza. Podem ser executados como exemplos, adaptados como pontos de partida ou usados como inspiração para as tuas próprias definições.

Esta é a primeira versão — testa-a, por favor

A v0.1.0 é a primeira versão pública do Monedula GitOps.

A ferramenta cobre várias APIs do Kafka, modelos de autorização, métodos de autenticação e ciclos de vida de recursos. É um software bastante complicado, e algumas combinações ou casos-limite podem ainda não funcionar exatamente como se espera.

Começa por um ambiente descartável ou não produtivo, inspeciona com atenção a saída de diff ou de apply --dry-run e ativa as operações destrutivas só depois de reveres as mudanças planeadas.

Acima de tudo, testa-a. Diferentes distribuições do Kafka, configurações de segurança e modelos operacionais são precisamente onde o feedback do mundo real tem valor. Se encontrares um bug, um comportamento pouco claro ou um caso de uso em falta, abre uma issue no GitHub.

Resumo

O Monedula GitOps traz tópicos Kafka, acessos, quotas, esquemas, utilizadores e RBAC da Confluent para um único modelo declarativo, que funciona através de uma CLI amiga da CI ou de um operador de Kubernetes. Podes começar com um cluster vazio, importar um já existente e aprender a ferramenta com quickstarts executáveis e cenários trabalhados.

A primeira versão já está disponível no GitHub.