Config files

monedula-acl-rbac reads four YAML configuration files: scopes.yaml, which plan and convert require, and three optional ones. init writes a starter scopes.yaml and rules.yaml with the placeholders documented inline, and refuses to overwrite existing files.

scopes.yaml

Passed with --scopes to plan and convert. Names the Confluent clusters that role bindings are scoped to.

organization: 123e4567-e89b-12d3-a456-426614174000   # required if any binding targets org scope
environment:  env-abc123                              # required if any binding targets environment scope
kafka_cluster:           lkc-kafka01                  # required for the common case
schema_registry_cluster: lsrc-sr01                    # only if input ACLs reference Subject resources
ksql_cluster:            lksqlc-ksql01                # optional; no ACL resource type requires it
connect_cluster:         lcc-connect01                # optional; no ACL resource type requires it

Field	Required	Description
kafka_cluster	For bindings on Topic, Group, TransactionalId, Cluster and DelegationToken resources	The ID that MDS knows the Kafka cluster by.
schema_registry_cluster	For bindings on Subject resources	The Schema Registry cluster ID.
ksql_cluster	No	The ksqlDB cluster ID. Accepted, and filled in by discover; no ACL resource type the tool reads requires it.
connect_cluster	No	The Connect cluster ID. Accepted, and filled in by discover; no ACL resource type the tool reads requires it.
organization	Only for bindings that need an organization scope	The Confluent organization ID. plan does not check it; when set, it is added to the scope of every binding.
environment	Only for bindings that need an environment scope	The Confluent environment ID. plan does not check it; when set, it is added to the scope of every binding.

Only the IDs that your bindings need are checked: plan stops with an error that names a missing field. The value of kafka_cluster must match the ID MDS knows the cluster by exactly; Find the cluster IDs for scopes.yaml shows where to get it. discover --mds-url ... writes a stub with the IDs MDS reports. The cfk and mds-curl output formats cannot express organization and environment scopes; they leave them out with a warning comment.

rules.yaml

Passed with --rules to plan and convert. Overrides or extends the built-in mapping rules; monedula-acl-rbac rules show prints the defaults.

rules:
  - when:
      operations: [Read, Describe]
      operations_mode: all   # default; alternatives: any
      resource_type: Topic
      permission_type: Allow
    then:
      role: DeveloperRead
      scope_template: kafka-cluster

Field	Required	Description
rules[].when.operations	Yes	The operations to match, at least one: Read, Write, Create, Delete, Alter, Describe, ClusterAction, DescribeConfigs, AlterConfigs, IdempotentWrite or All.
rules[].when.operations_mode	No	all, the default: the ACL group must hold every listed operation. any: one is enough.
rules[].when.resource_type	Yes	Cluster, Topic, Group, TransactionalId, DelegationToken or Subject.
rules[].when.permission_type	Yes	Allow or Deny.
rules[].then.role	Yes	The Confluent role to bind, such as DeveloperRead or ResourceOwner.
rules[].then.scope_template	No	Accepted; every default rule sets kafka-cluster. In 0.10.0 the binding’s cluster scope comes from the resource type, not from this field.

Values are case-sensitive, and an unknown operation, resource type, mode or permission is an error when the file is loaded. An empty file is valid and changes nothing.

Rules merge into the defaults key by key. The key is the shape of the when clause: its operations, regardless of order, mode, resource type and permission. A rule whose key matches a default replaces it in place; a rule with a new key is added after the defaults. The planner tries rules in that order. How ACLs map to RBAC roles explains the matching.

principals.yaml

Passed with --principals to plan and convert. Maps the principals in the source ACLs, such as TLS distinguished names or SASL user names, to the principals MDS expects.

principals:
  "User:CN=alice,O=acme,C=US": "User:alice@acme.com"
  "User:svc-billing":          "Group:billing-services"
fallback: pass-through   # or "fail" to require every principal be mapped

Field	Required	Description
principals	No	A map from source principal to MDS principal. A target may be a User: or Group: principal; an empty target is an error.
fallback	No	What happens to a principal without a mapping. pass-through, the default, uses it unchanged, with an MTLS_DN_PASS_THROUGH warning when it looks like a TLS distinguished name, because such a principal will probably not resolve in MDS. fail makes plan stop on it.

Without --principals, every principal passes through unchanged.

vars.yaml

Passed with --vars to extract --from script and convert. Gives the values of variables in a shell script of kafka-acls --add commands.

TOPIC: orders.events
ENV:   prod

The file is a flat map from variable name to value. A line that uses a variable missing from the file is rejected, with its line number, and control flow, such as a for loop over $TOPICS, an if or a function, is rejected whatever the file holds (Extract ACLs from any source).

Related

• Plan and review role bindings uses scopes.yaml, rules.yaml and principals.yaml.
• The init and rules show command references.