---
title: "Config files"
description: "The scopes.yaml, rules.yaml, principals.yaml and vars.yaml files monedula-acl-rbac reads, field by field."
url: https://monedula.dev/flock/docs/acl-rbac-converter/reference/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.

```yaml
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](/flock/docs/acl-rbac-converter/how-to/find-cluster-ids/) shows where to get it. [`discover --mds-url ...`](/flock/docs/acl-rbac-converter/reference/cli/discover/) 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.

```yaml
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](/flock/docs/acl-rbac-converter/concepts/how-acls-map-to-rbac/) 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.

```yaml
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.

```yaml
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](/flock/docs/acl-rbac-converter/how-to/extract-acls/)).

## Related

- [Plan and review role bindings](/flock/docs/acl-rbac-converter/how-to/plan-and-review/) uses `scopes.yaml`, `rules.yaml` and `principals.yaml`.
- The [init](/flock/docs/acl-rbac-converter/reference/cli/init/) and [rules show](/flock/docs/acl-rbac-converter/reference/cli/rules-show/) command references.