---
title: "monedula-acl-rbac-converter"
description: "A CLI that converts Apache Kafka ACLs into Confluent RBAC role bindings and verifies effective access before ACLs are deleted."
url: https://monedula.dev/flock/docs/acl-rbac-converter/
---

monedula-acl-rbac-converter is a command-line tool, `monedula-acl-rbac`, that converts Apache Kafka ACLs into Confluent RBAC role bindings. It changes external state only when you pass `--confirm` or type `yes` at a prompt.

## The workflow

Each step writes its artifacts into a run directory, which becomes the audit trail of the migration:

```text
extract  ->  plan  ->  apply  ->  verify  ->  delete-acls
```

- `extract` reads ACLs from a live cluster, a `kafka-acls.sh --list` dump, JSON, YAML or CSV, a shell script of `kafka-acls --add` commands, Strimzi `KafkaUser` resources, Confluent for Kubernetes (CFK) manifests or a running Kubernetes cluster, and writes `acls.json`.
- `plan` maps the ACLs to role bindings with [rules you can override](/flock/docs/acl-rbac-converter/concepts/how-acls-map-to-rbac/), and writes `plan.json` and `report.txt` for you to review.
- `apply` creates the bindings in the Confluent Metadata Service (MDS), after a `--dry-run` preview.
- `verify` asks MDS whether each source ACL's access is now granted, and writes `verify.json`.
- `delete-acls` writes a deletion script that you read and run yourself, and a rollback script.

Without MDS access, `emit` takes the place of `apply` and renders the plan as a Confluent CLI script, CFK `ConfluentRolebinding` manifests or MDS `curl` commands for another pipeline to apply; [Two paths: with or without MDS](/flock/docs/acl-rbac-converter/concepts/two-paths/) explains what each path can verify. For a quick look without a run directory, `convert` runs extract, plan and emit in one command.

## Where to start

- New to the tool: [Your first ACL to RBAC migration](/flock/docs/acl-rbac-converter/tutorials/first-migration/) runs the whole pipeline against a local Confluent Platform in Docker.
- To see what your ACLs become in RBAC: [Convert ACLs in one command](/flock/docs/acl-rbac-converter/tutorials/one-shot-conversion/).
- To install the CLI and verify a release: [Install monedula-acl-rbac](/flock/docs/acl-rbac-converter/how-to/install/).
- For a production migration: the [migration checklist](#migration-checklist) below.
- When a run stops halfway: [Recover from a failed run](/flock/docs/acl-rbac-converter/how-to/recover-from-a-failed-run/).
- To look up a command, flag, file or exit code: the [CLI overview](/flock/docs/acl-rbac-converter/reference/cli/) and [Config files](/flock/docs/acl-rbac-converter/reference/config-files/).
- To run an example for your ACL source: [Runnable examples](/flock/docs/acl-rbac-converter/reference/examples/).

## Migration checklist

1. Write `scopes.yaml` once per cluster, with [the cluster IDs](/flock/docs/acl-rbac-converter/how-to/find-cluster-ids/).
2. [Extract the ACLs](/flock/docs/acl-rbac-converter/how-to/extract-acls/) and check that `acls.json` holds the ACLs you expect.
3. [Plan](/flock/docs/acl-rbac-converter/how-to/plan-and-review/) and read `report.txt`, above all its unmapped, rejected and warning entries.
4. [Apply](/flock/docs/acl-rbac-converter/how-to/apply-to-mds/) with `--dry-run` and read `would-apply.log`, then apply with `--confirm`. Without MDS access, [hand the bindings to your pipeline](/flock/docs/acl-rbac-converter/how-to/emit-for-a-cd-pipeline/) instead.
5. With MDS access, [verify effective access](/flock/docs/acl-rbac-converter/how-to/verify-effective-access/); without it, [Two paths](/flock/docs/acl-rbac-converter/concepts/two-paths/) explains what to do.
6. At least 24 hours after `verify`, [delete the converted ACLs](/flock/docs/acl-rbac-converter/how-to/delete-converted-acls/): generate the deletion script, read it, run it, and keep `rollback.sh` until the migration is stable.
7. Only to remove DENY ACLs as well: [Remove DENY ACLs](/flock/docs/acl-rbac-converter/how-to/remove-deny-acls/).

## Version and license

These docs describe monedula-acl-rbac 0.10.0. The tool is open source under the AGPL-3.0 license, and its source and runnable examples are on [GitHub](https://github.com/monedula-dev/monedula-acl-rbac-converter).