DOC-2292/DOC-2015: Document shadow link role synchronization (26.2)

[Feediver1]

Description

Documents shadow link role synchronization shipping in v26.2: the new Roles Migrator task that continuously replicates RBAC role definitions and memberships from source to shadow cluster (ENG-1233 rpk + ENG-898 core). All engineering PRs are merged to dev, including the shadow_link_role_sync feature flag (redpanda#30976, 2026-07-08).

Resolves https://redpandadata.atlassian.net/browse/DOC-2292
Resolves https://redpandadata.atlassian.net/browse/DOC-2015
Review deadline:

⚠️ Stacked PR: based on DOC-2254-confluent-schema-registry-migration (#1776) because both features edit the same overview.adoc task-tabs block and setup.adoc sync-options area. Retarget to beta after #1776 merges — the diff shown here is role-sync-only.

Changes

• setup.adoc: role_sync_options added to the sample config file; new Role filtering section with:
  • Contextualized intro (why roles matter at failover, what the task does, when to use it)
  • IMPORTANT callout for the empty-default gotcha (no roles sync until an INCLUDE filter is added — opposite of ACL sync's default)
  • Full-mirror semantics within filter scope (create/update/delete; out-of-scope untouched)
  • Credentials deliberately not replicated (ENG-898 security rationale) + pre-provision guidance
  • Role-bound ACLs need ACL filters too for end-to-end authorization (per the e2e test)
  • Permissions/network: same connection + service account; existing cluster describe covers roles
• overview.adoc: Roles Migrator tab in Shadow link tasks; RBAC roles bullet in the replication list
• rbac.adoc: cross-link TIP (on the wrapper page, not the shared partial)

All new content is ifndef::env-cloud[]-gated: rpk explicitly rejects role_sync_options for Cloud shadow links in 26.2. Cloud twins (DOC-1814/DOC-2306) pick this up when Cloud support lands.

Sources of truth

Field names from src/go/rpk/pkg/cli/shadow/types.go + PR #30909's sample config; behavior from roles_migrator.cc, role_reconcile.h, and shadow_link_role_sync_test.py. Engineering PRs: redpanda#30838, #30932, #30946, #30909, #30978, #30976, #30731. Full research report on DOC-2292.

⚠️ Verify before merge (DRAFT-VERIFY comments in source)

• No special failover step for roles (inference from full-mirror design) — @nguyen-andrew
• Behavior with an Apache Kafka source (DescribeRedpandaRoles is Redpanda-specific)
• Whether role sync counters surface in rpk shadow status/metrics
• Exact source-cluster version requirement (docs currently say both clusters 26.2+)

Related

• rpk shadow reference pages regenerate at 26.2 release (config template + describe/status gain Role Sync sections) — not hand-edited here
• SMEs: Rogger Vasquez (rpk), Andrew Nguyen (core)

Page previews

• (after Netlify builds) /streaming/26.2/manage/disaster-recovery/shadowing/setup/#role-filtering
• /streaming/26.2/manage/disaster-recovery/shadowing/overview/#shadow-link-tasks
• /streaming/26.2/manage/security/authorization/rbac/

Checks

• New feature
• Content gap
• Support Follow-up
• Small fix (typos, links, copyedits, etc)

🤖 Generated with Claude Code

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 7843a88a-18a0-4b5b-91f5-adb4f0c2a1fe

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch DOC-2292-2015-shadow-link-role-sync

---

_{Comment @coderabbitai help to get the list of available commands.}