Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Feediver1 wants to merge 1 commit into
base: DOC-2254-confluent-schema-registry-migration
Choose a base branch
from
+80 −1
Open

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 19 additions & 0 deletions modules/manage/pages/disaster-recovery/shadowing/overview.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,9 @@ Shadowing replicates:
* **Topic configurations**: Partition counts, retention policies, and other topic properties
* **Consumer group offsets**: Enables seamless consumer resumption after failover
* **Access control lists (ACLs)**: User permissions and security policies
ifndef::env-cloud[]
* **RBAC roles**: Role definitions and memberships, for the roles you select with filters
endif::[]
* **Schema Registry data**: Schema definitions, versions, and compatibility settings, replicated from another Redpanda cluster or from a Confluent Schema Registry

== How Shadowing fits into disaster recovery
Expand Down Expand Up @@ -123,6 +126,22 @@ The task is controlled by the `schema_registry_sync_options` section in the conf

A shadow link uses one mode or the other, not both.
--

ifndef::env-cloud[]
Roles Migrator::
+
--
[#roles-migrator-task]
The **Roles Migrator task** replicates RBAC role definitions and role memberships from the source cluster, so that role-based permissions authorize the same operations on the shadow cluster after failover.

The task is controlled by the `role_sync_options` section in the configuration file. It includes:

* **Role name filters**: Determines which roles replicate. No roles replicate until you add at least one include filter.
* **Sync interval**: How frequently to synchronize roles

Within the configured filters, the task keeps the shadow cluster's roles as a full mirror of the source, creating, updating, and deleting roles to match. It does not replicate user credentials or the ACLs bound to roles; the Security Migrator task replicates ACLs.
--
endif::[]
====

=== Task status and monitoring
Expand Down
56 changes: 56 additions & 0 deletions modules/manage/pages/disaster-recovery/shadowing/setup.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -257,6 +257,16 @@ security_sync_options:

schema_registry_sync_options: # Schema Registry synchronization options
shadow_schema_registry_topic: {} # Enable byte-for-byte _schemas topic replication

ifndef::env-cloud[]
role_sync_options: # RBAC role synchronization options
interval: 30s # How often to sync roles
paused: false # Enable role synchronization
role_name_filters: # Default empty: no roles sync until you add an INCLUDE filter
- pattern_type: LITERAL # Pattern type: "LITERAL", "PREFIX"
filter_type: INCLUDE # Filter type: "INCLUDE", "EXCLUDE"
name: '*' # Include all roles ('*' must be the only character, LITERAL only)
endif::[]
----
====

Expand Down Expand Up @@ -550,6 +560,52 @@ security_sync_options:
host: '*' # Any host
----

// DRAFT-VERIFY (DOC-2292/DOC-2015): Role sync documents ENG-1233/ENG-898 (v26.2; all
// engineering PRs merged to dev; feature flag shadow_link_role_sync). Confirm with
// 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.

@nguyen-andrew nguyen-andrew Jul 10, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

  2. 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).

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

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

ifndef::env-cloud[]
==== Role filtering

After a failover, your users and applications need the same permissions on the shadow cluster that they had on the source. Role synchronization prepares the shadow cluster for that moment: the xref:manage:disaster-recovery/shadowing/overview.adoc#shadow-link-tasks[Roles Migrator task] periodically reads xref:manage:security/authorization/rbac.adoc[RBAC] role definitions and role memberships from the source cluster and mirrors them to the shadow cluster. Use role synchronization together with <<acl-filtering,ACL filters>> whenever your authorization model uses roles, so that role-based permissions keep working after failover.

[IMPORTANT]
====
No roles are replicated by default. The `role_name_filters` list defaults to empty, which synchronizes nothing. Add at least one `INCLUDE` filter to start replicating roles.
====

To replicate all roles:

[,yaml]
----
role_sync_options:
interval: 30s # How often to sync roles
role_name_filters:
- pattern_type: LITERAL
filter_type: INCLUDE
name: '*' # '*' must be the only character and requires LITERAL
----

Role filters use the same pattern and filter types as topic filters: `pattern_type` is `LITERAL` or `PREFIX`, and `filter_type` is `INCLUDE` or `EXCLUDE`.

Within the configured filters, the Roles Migrator task keeps the shadow cluster's roles as a full mirror of the source:

* The task creates roles that exist on the source but not on the shadow.
* The task updates roles whose membership changed on the source.
* The task deletes roles that were deleted on the source.

The task does not modify roles on the shadow cluster that fall outside your filters.

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.

@nguyen-andrew nguyen-andrew Jul 9, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

* **Role synchronization does not replicate the ACLs bound to roles.** Configure <<acl-filtering,ACL filters>> as well, so that both the roles and the permissions granted to them exist on the shadow cluster.

Role synchronization uses the same connection and service account as the rest of the shadow link. The cluster `describe` permission already required for ACL replication also covers role reads, and no additional network configuration is required. Both the source and shadow clusters must be running Redpanda 26.2 or later; the capability activates after the upgrade completes on all brokers.
endif::[]

==== Consumer group filtering and behavior

Consumer group filters determine which consumer groups have their offsets replicated to the shadow cluster by the xref:manage:disaster-recovery/shadowing/overview.adoc#shadow-link-tasks[Consumer Group Shadowing task].
Expand Down
6 changes: 5 additions & 1 deletion modules/manage/pages/security/authorization/rbac.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,4 +12,8 @@ Role-based access control (RBAC) provides a way to configure permissions for pro

endif::[]

include::manage:partial$rbac-dp.adoc[]
include::manage:partial$rbac-dp.adoc[]

ifndef::env-cloud[]
TIP: If you use xref:manage:disaster-recovery/shadowing/index.adoc[Shadowing] for disaster recovery, you can replicate roles to the shadow cluster so that role-based permissions keep working after failover. See xref:manage:disaster-recovery/shadowing/setup.adoc#role-filtering[Role filtering].
endif::[]
Loading