DOC-2292/DOC-2015: Document shadow link role synchronization (26.2) by Feediver1 · Pull Request #1780 · redpanda-data/docs

Feediver1 · 2026-07-08T23:49:39Z

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
monitor.adoc: Role sync counts bullet in the status output 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.

✅ Verified in review (answers from @nguyen-andrew, applied in `6f6e95a`)

No special failover step for roles — failover is topic-data only; sync tasks keep running until paused per-task or the link is deleted (now documented)
Apache Kafka source — Roles Migrator enters LINK_UNAVAILABLE without affecting other tasks (now documented)
Role sync counters — surface in the rpk shadow status Reason field, latest cycle only, not Prometheus (now documented in setup.adoc + monitor.adoc)
Source-cluster version — both clusters 26.2+ confirmed; BYOC/Dedicated/self-hosted only (content already env-gated)

Also per review: removed the "security vulnerability" rationale for excluding SCRAM credentials.

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

Documents the Roles Migrator task (ENG-1233 rpk + ENG-898 core): - setup.adoc: role_sync_options in the sample config file + new Role filtering section (empty-default gotcha, full-mirror semantics, credentials deliberately excluded, ACL sync required for end-to-end authorization, permissions/network notes) - overview.adoc: Roles Migrator task tab + RBAC roles in the replication list - rbac.adoc: cross-link TIP to role filtering All content gated ifndef::env-cloud (rpk rejects role_sync_options for Cloud in 26.2). Field names verified against rpk types.go and PR #30909; behavior from roles_migrator.cc and ducktape e2e tests. DRAFT-VERIFY comments mark SME questions for Andrew Nguyen and Rogger Vasquez. Stacked on the DOC-2254 branch to avoid conflicts in shared files. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

coderabbitai · 2026-07-08T23:50:15Z

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: a29f05bc-3562-48da-80b9-dacac161faff

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.}

nguyen-andrew

Looks good, just added some responses to questions

nguyen-andrew · 2026-07-09T15:35:54Z

+
+Role synchronization replicates role definitions and memberships only:
+
+* **Shadowing does not replicate user credentials.** Replicating SCRAM credentials between clusters would create a security vulnerability, so Shadowing deliberately excludes them. Manage and distribute credentials outside of Shadowing, and provision users on the shadow cluster before failover.


Replicating SCRAM credentials between clusters would create a security vulnerability, so Shadowing deliberately excludes them.

I don't think we need to include this. It's not necessarily a vulnerability, but add it would've added risk and we determined that the juice wasn't worth the squeeze for now.

Removed in 6f6e95a — the bullet now just states that Shadowing doesn't replicate user credentials, with the pre-provisioning guidance, and no claim about why. Thanks!

nguyen-andrew · 2026-07-10T15:58:16Z

+// Andrew Nguyen (core) and Rogger Vasquez (rpk): (1) no special failover step for roles,
+// (2) behavior when the source is Apache Kafka (DescribeRedpandaRoles is Redpanda-specific),
+// (3) whether role sync counters (created/updated/deleted/failures) surface in
+// rpk shadow status or metrics, (4) exact source-cluster version requirement.


Shadow link failover is a topic-data mechanism only: rpk shadow failover sets each topic's mirror status to failing_over, which cuts source replication for that topic and makes it read-write, but it has no effect on the sync tasks (roles, ACLs, consumer offsets, schema registry) - these keep running on their intervals independently. To stop role sync, you either pause it in the link config (each task has its own paused flag; there's no link-wide pause) or delete the link.

Since DescribeRedpandaRoles is Redpanda-specific, an Apache Kafka source won't advertise it and so the ApiVersions negotiation for it won't work - the role sync task will just park itself in link_unavailable (doesn't affect the other tasks on that link).

Not as Prometheus metrics, but the counts appear in rpk shadow status in the role task's Reason field (e.g. Synced roles: 2 created, 0 updated, 0 deleted, 0 failures) - only for the latest cycle though, not cumulative.

Both source and shadow clusters must be Redpanda v26.2 or newer (for role syncing specifically). Also note that this is BYOC/Dedicated/self-hosted only - not serverless.

All four applied in 6f6e95a (plus link touch-ups in 78a3039):

Failover: documented that failover acts on topic data only and sync tasks keep running on their intervals until paused per-task (paused: true in role_sync_options) or the link is deleted.

Apache Kafka source: documented that role sync requires a Redpanda source, and the Roles Migrator enters LINK_UNAVAILABLE without affecting the other tasks on the link.

Counters: documented the rpk shadow status Reason field with your example output (latest cycle only), in setup.adoc and monitor.adoc's status list.

Version: kept "both clusters 26.2 or later" as written. The Serverless exclusion is covered by the existing ifndef::env-cloud[] gating — worth revisiting when the Cloud twins (DOC-1814/DOC-2306) get picked up.

Also removed the DRAFT-VERIFY comment block since all four questions are now answered. Thanks for the thorough answers!

- Drop the "security vulnerability" rationale for excluding SCRAM credentials; state only that Shadowing does not replicate them - Document that failover acts on topic data only: sync tasks keep running until paused per-task or the link is deleted - Document Apache Kafka source behavior: Roles Migrator enters LINK_UNAVAILABLE without affecting other tasks - Document role sync counts in the rpk shadow status Reason field (latest cycle only), in setup.adoc and the monitor.adoc status list - Remove the DRAFT-VERIFY comment block: all four questions answered in review Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

nguyen-andrew

Looks good to me 😀

Feediver1 requested a review from a team as a code owner July 8, 2026 23:49

Feediver1 requested review from nguyen-andrew and r-vasquez July 8, 2026 23:51

nguyen-andrew reviewed Jul 10, 2026

View reviewed changes

Feediver1 and others added 2 commits July 16, 2026 11:48

Link first Roles Migrator mentions to task anchor and Role filtering

78a3039

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Feediver1 requested review from nguyen-andrew and trevpanda July 16, 2026 18:02

nguyen-andrew approved these changes Jul 16, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

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

DOC-2292/DOC-2015: Document shadow link role synchronization (26.2)#1780
Feediver1 wants to merge 3 commits into
DOC-2254-confluent-schema-registry-migrationfrom
DOC-2292-2015-shadow-link-role-sync

Feediver1 commented Jul 8, 2026 •

edited

Loading

Uh oh!

coderabbitai Bot commented Jul 8, 2026 •

edited

Loading

Review skipped

Uh oh!

nguyen-andrew left a comment

Uh oh!

nguyen-andrew Jul 9, 2026

Uh oh!

Feediver1 Jul 16, 2026

Uh oh!

nguyen-andrew Jul 10, 2026

Uh oh!

Feediver1 Jul 16, 2026

Uh oh!

nguyen-andrew left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants


		Role synchronization replicates role definitions and memberships only:

		* Shadowing does not replicate user credentials. Replicating SCRAM credentials between clusters would create a security vulnerability, so Shadowing deliberately excludes them. Manage and distribute credentials outside of Shadowing, and provision users on the shadow cluster before failover.

Uh oh!

Conversation

Feediver1 commented Jul 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Changes

Sources of truth

✅ Verified in review (answers from @nguyen-andrew, applied in 6f6e95a)

Related

Page previews

Checks

Uh oh!

coderabbitai Bot commented Jul 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review skipped

Uh oh!

nguyen-andrew left a comment

Choose a reason for hiding this comment

Uh oh!

nguyen-andrew Jul 9, 2026

Choose a reason for hiding this comment

Uh oh!

Feediver1 Jul 16, 2026

Choose a reason for hiding this comment

Uh oh!

nguyen-andrew Jul 10, 2026

Choose a reason for hiding this comment

Uh oh!

Feediver1 Jul 16, 2026

Choose a reason for hiding this comment

Uh oh!

nguyen-andrew left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Feediver1 commented Jul 8, 2026 •

edited

Loading

✅ Verified in review (answers from @nguyen-andrew, applied in `6f6e95a`)

coderabbitai Bot commented Jul 8, 2026 •

edited

Loading