redpanda-data · Feediver1 · Jul 21, 2026 · Jul 2, 2026 · Jul 8, 2026 · Jul 8, 2026
@@ -160,6 +160,7 @@ endif::[]
 * **Lag information**: Replication lag per partition showing source vs shadow high watermarks (HWM).
 ifndef::env-cloud[]
 * **Schema Registry sync status**: For links that replicate schemas through the Schema Registry API, inventory counts for source and destination subjects, sync progress, and the most recent error. See xref:manage:disaster-recovery/shadowing/migrate-schemas-confluent.adoc#monitor-replication-status[Monitor replication status].
+* **Role sync counts**: For links that replicate RBAC roles, the `Reason` field of the xref:manage:disaster-recovery/shadowing/overview.adoc#roles-migrator-task[Roles Migrator task] reports the counts from the most recent sync cycle (roles created, updated, deleted, and failures). See xref:manage:disaster-recovery/shadowing/setup.adoc#role-filtering[Role filtering].
 endif::[]
 
 include::manage:partial$shadowing/shadow-link-metrics.adoc[]

@@ -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
@@ -126,6 +129,22 @@ endif::[]
 
 A shadow link uses one mode or the other, not both. Only API mode runs as a separate task that appears in the shadow link status. Topic mode adds the `_schemas` topic to the set of shadowed topics, so it is monitored like any other shadow topic rather than as a separate task.
 --
+
+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. See xref:manage:disaster-recovery/shadowing/setup.adoc#role-filtering[Role filtering].
+--
+endif::[]
 ====
 
 === Task status and monitoring

@@ -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::[]
 ----
 ====
 
@@ -553,6 +563,50 @@ security_sync_options:
       host: '*'                       # Any host
 ----
 
+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#roles-migrator-task[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.** Manage and distribute credentials outside of Shadowing, and provision users on the shadow cluster before failover.
+* **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. Role synchronization requires a Redpanda source cluster: if the source is an Apache Kafka cluster, the Roles Migrator task enters the `LINK_UNAVAILABLE` state, without affecting the other tasks on the link.
+
+Role synchronization continues to run after a xref:manage:disaster-recovery/shadowing/failover.adoc[failover]. Failover acts on topic data only: it stops topic replication and makes shadow topics writable, but the sync tasks, including the Roles Migrator, keep running on their intervals. To stop role synchronization, set `paused: true` in `role_sync_options`, or delete the shadow link.
+
+To monitor role synchronization, run xref:reference:rpk/rpk-shadow/rpk-shadow-status.adoc[`rpk shadow status`]. The Roles Migrator task's `Reason` field reports the counts from the most recent sync cycle, for example: `Synced roles: 2 created, 0 updated, 0 deleted, 0 failures`.
+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]. 

@@ -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::[]