A configuração do Kafka raramente vive em um só lugar.

Os tópicos são criados por um script, as ACLs por outro, os esquemas pelos pipelines das aplicações, as cotas 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 confiável do sistema - mas não uma descrição intencional nem revisável.

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

O objetivo é simples:

Descreva o estado desejado do Kafka no Git, revise-o como código, compare-o com o cluster em produção e faça o cluster convergir para ele.

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

Por que 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 detecção de drift. O Kafka, porém, não é só tópicos. Uma ferramenta de gerenciamento útil também precisa entender regras de acesso, grupos de consumidores, cotas, 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 projetado em torno 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 executá-lo

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

No 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. No 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 arquivos na CLI e Secrets do Kubernetes no operador - mas o estado desejado, as regras de drift e a semântica de execução se mantêm consistentes.

Assim, uma equipe pode começar com mudanças conduzidas pelo pipeline e adotar o operador mais tarde, sem projetar um segundo modelo de configuração.

Um tópico e o seu acesso em um único manifesto

O recurso com que mais se trabalha deveria 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 gerencia o tópico e gera as ACLs correspondentes de tópico e de grupo de consumidores.

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

O que ele consegue gerenciar?

A primeira versão cobre as principais entidades do Kafka e da Confluent necessárias para um gerenciamento declarativo:

  • KafkaCluster - dados de conexão, autenticação, valores padrã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 compartilhadas;
  • KafkaQuota - cotas por usuário, 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, detecção de drift, pré-visualizações seguras, verificações preflight, aplicação, verificação e importação.

Instalação

Instale 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 contêiner é publicada em ghcr.io/monedula-dev/monedula-gitops.

Instale o operador de Kubernetes com o Helm:

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

Consulte a documentação (em inglês) para ver a configuração completa da CLI e a instalação do operador.

Início rápido

Assim que você tiver 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 retorna 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 são protegidas, e a exclusã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 em um cluster local de Kubernetes.

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

As ferramentas GitOps são fáceis de demonstrar em um 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, cotas, esquemas, usuários SCRAM e, onde há suporte, os role bindings de RBAC da Confluent. As ACLs simples de produtor e consumidor são incorporadas ao KafkaTopic respectivo; as regras avançadas ou ambíguas viram recursos autônomos.

O Kafka não consegue revelar as senhas SCRAM existentes, por isso os usuários importados contêm referências a segredos provisórios (placeholders), que precisam ser preenchidas antes de aplicá-los.

A propriedade importante é a ida e volta: verificar o diretório importado contra o mesmo cluster não deve apontar nenhum 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 gerenciado 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. Eles cobrem tópicos, regras de acesso inline e avançadas, cotas, esquemas, drift e reconciliação, pruning, políticas de exclusão, multi-tenancy, Import, usuários 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. Eles podem ser executados como exemplos, adaptados como pontos de partida ou usados como inspiração para as suas próprias definições.

Esta é a primeira versão - teste-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.

Comece por um ambiente descartável ou não produtivo, inspecione com atenção a saída de diff ou de apply --dry-run e ative as operações destrutivas só depois de revisar as mudanças planejadas.

Acima de tudo, teste-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 você encontrar um bug, um comportamento pouco claro ou um caso de uso que esteja faltando, abra uma issue no GitHub.

Resumo

O Monedula GitOps traz tópicos Kafka, acessos, cotas, esquemas, usuários 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. Você pode começar com um cluster vazio, importar um já existente e aprender a ferramenta com quickstarts executáveis e cenários comentados.

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

A ferramenta: monedula-gitops tem o modelo de recursos, os passos de instalação e o repositório.