docs: document required ACLs for the Redpanda Migrator user (#451)

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-authored-by: Joyce Fee <102751339+Feediver1@users.noreply.github.com>

Author: 3 people

modules/components/pages/inputs/redpanda_migrator.adoc

@@ -51,6 +51,7 @@ For capabilities, guarantees, scheduling, and examples, see the output documenta
 * Must be paired with a `redpanda_migrator` output in the same pipeline.
 * Requires access to a source Kafka or Redpanda cluster.
 * Consumer group configuration is recommended for partition balancing.
+* When the source cluster enforces ACLs, a consumer ACL alone is not enough for the source principal: it needs at minimum topic `READ` *and* `DESCRIBE_CONFIGS`, plus consumer group and cluster permissions. A `READ` ACL grants `DESCRIBE` but not `DESCRIBE_CONFIGS`, so the migrator consumes messages but fails to create topics with `TOPIC_AUTHORIZATION_FAILED`. See xref:cookbooks:redpanda_migrator.adoc#required-permissions[Required permissions].
 
 == Multiple migrator pairs
 When using multiple migrator pairs in a single pipeline, coordination is based on the `label` field. The label of the input and output must match exactly for correct pairing. If labels do not match, migration fails for that pair.

modules/components/pages/outputs/redpanda_migrator.adoc

@@ -42,6 +42,16 @@ include::components:example$advanced/outputs/redpanda_migrator.yaml[]
 ======
 
 
+== Requirements
+
+When the destination cluster enforces ACLs, the destination principal needs permission to create topics and add partitions, not only to produce records. Grant these ACLs at minimum:
+
+* Topic `CREATE`, `WRITE`, `ALTER`, and `DESCRIBE_CONFIGS`. Cluster `CREATE` also authorizes topic creation.
+* When consumer group migration is enabled, consumer group `READ`.
+* When `sync_topic_acls` is enabled, cluster `ALTER`.
+
+For the source-principal ACLs and full details, see xref:cookbooks:redpanda_migrator.adoc#required-permissions[Required permissions].
+
 == Multiple migrator pairs
 
 Each migrator pair requires a unique `label`. Set the same label value on both the input and output within a pair. Labels must match exactly; mismatched labels prevent the input and output from coordinating.

modules/cookbooks/pages/redpanda_migrator.adoc

@@ -365,6 +365,104 @@ endif::[]
 
 At this point, the `source` cluster has some data in both `foo` and `bar` topics, and the consumer prints the messages it reads from these topics to `stdout`.
 
+[#required-permissions]
+== Required permissions
+
+This cookbook authenticates as a superuser for simplicity. In production, when the source and destination clusters enforce authorization (ACLs), a basic consumer or producer ACL is not sufficient for Redpanda Migrator. The migrator authenticates to the source cluster with the credentials in the `redpanda_migrator` input, and to the destination cluster with the credentials in the `redpanda_migrator` output, so grant ACLs to each principal as follows.
+
+[IMPORTANT]
+====
+To recreate each topic on the destination with matching settings, Redpanda Migrator reads the source topic's configuration with a `DescribeConfigs` request, which requires the `DESCRIBE_CONFIGS` operation on the topic.
+
+A consumer ACL (`READ`) implicitly grants `DESCRIBE`, but it does *not* grant `DESCRIBE_CONFIGS`. If the source principal has only `READ`, the migrator consumes messages successfully but fails to create topics, logging an error such as:
+
+[,text]
+----
+level=error msg="Failed to send message to redpanda_migrator: creating records: sync topics:
+create topic <topic>: get topic details <topic>: TOPIC_AUTHORIZATION_FAILED:
+Not authorized to access topics: [Topic authorization failed.]"
+----
+
+Despite the `create topic` wording, this failure is the `DescribeConfigs` read against the *source* cluster, not the topic creation on the destination.
+====
+
+=== Source cluster
+
+Grant the source principal (the `redpanda_migrator` input credentials) these ACLs:
+
+[cols="1,1,2"]
+|===
+| Resource | Operations | Purpose
+
+| Topic (migrated topics)
+| `READ`, `DESCRIBE_CONFIGS`
+| Consume records (`READ`, which also grants `DESCRIBE` for metadata and offsets) and read topic configurations to replicate them (`DESCRIBE_CONFIGS`).
+
+| Group (the input's `consumer_group`)
+| `READ`
+| Join the migrator's own consumer group and track progress.
+
+| Group (migrated groups)
+| `DESCRIBE`
+| Read source consumer group offsets. Required when consumer group migration is enabled (`consumer_groups.enabled`, the default).
+
+| Cluster
+| `DESCRIBE`
+| List source consumer groups. Also required to read source ACLs when `sync_topic_acls` is enabled on the output.
+|===
+
+For example, to grant the least-privilege source ACLs to `User:migrator` with `rpk`:
+
+[,bash]
+----
+# Consume records and read topic configs (READ also grants DESCRIBE; DESCRIBE_CONFIGS does not come with READ)
+rpk security acl create --allow-principal User:migrator \
+  --operation read,describe_configs \
+  --topic <migrated-topics>
+
+# READ on the migrator's own consumer group
+rpk security acl create --allow-principal User:migrator \
+  --operation read \
+  --group <migrator-consumer-group>
+
+# DESCRIBE on the groups being migrated (omit if consumer_groups.enabled is false)
+rpk security acl create --allow-principal User:migrator \
+  --operation describe \
+  --group <migrated-groups>
+
+# List consumer groups (and describe ACLs if sync_topic_acls is enabled)
+rpk security acl create --allow-principal User:migrator \
+  --operation describe \
+  --cluster
+----
+
+=== Destination cluster
+
+Grant the destination principal (the `redpanda_migrator` output credentials) these ACLs:
+
+[cols="1,1,2"]
+|===
+| Resource | Operations | Purpose
+
+| Topic (migrated topics)
+| `CREATE`, `WRITE`, `ALTER`, `DESCRIBE_CONFIGS`
+| Create topics (`CREATE` and `DESCRIBE_CONFIGS`), produce migrated records (`WRITE`), and add partitions to match the source (`ALTER`). These operations also grant `DESCRIBE`.
+
+| Cluster
+| `CREATE`
+| Allow creating destination topics whose names are not known in advance. Use instead of per-topic `CREATE`.
+
+| Group (migrated groups)
+| `READ`
+| Commit translated consumer group offsets. Required when consumer group migration is enabled (`consumer_groups.enabled`, the default).
+
+| Cluster
+| `ALTER`
+| Create migrated ACLs on the destination. Required only when `sync_topic_acls` is enabled.
+|===
+
+TIP: Run `rpk security acl --help-operations` to see which ACL operation each Kafka request requires.
+
 == Configure and start Redpanda Migrator
 
 The unified Redpanda Migrator does the following: