diff --git a/modules/manage/pages/disaster-recovery/shadowing/overview.adoc b/modules/manage/pages/disaster-recovery/shadowing/overview.adoc index 2d0b5fcf9d..bee32b3919 100644 --- a/modules/manage/pages/disaster-recovery/shadowing/overview.adoc +++ b/modules/manage/pages/disaster-recovery/shadowing/overview.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 @@ -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 diff --git a/modules/manage/pages/disaster-recovery/shadowing/setup.adoc b/modules/manage/pages/disaster-recovery/shadowing/setup.adoc index dd476821f6..c783afa358 100644 --- a/modules/manage/pages/disaster-recovery/shadowing/setup.adoc +++ b/modules/manage/pages/disaster-recovery/shadowing/setup.adoc @@ -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::[] ---- ==== @@ -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. +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 <> 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. +* **Role synchronization does not replicate the ACLs bound to roles.** Configure <> 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]. diff --git a/modules/manage/pages/security/authorization/rbac.adoc b/modules/manage/pages/security/authorization/rbac.adoc index fc9d98ee3c..dfc4b83be4 100644 --- a/modules/manage/pages/security/authorization/rbac.adoc +++ b/modules/manage/pages/security/authorization/rbac.adoc @@ -12,4 +12,8 @@ Role-based access control (RBAC) provides a way to configure permissions for pro endif::[] -include::manage:partial$rbac-dp.adoc[] \ No newline at end of file +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::[] \ No newline at end of file