De las ACL de Kafka al RBAC de Confluent:
una ruta de migración segura con una nueva herramienta de código abierto

Cuando trabajamos con bancos y grandes empresas, Kafka rara vez es un proyecto desde cero.

Lo más habitual es que Kafka lleve años funcionando. Los equipos dependen de él, datos críticos fluyen a través de él y la plataforma ha acumulado un largo historial de decisiones operativas, convenciones de nomenclatura, cuentas de servicio, patrones de topics y reglas de acceso. Para cuando una organización decide migrar a Confluent Platform, Kafka ya no es solo un sistema de mensajería. Es parte de la columna vertebral de producción.

Ese contexto importa, porque las migraciones en este tipo de entornos no son solo proyectos técnicos. Son ejercicios de gestión de riesgos.

En la primera fase de una migración a Confluent, el enfoque más seguro suele ser cambiar lo menos posible. El objetivo es trasladar la base de la plataforma, estabilizarla y solo entonces introducir mejoras más grandes. La autenticación y la autorización forman parte de esa historia. Las instalaciones de Kafka existentes a menudo se apoyan en las ACL de Apache Kafka, porque las ACL son el modelo de autorización integrado disponible en Kafka de código abierto.

Confluent Platform, sin embargo, también ofrece RBAC: control de acceso basado en roles. El RBAC suele ser más fácil de razonar a escala organizativa, encaja mejor con la gobernanza de la plataforma e se integra de forma natural con otros componentes de Confluent como Metadata Service, Control Center y Confluent for Kubernetes.

Así que la pregunta es: ¿cómo pasar de un entorno Kafka existente basado en ACL al RBAC de Confluent sin convertir el control de acceso en una migración manual de alto riesgo?

Por eso exactamente construimos monedula-acl-rbac-converter.

Por qué la migración de ACL a RBAC es más difícil de lo que parece

Un clúster de Kafka pequeño, con un puñado de topics y usuarios, puede migrarse manualmente. Inspeccionas las ACL, decides los roles RBAC equivalentes, creas los bindings, verificas el acceso y eliminas las ACL antiguas.

Pero así no son la mayoría de los entornos empresariales maduros.

En despliegues reales puedes encontrarte con cientos o miles de reglas ACL. Algunas las crearon los equipos de plataforma. Otras, los equipos de aplicaciones. Algunas vinieron de la automatización. Otras son antiguas pero siguen en uso. Algunas usan patrones de topics con prefijo. Otras hacen referencia a usuarios de servicio que desde entonces se han renombrado. Algunas se exportaron de scripts que nadie ha tocado en años.

La migración manual en ese contexto tiene varios problemas:

• es lenta,
• es propensa a errores,
• es difícil de revisar,
• es difícil de repetir,
• es difícil de auditar,
• y se vuelve peligrosa cuando empieza la limpieza.

Crear nuevos bindings RBAC es solo la mitad de la migración. La parte más delicada es demostrar que los nuevos bindings proporcionan el mismo acceso efectivo que las ACL antiguas, y solo entonces eliminar las ACL de origen.

Por eso no queríamos una herramienta que simplemente “tradujera un archivo”. Queríamos un flujo de migración.

Qué hace el conversor

monedula-acl-rbac-converter es una herramienta de línea de comandos que lee las ACL de Kafka existentes, las convierte en un plan de role bindings RBAC de Confluent y ayuda a los operadores a ejecutar la migración de forma controlada y auditable.

Puede leer ACL de múltiples fuentes del mundo real, entre ellas:

• un clúster de Kafka en vivo,
• la salida exportada de kafka-acls.sh --list,
• volcados en JSON, YAML o CSV,
• manifiestos KafkaUser de Strimzi,
• manifiestos de Confluent for Kubernetes,
• un clúster de Kubernetes en ejecución,
• o un script de shell que contiene comandos kafka-acls --add ....

Este último caso es especialmente útil en entornos brownfield. Muchos equipos no parten de una exportación limpia. En su lugar, tienen un script de configuración antiguo que creó las ACL en primer lugar.

Por ejemplo, un script de entrada puede contener 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

El conversor puede extraer esas definiciones de ACL a un archivo acls.json canónico. A partir de ahí, puede producir un plan de migración revisado, emitir scripts o manifiestos, aplicar bindings directamente a Confluent MDS, verificar el resultado y generar scripts de limpieza para las ACL antiguas.

Un flujo diseñado para cambios de alto riesgo

Las migraciones de control de acceso necesitan barreras de seguridad. Un permiso incorrecto puede romper cargas de trabajo de producción. Un permiso demasiado amplio puede crear un incidente de seguridad. Un paso de limpieza realizado demasiado pronto puede provocar una interrupción.

Por esa razón, el flujo de producción es explícito y por pasos:

1. extract       -> crear una instantánea ACL canónica
2. plan          -> convertir ACLs en un plan de migración RBAC
3. apply dry-run -> previsualizar cambios en MDS
4. apply         -> crear vinculaciones de rol RBAC
5. verify        -> comprobar acceso efectivo
6. wait          -> permitir que los usuarios prueben la nueva ruta
7. delete-acls   -> generar un script de eliminación para ACLs antiguas
8. review + run  -> ejecutar la limpieza manualmente

Cada paso crea artefactos que pueden inspeccionarse, revisarse, versionarse o adjuntarse a una solicitud de cambio.

La herramienta separa intencionadamente la planificación de la aplicación, la aplicación de la verificación y la verificación de la eliminación. Esto hace que la migración sea más fácil de razonar y más segura de ejecutar en entornos regulados.

Ejemplo: migrar desde un script de configuración de ACL

Supongamos que el punto de partida es un script de shell con comandos kafka-acls.sh --add.

1. Extraer las ACL

Primero, extrae las ACL a una representación JSON canónica:

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

El archivo opcional vars.yaml es útil cuando el script contiene variables. La herramienta no adivina valores sin resolver. Si hay variables presentes, deben proporcionarse explícitamente o el script debe expandirse previamente antes de la migración.

En esta etapa, la salida sigue siendo solo una instantánea. No se cambia ningún estado externo.

2. Crear un plan de migración

A continuación, convierte las ACL extraídas en un plan 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

El archivo scopes.yaml identifica los clústeres de Confluent a los que deben dirigirse los bindings RBAC. Los archivos opcionales rules.yaml y principals.yaml permiten a los operadores adaptar la conversión a su entorno, por ejemplo asignando los principals de origen al formato de principal que espera MDS.

El paso de planificación también genera un informe. Este es uno de los puntos de revisión más importantes del flujo. Muestra en qué se convirtió cada ACL de origen y marca todo lo que no se pudo mapear o que no debería convertirse automáticamente.

3. Leer el informe

Antes de aplicar nada, los operadores deben leer el informe generado.

Aquí es donde el trabajo de migración se vuelve visible. En lugar de depender de una conversión de caja negra, el equipo puede revisar los bindings generados, investigar las ACL sin mapear y decidir si se necesitan reglas de mapeo personalizadas.

Las ACL DENY merecen una atención especial. El RBAC de Confluent no tiene una semántica de denegación equivalente, por lo que las ACL DENY no se convierten en silencio. Se reportan y se gestionan por separado.

4. Ejecutar el paso de aplicación en modo dry-run

Antes de crear role bindings en MDS, ejecuta un 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

El dry-run previsualiza las llamadas a MDS que se realizarían. También realiza comprobaciones de lectura para que los bindings existentes puedan omitirse de forma idempotente.

Esto da a los operadores otro punto de control antes del primer cambio real.

5. Aplicar los bindings RBAC

Una vez revisada la salida del dry-run, aplica el plan:

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

El paso de aplicación crea bindings RBAC en Confluent MDS. Está diseñado para poder reejecutarse: si un binding ya existe, se omite.

6. Verificar el acceso efectivo

Después de aplicar los bindings RBAC, verifica que realmente otorgan el acceso que originalmente proporcionaban las ACL:

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

Esto es más sólido que comprobar si un binding existe. El objetivo es confirmar el acceso efectivo para el principal, la operación y el recurso originales.

Esa distinción importa en entornos empresariales donde la propagación de identidad, la pertenencia a grupos, la integración con LDAP o los desajustes de scope pueden hacer que un binding exista pero no se comporte como se espera.

7. Generar scripts de eliminación de ACL

Solo después de una verificación correcta, y tras un periodo de enfriamiento definido por el operador, deben eliminarse las ACL de origen.

La herramienta no elimina las ACL directamente. En su lugar, genera un script que los operadores inspeccionan y ejecutan ellos mismos:

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

Los artefactos generados incluyen:

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

Este es un punto de control humano deliberado. El operador puede abrir el script, revisar cada comando kafka-acls --remove, ejecutarlo para un principal cada vez y conservar el script de rollback hasta que la migración esté estable.

Distintas salidas para distintos modelos operativos

No todas las organizaciones quieren el mismo modelo de aplicación.

Algunos equipos se sienten cómodos aplicando directamente a MDS. Otros necesitan que cada cambio pase por un proceso de control de cambios, un flujo GitOps o una canalización de CD externa.

El conversor admite esos escenarios emitiendo distintos tipos de artefactos:

# Script de shell con comandos de vinculaciones de rol de Confluent CLI
monedula-acl-rbac emit \
  --plan runs/billing-batch-1/plan.json \
  --format script \
  --out-dir emit/

# Manifiestos de 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/

Esto hace que la herramienta sea útil tanto para el trabajo de migración práctico como para entornos donde los cambios de infraestructura deben pasar por un sistema separado de aprobación y despliegue.

Construido para el desorden real de las migraciones

Intentamos dar soporte a los tipos de entradas y restricciones que aparecen en entornos Kafka reales, no solo a casos de demo limpios.

Eso incluye:

• extracción de Kafka en vivo,
• exportaciones de texto,
• archivos estructurados,
• recursos nativos de Kubernetes,
• manifiestos existentes de Confluent for Kubernetes,
• scripts de configuración antiguos,
• remapeo de principals,
• reglas de conversión personalizadas,
• ejecución en dry-run,
• aplicación directa a MDS,
• scripts y manifiestos emitidos,
• verificación de acceso efectivo,
• generación de scripts de eliminación,
• artefactos de rollback,
• y comandos de status/diff para lotes de migración repetibles.

El resultado es una herramienta que puede usarse tanto para la exploración como para migraciones de nivel de producción.

Para experimentos pequeños, el comando todo-en-uno convert puede ejecutar la extracción, la planificación y la emisión de scripts en un solo paso:

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

Para producción, la canalización explícita es la ruta recomendada porque preserva los artefactos de auditoría y los puntos de revisión.

Reflexiones finales

Migrar de las ACL de Kafka al RBAC de Confluent no es solo un problema de conversión de sintaxis.

Es un cambio controlado en el modelo de autorización de una plataforma de datos en funcionamiento. En grandes organizaciones, especialmente en la banca y en sectores regulados, ese cambio debe ser revisable, repetible, auditable y reversible siempre que sea posible.

Construimos monedula-acl-rbac-converter porque seguíamos viendo el mismo patrón: Kafka ya estaba ahí, las ACL ya estaban ahí, y los equipos querían adoptar el RBAC de Confluent sin traducir manualmente cientos de reglas bajo la presión de la migración.

La herramienta no pretende ocultar el proceso de migración. Pretende hacerlo visible.

Extrae el estado actual. Planifica el estado objetivo. Revisa el informe. Ejecuta los cambios en dry-run. Aplica de forma deliberada. Verifica el acceso efectivo. Genera scripts de limpieza. Revísalos. Y entonces elimina las ACL antiguas solo cuando estés listo.

Ese es el tipo de flujo que queremos para las migraciones de control de acceso.

Lo construimos porque nos resulta útil. Esperamos que también sea útil para otros.

Puedes encontrar monedula-acl-rbac-converter en GitHub. Si encuentras un error o tienes una sugerencia de mejora, no dudes en abrir una issue.