De ACLs do Kafka ao RBAC do Confluent: um caminho de migração seguro com uma nova ferramenta open-source

Quando trabalhamos com bancos e grandes empresas, o Kafka raramente é um tema greenfield.

Com mais frequência, o Kafka já está em execução há anos. As equipes dependem dele, dados críticos fluem por ele e a plataforma acumulou um longo histórico de decisões operacionais, convenções de nomenclatura, contas de serviço, padrões de topic e regras de acesso. Quando uma organização decide migrar para o Confluent Platform, o Kafka já não é mais apenas um sistema de mensageria. Ele faz parte da espinha dorsal da produção.

Esse contexto importa, porque migrações nesse tipo de ambiente não são apenas projetos técnicos. São exercícios de gestão de riscos.

Na primeira fase de uma migração para o Confluent, a abordagem mais segura costuma ser mudar o mínimo possível. O objetivo é migrar a base da plataforma, estabilizá-la e só então introduzir melhorias maiores. Autenticação e autorização fazem parte dessa história. Instalações Kafka existentes frequentemente dependem de ACLs do Apache Kafka, porque as ACLs são o modelo de autorização nativo disponível no Kafka open-source.

O Confluent Platform, porém, também oferece RBAC: controle de acesso baseado em papéis. O RBAC normalmente é mais fácil de raciocinar em escala organizacional, se encaixa melhor na governança da plataforma e integra-se naturalmente com outros componentes do Confluent, como o Metadata Service, o Control Center e o Confluent for Kubernetes.

A pergunta, então, passa a ser: como migrar de um ambiente Kafka baseado em ACLs para o RBAC do Confluent sem transformar o controle de acesso em uma migração manual de alto risco?

É exatamente para isso que criamos o monedula-acl-rbac-converter.

Por que a migração de ACL para RBAC é mais difícil do que parece

Um cluster Kafka pequeno, com um punhado de topics e usuários, pode ser migrado manualmente. Você inspeciona as ACLs, decide os papéis RBAC equivalentes, cria os bindings, verifica o acesso e remove as ACLs antigas.

Mas não é assim que a maioria dos ambientes corporativos maduros se parece.

Em implantações reais, você pode encontrar centenas ou milhares de regras de ACL. Algumas foram criadas por equipes de plataforma. Outras por equipes de aplicação. Algumas vieram de automação. Algumas são antigas, mas ainda em uso. Algumas usam padrões de topic com prefixo. Algumas referenciam usuários de serviço que foram renomeados desde então. Algumas foram exportadas de scripts em que ninguém toca há anos.

A migração manual nesse contexto tem vários problemas:

é lenta,
é propensa a erros,
é difícil de revisar,
é difícil de repetir,
é difícil de auditar,
e torna-se perigosa quando a limpeza começa.

Criar novos bindings RBAC é apenas metade da migração. A parte mais delicada é provar que os novos bindings fornecem o mesmo acesso efetivo que as ACLs antigas e, só então, remover as ACLs de origem.

Por isso não queríamos uma ferramenta que simplesmente “traduzisse um arquivo”. Queríamos um fluxo de migração.

O que o conversor faz

O monedula-acl-rbac-converter é uma ferramenta de linha de comando que lê ACLs existentes do Kafka, converte-as em um plano de role bindings RBAC do Confluent e ajuda os operadores a executar a migração de forma controlada e auditável.

Ele pode ler ACLs de várias fontes do mundo real, incluindo:

um cluster Kafka ao vivo,
a saída exportada de kafka-acls.sh --list,
dumps em JSON, YAML ou CSV,
manifests KafkaUser do Strimzi,
manifests do Confluent for Kubernetes,
um cluster Kubernetes em execução,
ou um shell script contendo comandos kafka-acls --add ....

Este último caso é particularmente útil em ambientes brownfield. Muitas equipes não partem de uma exportação limpa. Em vez disso, têm um antigo script de setup que criou as ACLs em primeiro lugar.

Por exemplo, um script de entrada pode conter comandos como:

kafka-acls.sh \
  --bootstrap-server kafka.example.com:9093 \
  --command-config admin.properties \
  --add \
  --allow-principal User:svc-billing \
  --operation Read \
  --topic billing.events \
  --group billing-consumer

kafka-acls.sh \
  --bootstrap-server kafka.example.com:9093 \
  --command-config admin.properties \
  --add \
  --allow-principal User:svc-billing \
  --operation Describe \
  --topic billing.events

O conversor consegue extrair essas definições de ACL para um arquivo acls.json canônico. A partir daí, ele pode produzir um plano de migração revisado, emitir scripts ou manifests, aplicar bindings diretamente ao MDS do Confluent, verificar o resultado e gerar scripts de limpeza para as ACLs antigas.

Um fluxo projetado para mudanças de alto risco

Migrações de controle de acesso precisam de salvaguardas. Uma permissão errada pode quebrar cargas de trabalho em produção. Uma permissão ampla demais pode criar um incidente de segurança. Uma etapa de limpeza realizada cedo demais pode causar uma indisponibilidade.

Por essa razão, o fluxo de produção é explícito e baseado em etapas:

1. extract       -> criar um snapshot ACL canônico
2. plan          -> converter ACLs em um plano de migração RBAC
3. apply dry-run -> pré-visualizar alterações no MDS
4. apply         -> criar vinculações de função RBAC
5. verify        -> verificar acesso efetivo
6. wait          -> permitir que usuários exercitem o novo caminho
7. delete-acls   -> gerar script de exclusão para ACLs antigas
8. review + run  -> executar limpeza manualmente

Cada etapa cria artefatos que podem ser inspecionados, revisados, versionados ou anexados a uma solicitação de mudança.

A ferramenta separa intencionalmente o planejamento da aplicação, a aplicação da verificação e a verificação da exclusão. Isso torna a migração mais fácil de raciocinar e mais segura de executar em ambientes regulados.

Exemplo: migrando a partir de um script de setup de ACLs

Vamos supor que o ponto de partida seja um shell script com comandos kafka-acls.sh --add.

1. Extrair as ACLs

Primeiro, extraia as ACLs para uma representação JSON canônica:

monedula-acl-rbac extract \
  --from script \
  --input setup-acls.sh \
  --vars vars.yaml \
  --out runs/billing-batch-1/acls.json

O arquivo opcional vars.yaml é útil quando o script contém variáveis. A ferramenta não adivinha valores não resolvidos. Se houver variáveis, elas devem ser fornecidas explicitamente, ou o script deve ser pré-expandido antes da migração.

Nesta etapa, a saída ainda é apenas um snapshot. Nenhum estado externo é alterado.

2. Criar um plano de migração

Em seguida, converta as ACLs extraídas em um plano de role bindings:

monedula-acl-rbac plan \
  --acls runs/billing-batch-1/acls.json \
  --scopes scopes.yaml \
  --rules rules.yaml \
  --principals principals.yaml \
  --out runs/billing-batch-1/plan.json

O arquivo scopes.yaml identifica os clusters Confluent que os bindings RBAC devem alvejar. Os arquivos opcionais rules.yaml e principals.yaml permitem que os operadores adaptem a conversão ao seu ambiente, por exemplo mapeando os principals de origem para o formato de principal esperado pelo MDS.

A etapa de planejamento também gera um relatório. Este é um dos pontos de revisão mais importantes do fluxo. Ele mostra no que cada ACL de origem se transformou e sinaliza qualquer coisa que não pôde ser mapeada ou que não deveria ser convertida automaticamente.

3. Ler o relatório

Antes de qualquer coisa ser aplicada, os operadores devem ler o relatório gerado.

É aqui que o trabalho de migração se torna visível. Em vez de depender de uma conversão caixa-preta, a equipe pode revisar os bindings gerados, investigar ACLs não mapeadas e decidir se são necessárias regras de mapeamento personalizadas.

ACLs do tipo DENY merecem atenção especial. O RBAC do Confluent não tem semântica de negação equivalente, portanto as ACLs DENY não são convertidas silenciosamente. Elas são reportadas e tratadas separadamente.

4. Fazer um dry-run da etapa de aplicação

Antes de criar role bindings no MDS, execute um dry-run:

monedula-acl-rbac apply \
  --plan runs/billing-batch-1/plan.json \
  --mds-url https://mds.example.com \
  --mds-token-file ~/.confluent/token \
  --dry-run

O dry-run prevê as chamadas ao MDS que seriam feitas. Ele também realiza verificações de leitura para que bindings existentes possam ser ignorados de forma idempotente.

Isso dá aos operadores mais um checkpoint antes da primeira mudança real.

5. Aplicar os bindings RBAC

Uma vez revisada a saída do dry-run, aplique o plano:

monedula-acl-rbac apply \
  --plan runs/billing-batch-1/plan.json \
  --mds-url https://mds.example.com \
  --mds-token-file ~/.confluent/token \
  --confirm

A etapa de aplicação cria os bindings RBAC no MDS do Confluent. Ela foi projetada para ser reexecutável: se um binding já existe, ele é ignorado.

6. Verificar o acesso efetivo

Após aplicar os bindings RBAC, verifique se eles realmente concedem o acesso originalmente fornecido pelas ACLs:

monedula-acl-rbac verify \
  --plan runs/billing-batch-1/plan.json \
  --mds-url https://mds.example.com \
  --mds-token-file ~/.confluent/token

Isso é mais robusto do que verificar se um binding existe. O objetivo é confirmar o acesso efetivo para o principal, a operação e o recurso originais.

Essa distinção importa em ambientes corporativos onde a propagação de identidade, a participação em grupos, a integração com LDAP ou incompatibilidades de escopo podem fazer com que um binding exista, mas não se comporte como esperado.

7. Gerar scripts de exclusão de ACLs

Somente após uma verificação bem-sucedida, e após um período de espera definido pelo operador, as ACLs de origem devem ser removidas.

A ferramenta não exclui ACLs diretamente. Em vez disso, ela gera um script que os operadores inspecionam e executam por conta própria:

monedula-acl-rbac delete-acls \
  --plan runs/billing-batch-1/plan.json \
  --verify runs/billing-batch-1/verify.json \
  --bootstrap-server kafka.example.com:9093 \
  --command-config admin.properties \
  --principal User:svc-billing \
  --confirm \
  --i-understand-this-is-destructive

Os artefatos gerados incluem:

delete-acls.sh
deleted-acls.json
rollback.sh

Este é um checkpoint humano deliberado. O operador pode abrir o script, revisar cada comando kafka-acls --remove, executá-lo para um principal de cada vez e manter o script de rollback até que a migração esteja estável.

Saídas diferentes para modelos operacionais diferentes

Nem toda organização quer o mesmo modelo de aplicação.

Algumas equipes se sentem confortáveis aplicando diretamente ao MDS. Outras precisam que cada mudança passe por um processo de controle de mudanças, um fluxo GitOps ou um pipeline externo de CD.

O conversor suporta esses cenários ao emitir diferentes tipos de artefato:

# Script de shell com comandos de vinculação de função do Confluent CLI
monedula-acl-rbac emit \
  --plan runs/billing-batch-1/plan.json \
  --format script \
  --out-dir emit/

# Manifestos do Confluent for Kubernetes
monedula-acl-rbac emit \
  --plan runs/billing-batch-1/plan.json \
  --format cfk \
  --out-dir emit/

# Comandos curl contra MDS REST API
monedula-acl-rbac emit \
  --plan runs/billing-batch-1/plan.json \
  --format mds-curl \
  --out-dir emit/

Isso torna a ferramenta útil tanto para o trabalho de migração prático quanto para ambientes onde as mudanças de infraestrutura precisam passar por um sistema separado de aprovação e implantação.

Feito para a bagunça real da migração

Tentamos dar suporte aos tipos de entrada e restrições que aparecem em ambientes Kafka reais, não apenas a casos de demonstração limpos.

Isso inclui:

extração de Kafka ao vivo,
exportações em texto,
arquivos estruturados,
recursos nativos do Kubernetes,
manifests existentes do Confluent for Kubernetes,
scripts de setup antigos,
remapeamento de principals,
regras de conversão personalizadas,
execução em dry-run,
aplicação direta ao MDS,
scripts e manifests emitidos,
verificação de acesso efetivo,
geração de scripts de exclusão,
artefatos de rollback,
e comandos de status/diff para lotes de migração repetíveis.

O resultado é uma ferramenta que pode ser usada tanto para exploração quanto para migrações de nível de produção.

Para pequenos experimentos, o comando único convert pode executar extração, planejamento e emissão de script em uma única etapa:

monedula-acl-rbac convert \
  --from yaml \
  --input acls.yaml \
  --scopes scopes.yaml \
  --rules rules.yaml \
  --principals principals.yaml \
  > bindings.sh

Para produção, o pipeline explícito é o caminho recomendado, pois preserva os artefatos de auditoria e os pontos de revisão.

Considerações finais

Migrar de ACLs do Kafka para o RBAC do Confluent não é apenas um problema de conversão de sintaxe.

É uma mudança controlada no modelo de autorização de uma plataforma de dados em execução. Em grandes organizações, especialmente no setor bancário e em indústrias reguladas, essa mudança precisa ser revisável, repetível, auditável e reversível sempre que possível.

Criamos o monedula-acl-rbac-converter porque continuávamos vendo o mesmo padrão: o Kafka já estava lá, as ACLs já estavam lá, e as equipes queriam adotar o RBAC do Confluent sem traduzir manualmente centenas de regras sob a pressão da migração.

A ferramenta não pretende esconder o processo de migração. Ela pretende torná-lo visível.

Extraia o estado atual. Planeje o estado alvo. Revise o relatório. Faça um dry-run das mudanças. Aplique de forma deliberada. Verifique o acesso efetivo. Gere scripts de limpeza. Revise-os. Depois remova as ACLs antigas somente quando estiver pronto.

Esse é o tipo de fluxo que queremos para migrações de controle de acesso.

Nós a criamos porque é útil para nós. Esperamos que seja útil para outros também.

Você pode encontrar o monedula-acl-rbac-converter no GitHub. Se encontrar um bug ou tiver uma sugestão de melhoria, fique à vontade para abrir uma issue.