Verify effective access

After apply, verify asks MDS, for every source ACL, whether the original principal, operation and resource is now allowed, so it also catches a binding that exists but grants nothing, for example when a principal does not resolve or the cluster ID is wrong. It changes nothing, and it is the gate before any ACL is deleted.

Before you start

• An applied plan whose run directory still holds the acls.json it was made from, which the default mode reads.
• The same MDS flags as for apply.

Steps

1. Run verify

monedula-acl-rbac verify \
  --plan runs/2026-05-21T10-00-00Z/plan.json \
  --mds-url https://mds.example.com \
  --mds-token-file ~/.confluent/token

verify checks that plan.json still matches its checksum, then writes verify.json to the path you give with --out, otherwise into its run directory: --run-dir when you give it, otherwise the directory of --plan. It stamps the plan’s SHA-256 into verify.json, so the delete commands can tell which plan it checked. --verify-parallelism sets the number of concurrent MDS lookups, 8 by default.

2. Read the results

The default mode, --mode effective, classifies each source ACL:

• EFFECTIVE_OK: the binding grants the access the ACL granted.
• EFFECTIVE_MISSING: the binding exists in MDS, but the principal still cannot perform the operation. Common causes are a principal that does not resolve in MDS, such as a TLS distinguished name passed through unmapped or an LDAP setup that did not resolve it, group membership that has not propagated yet, and a scope mismatch, such as a wrong cluster ID in scopes.yaml (Find the cluster IDs for scopes.yaml).
• EFFECTIVE_UNKNOWN: MDS did not answer clearly, for example because it lacks the lookup endpoint. The tool treats this as unsafe.

To list every result that is not EFFECTIVE_OK:

jq '.results[] | select(.status != "EFFECTIVE_OK")' verify.json

--format json prints the same envelope on stdout as verify.json holds on disk, described by verify-summary.v1.json.

3. Fix missing access and run verify again

Fix the cause of each EFFECTIVE_MISSING result, for example with a principal mapping in principals.yaml, then run verify again. Right after apply, MDS’s role-binding cache can lag a few seconds behind, so run verify again before you look for another cause.

If the fix changes the plan, for example a corrected cluster ID or principal mapping, plan again, apply the new plan and verify it: a verify.json belongs to the plan it checked.

4. Accept unknown results only where MDS cannot answer

Where MDS lacks the effective-access lookup endpoint, add --accept-unknown-verify to treat EFFECTIVE_UNKNOWN results as EFFECTIVE_OK:

monedula-acl-rbac verify \
  --plan runs/2026-05-21T10-00-00Z/plan.json \
  --mds-url https://mds.example.com \
  --mds-token-file ~/.confluent/token \
  --accept-unknown-verify

The downgrade is recorded in the detail field of each result it changed, so it stays visible in verify.json. It never affects EFFECTIVE_MISSING.

Check only that the bindings exist

--mode bindings-exist only confirms that the binding rows exist in MDS, with no group or LDAP lookups. It writes verify.json too, replacing the effective results unless you pass --out with another path, and delete-acls accepts its BINDING_EXISTS results. To keep both, write each mode to its own file, as the live-mds-migration example does with --out out/verify-bindings.json and --out out/verify-effective.json, and pass the effective one to delete-acls.

Check it worked

verify exits 0 when every result is OK, and 5 when any result is EFFECTIVE_MISSING, EFFECTIVE_UNKNOWN or, in bindings-exist mode, a missing binding, so it works as a CI gate. verify.json is written before that check, so you can still read it after a non-zero exit. The verify line of monedula-acl-rbac status runs/2026-05-21T10-00-00Z counts the results, for example 0 missing, 0 unknown.

Then wait at least 24 hours before you delete the converted ACLs.

Related

• Recover from a failed run covers what to do when verify keeps failing.
• The verify command reference lists every flag and exit code.
• Runnable version: live-mds-migration, which runs both verify modes against a real MDS.