docs: document required ACLs for the Redpanda Migrator user#451
Conversation
The migrator reads each source topic's configuration via a DescribeConfigs request so it can recreate the topic on the destination, which requires the DESCRIBE_CONFIGS operation on the topic. A consumer ACL (READ) implicitly grants DESCRIBE but not DESCRIBE_CONFIGS, so a consumer-only source principal consumes messages but then fails topic creation with TOPIC_AUTHORIZATION_FAILED against the source cluster. Add a "Required permissions" section to the migrator cookbook with source/destination ACL tables and least-privilege rpk examples, and reference it from the redpanda_migrator input and output component pages. The ACL set is derived from the migrator's admin calls and cross-checked against `rpk security acl --help-operations`. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
✅ Deploy Preview for redpanda-connect ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
|
Important Review skippedAuto incremental reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the ⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
📝 WalkthroughWalkthroughThis PR updates Redpanda Migrator documentation to describe ACL requirements for source and destination clusters. It adds a new permissions section in the cookbook, including the Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Possibly related PRs
Suggested reviewers
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@modules/components/pages/outputs/redpanda_migrator.adoc`:
- Around line 45-48: The requirements text mixes destination-principal ACLs with
the source-topic DESCRIBE_CONFIGS caveat, so separate them in
redpanda_migrator.adoc. Keep the destination summary focused on the output
principal’s needed permissions (CREATE, WRITE, ALTER, DESCRIBE_CONFIGS, consumer
group READ, cluster ALTER), and move the source-side DESCRIBE_CONFIGS
requirement for reading topic configs into the cookbook reference or a dedicated
source-side note. Use the existing “Requirements” section and the xref to
required permissions to keep the scoping clear.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 11d4cccf-5454-4d98-8a89-0ac9e21ba886
📒 Files selected for processing (3)
modules/components/pages/inputs/redpanda_migrator.adocmodules/components/pages/outputs/redpanda_migrator.adocmodules/cookbooks/pages/redpanda_migrator.adoc
Feediver1
left a comment
Feediver1
left a comment
There was a problem hiding this comment.
PR Review (final-pass against docs-team-standards)
Files reviewed: 3 .adoc files (cookbook + input/output component pages, ~103 additions)
Overall assessment: Strong, source-verified addition by the SME that fills a real gap. The new cookbook section is well-structured (tables + least-privilege rpk examples + a clear error-log explanation). One valid CodeRabbit clarity point on the output page, one style nit, and a minor cross-repo reconciliation with the companion docs PR.
Critical issues (must fix)
None. The xref:cookbooks:redpanda_migrator.adoc#required-permissions[...] links from both the input and output pages resolve — the [#required-permissions] anchor exists at cookbook line 368. Code blocks have language specifiers ([,text], [,bash]), tables are well-formed, terminology is correct.
Suggestions (should consider)
-
[outputs/redpanda_migrator.adoc:47] Em dash — the style guide disallows them: "...requires
DESCRIBE_CONFIGSon the source topics — a consumer-only ACL is not sufficient." Replace with a colon, period, or "; ". -
[outputs/redpanda_migrator.adoc:47] (aligns with CodeRabbit) The destination "Requirements" paragraph folds in a source-topic
DESCRIBE_CONFIGScaveat, which blurs which principal needs which ACL. The source requirement is already documented on the input page and in the cookbook. Consider scoping this section to the destination principal and letting the cookbook link carry the source detail. -
[inputs vs outputs pages] Structural asymmetry: the input page adds the caveat as a bullet inside an existing requirements list, while the output page introduces a new
== RequirementsH2. Minor — consider matching the two for consistency.
Impact on other files
- redpanda-data/docs#1770 (companion, different repo): worth reconciling the consumer-group ACLs. #1770's summary lists target consumer groups as
CREATE/READ, while this PR's destination table lists groupREADonly (for committing translated offsets). This PR is the more granular, source-derived version; confirm the #1770 summary doesn't imply a groupCREATEthat isn't actually required. - nav.adoc: No change needed — cookbook page already in nav (
nav.adoc:409); new section, not a new page. - What's New: No entry needed — documents existing migrator behavior, not a new feature.
- Inbound xrefs: Several pages xref the cookbook (migration guides, whats-new); all still valid.
CodeRabbit findings worth considering
- [outputs/redpanda_migrator.adoc:48] "Keep the source-side caveat separate from the destination summary" — valid. Captured as suggestion #2; the destination note should stay scoped to the output principal.
What works well
- Source-verified: ACL set derived from the migrator's admin calls (
migrator_topic.go,migrator_groups.go) and cross-checked againstrpk security acl --help-operations. - Excellent troubleshooting touch: shows the actual
TOPIC_AUTHORIZATION_FAILEDerror and explains the counter-intuitive part (the failure is aDescribeConfigsread against the source, despite "create topic" wording). - Tables document operation and purpose, and note feature-gating (
consumer_groups.enableddefault-on,sync_topic_aclsopt-in). - Least-privilege
rpkexamples with inline comments make the ACLs directly actionable.
🤖 Generated with Claude Code
2 participants
What
Documents the Kafka ACLs the Redpanda Migrator user needs on the source and destination clusters. Adds a
Required permissionssection to the migrator cookbook (source/destination ACL tables + least-privilegerpkexamples) and references it from theredpanda_migratorinput and output component pages.Why
The migrator reads each source topic's configuration via a
DescribeConfigsrequest so it can recreate the topic on the destination, which requires theDESCRIBE_CONFIGSoperation on the topic. A consumer ACL (READ) implicitly grantsDESCRIBEbut notDESCRIBE_CONFIGS, so a consumer-only source principal consumes messages successfully but then fails topic creation withTOPIC_AUTHORIZATION_FAILEDagainst the source cluster. These ACL requirements were previously undocumented.Verification
The ACL set is derived from the migrator's admin calls (
internal/impl/redpanda/migrator/migrator_topic.goandmigrator_groups.goinredpanda-data/connect) and cross-checked againstrpk security acl --help-operations. Feature gating reflects the defaults: consumer group offset migration is on by default (consumer_groups.enabled); ACL migration (sync_topic_acls) is opt-in.🤖 Generated with Claude Code