From 0228148b3d2b08e3cc87bd6e8ba184c41443337b Mon Sep 17 00:00:00 2001 From: micheleRP Date: Mon, 24 Nov 2025 17:07:20 -0700 Subject: [PATCH 01/20] DOC-1667 Document Shadow Link in Cloud --- local-antora-playbook.yml | 2 +- .../shadowing/failover-runbook.adoc | 8 ++++-- .../disaster-recovery/shadowing/failover.adoc | 8 ++++-- .../disaster-recovery/shadowing/monitor.adoc | 6 ++++- .../disaster-recovery/shadowing/overview.adoc | 22 +++++++++++++++- .../disaster-recovery/shadowing/setup.adoc | 26 ++++++++++++++++++- .../partials/emergency-shadowing-callout.adoc | 2 +- .../partials/shadow-link-cloud-tip.adoc | 1 + 8 files changed, 66 insertions(+), 9 deletions(-) create mode 100644 modules/shared/partials/shadow-link-cloud-tip.adoc diff --git a/local-antora-playbook.yml b/local-antora-playbook.yml index 391a6df4d3..e3ec36f597 100644 --- a/local-antora-playbook.yml +++ b/local-antora-playbook.yml @@ -17,7 +17,7 @@ content: - url: https://github.com/redpanda-data/docs branches: [v/*, shared, site-search,'!v-end-of-life/*'] - url: https://github.com/redpanda-data/cloud-docs - branches: 'main' + branches: 'DOC-1621-Document-Cloud-Feature-Shadowing-Disaster-Recovery-Enterprise' - url: https://github.com/redpanda-data/redpanda-labs branches: main start_paths: [docs,'*/docs'] diff --git a/modules/manage/pages/disaster-recovery/shadowing/failover-runbook.adoc b/modules/manage/pages/disaster-recovery/shadowing/failover-runbook.adoc index 7fb96e0eab..aab7645c6a 100644 --- a/modules/manage/pages/disaster-recovery/shadowing/failover-runbook.adoc +++ b/modules/manage/pages/disaster-recovery/shadowing/failover-runbook.adoc @@ -3,14 +3,16 @@ :page-aliases: deploy:redpanda/manual/resilience/shadowing-guide.adoc, deploy:redpanda/manual/disaster-recovery/shadowing/failover-runbook.adoc :env-linux: true :page-categories: Management, High Availability, Disaster Recovery, Emergency Response +// tag::single-source[] +ifndef::env-cloud[] [NOTE] ==== include::shared:partial$enterprise-license.adoc[] ==== +endif::[] This guide provides step-by-step procedures for emergency failover when your primary Redpanda cluster becomes unavailable. Follow these procedures only during active disasters when immediate failover is required. - // TODO: All command output examples in this guide need verification by running actual commands in test environment [IMPORTANT] @@ -290,4 +292,6 @@ After successful failover, focus on recovery planning and process improvement. B 1. **Document the incident**: Record timeline, impact, and lessons learned 2. **Update runbooks**: Improve procedures based on what you learned 3. **Test regularly**: Schedule regular disaster recovery drills -4. **Review monitoring**: Ensure monitoring caught the issue appropriately \ No newline at end of file +4. **Review monitoring**: Ensure monitoring caught the issue appropriately + +// end::single-source[] \ No newline at end of file diff --git a/modules/manage/pages/disaster-recovery/shadowing/failover.adoc b/modules/manage/pages/disaster-recovery/shadowing/failover.adoc index d89dfd026e..ab380862ad 100644 --- a/modules/manage/pages/disaster-recovery/shadowing/failover.adoc +++ b/modules/manage/pages/disaster-recovery/shadowing/failover.adoc @@ -2,14 +2,16 @@ :description: Learn how failover can transform shadow topics into fully writable resources during disasters. :page-categories: Management, High Availability, Disaster Recovery :page-aliases: deploy:redpanda/manual/disaster-recovery/shadowing/failover.adoc +// tag::single-source[] +ifndef::env-cloud[] [NOTE] ==== include::shared:partial$enterprise-license.adoc[] ==== +endif::[] Failover is the process of modifying shadow topics or an entire shadow cluster from read-only replicas to fully writable resources, and ceasing replication from the source cluster. You can fail over individual topics for selective workload migration or fail over the entire cluster for comprehensive disaster recovery. This critical operation transforms your shadow resources into operational production assets, allowing you to redirect application traffic when the source cluster becomes unavailable. - include::shared:partial$emergency-shadowing-callout.adoc[] == Failover behavior @@ -151,4 +153,6 @@ After completing failover: * Verify that applications can produce and consume messages normally * Consider deleting the shadow link if failover was successful and permanent -For emergency situations, see xref:./failover-runbook.adoc[Failover Runbook]. \ No newline at end of file +For emergency situations, see xref:./failover-runbook.adoc[Failover Runbook]. + +// end::single-source[] \ No newline at end of file diff --git a/modules/manage/pages/disaster-recovery/shadowing/monitor.adoc b/modules/manage/pages/disaster-recovery/shadowing/monitor.adoc index b34d61eda4..81f1c0ec23 100644 --- a/modules/manage/pages/disaster-recovery/shadowing/monitor.adoc +++ b/modules/manage/pages/disaster-recovery/shadowing/monitor.adoc @@ -2,14 +2,16 @@ :description: Monitor Shadowing health with status commands, metrics, and best practices for tracking replication performance. :page-categories: Management, Monitoring, Disaster Recovery :page-aliases: deploy:redpanda/manual/disaster-recovery/shadowing/monitor.adoc +// tag::single-source[] +ifndef::env-cloud[] [NOTE] ==== include::shared:partial$enterprise-license.adoc[] ==== +endif::[] Monitor your shadow links to ensure proper replication performance and understand your disaster recovery readiness. Use `rpk` commands, metrics, and status information to track shadow link health and troubleshoot issues. - include::shared:partial$emergency-shadowing-callout.adoc[] == Status commands @@ -122,3 +124,5 @@ Configure monitoring alerts for: * **Link unavailability**: When tasks show `LINK_UNAVAILABLE` indicating source cluster connectivity issues + For more information about shadow link tasks and their states, see xref:manage:disaster-recovery/shadowing/setup.adoc#shadow-link-tasks[Shadow link tasks]. + +// end::single-source[] diff --git a/modules/manage/pages/disaster-recovery/shadowing/overview.adoc b/modules/manage/pages/disaster-recovery/shadowing/overview.adoc index 1556f36632..7e8644922d 100644 --- a/modules/manage/pages/disaster-recovery/shadowing/overview.adoc +++ b/modules/manage/pages/disaster-recovery/shadowing/overview.adoc @@ -3,11 +3,14 @@ :env-linux: true :page-categories: Management, High Availability, Disaster Recovery :page-aliases: deploy:redpanda/manual/disaster-recovery/shadowing/overview.adoc +// tag::single-source[] +ifndef::env-cloud[] [NOTE] ==== include::shared:partial$enterprise-license.adoc[] ==== +endif::[] Shadowing is Redpanda's enterprise-grade disaster recovery solution that establishes asynchronous, offset-preserving replication between two distinct Redpanda clusters. A cluster is able to create a dedicated client that continuously replicates source cluster data, including offsets, timestamps, and cluster metadata. This creates a read-only shadow cluster that you can quickly failover to handle production traffic during a disaster. @@ -29,7 +32,13 @@ Shadowing addresses enterprise disaster recovery requirements driven by regulato The architecture follows an active-passive pattern. The source cluster processes all production traffic while the shadow cluster remains in read-only mode, continuously receiving updates. If a disaster occurs, you can failover the shadow topics using the Admin API or `rpk`, making them fully writable. At that point, you can redirect your applications to the shadow cluster, which becomes the new production cluster. +ifdef::env-cloud[] +Shadowing complements Redpanda's existing availability and recovery capabilities. High availability actively protects your day-to-day operations, handling reads and writes seamlessly during node or availability zone failures within a region. Shadowing is your safety net for catastrophic regional disasters. Shadowing delivers near real-time, cross-region replication for mission-critical applications that require rapid failover with minimal data loss. +endif::[] + +ifndef::env-cloud[] Shadowing complements Redpanda's existing availability and recovery capabilities. xref:deploy:redpanda/manual/high-availability.adoc[High availability] actively protects your day-to-day operations, handling reads and writes seamlessly during node or availability zone failures within a region. Shadowing is your safety net for catastrophic regional disasters. While xref:deploy:redpanda/manual/disaster-recovery/whole-cluster-restore.adoc[Whole Cluster Restore] provides point-in-time recovery from xref:manage:tiered-storage.adoc[Tiered Storage], Shadowing delivers near real-time, cross-region replication for mission-critical applications that require rapid failover with minimal data loss. +endif::[] // TODO: insert diagram. Possibly with a .gif animation showing cluster Cluster A being written and cluster B being replicated with a data flow arrow and geo-separation. Diagram must show Icons or labels for topics, configurations, offsets, ACLs, schemas that are being copied @@ -60,10 +69,19 @@ Choose your implementation approach: * **xref:./failover.adoc[Planned Failover]** - Controlled disaster recovery testing and migrations * **xref:./failover-runbook.adoc[Failover Runbook]** - Rapid disaster response procedures +ifndef::env-cloud[] [TIP] ==== include::shared:partial$shadow-link-management-tip.adoc[] ==== +endif::[] + +ifdef::env-cloud[] +[TIP] +==== +include::shared:partial$shadow-link-cloud-tip.adoc[] +==== +endif::[] == Disaster readiness checklist @@ -87,4 +105,6 @@ After setting up Shadowing for your Redpanda clusters, consider these additional * **Review security policies**: Ensure your ACL filters replicate the appropriate security settings for your disaster recovery environment. -* **Document your configuration**: Maintain up-to-date documentation of your shadow link configuration, including network settings, authentication details, and filter definitions. \ No newline at end of file +* **Document your configuration**: Maintain up-to-date documentation of your shadow link configuration, including network settings, authentication details, and filter definitions. + +// end::single-source[] \ No newline at end of file diff --git a/modules/manage/pages/disaster-recovery/shadowing/setup.adoc b/modules/manage/pages/disaster-recovery/shadowing/setup.adoc index b0682dc430..2fd1f68650 100644 --- a/modules/manage/pages/disaster-recovery/shadowing/setup.adoc +++ b/modules/manage/pages/disaster-recovery/shadowing/setup.adoc @@ -3,23 +3,33 @@ :env-linux: true :page-categories: Management, High Availability, Disaster Recovery :page-aliases: deploy:redpanda/manual/disaster-recovery/shadowing/setup.adoc +// tag::single-source[] +ifndef::env-cloud[] include::shared:partial$shadow-link-management-tip.adoc[] +endif::[] + +ifndef::env-cloud[] +include::shared:partial$shadow-link-cloud-tip.adoc[] +endif::[] == Prerequisites +ifndef::env-cloud[] [NOTE] ==== include::shared:partial$enterprise-license.adoc[] ==== +endif::[] === License and cluster requirements - Both clusters must be running Redpanda v25.3 or later. - +ifndef::env-cloud[] - If you use Redpanda Console, ensure that it is running v3.30 or later. - You must have xref:get-started:licensing/overview.adoc[Enterprise Edition] licenses on both clusters. +endif::[] [TIP] ==== @@ -41,11 +51,17 @@ rpk cluster config set enable_shadow_linking true This cluster property must be configured using `rpk` or the Admin API v1 before you can create shadow links through any interface. ==== +ifdef::env-cloud[] +To learn more about configuring cluster properties, see xref:manage:cluster-maintenance/config-cluster.adoc[]. +endif::[] + +ifndef::env-cloud[] To learn more about configuring cluster properties, see xref:manage:cluster-maintenance/cluster-property-configuration.adoc[]. === Administrative access Superuser access is required on both clusters through xref:get-started:rpk/index.adoc[`rpk`], the Admin API, or xref:console:index.adoc[Redpanda Console] to create and manage shadow links. +endif::[] === Replication service permissions @@ -63,7 +79,13 @@ This service account authenticates from the shadow cluster to the source cluster You must configure network connectivity between clusters with appropriate firewall rules to allow the shadow cluster to connect to the source cluster for data replication. Shadowing uses a pull-based architecture where the shadow cluster fetches data from the source cluster. For detailed networking configuration, see <>. +ifndef::env-cloud[] If using xref:manage:security/authentication.adoc[authentication] for the shadow link connection, configure the source cluster with your chosen authentication method (SASL/SCRAM, TLS, mTLS) and ensure the shadow cluster has the proper credentials to authenticate to the source cluster. +endif::[] + +ifdef::env-cloud[] +If using xref:security:cloud-authentication.adoc[authentication] for the shadow link connection, configure the source cluster with your chosen authentication method (SASL/SCRAM, TLS, mTLS) and ensure the shadow cluster has the proper credentials to authenticate to the source cluster. +endif::[] == Set up Shadowing @@ -588,4 +610,6 @@ schema_registry_sync_options: # Schema Registry synchronization options ---- ==== +// end::single-source[] + See also: link:/api/doc/admin/[Admin API v2 reference^] \ No newline at end of file diff --git a/modules/shared/partials/emergency-shadowing-callout.adoc b/modules/shared/partials/emergency-shadowing-callout.adoc index d4cb4cf302..c853f01070 100644 --- a/modules/shared/partials/emergency-shadowing-callout.adoc +++ b/modules/shared/partials/emergency-shadowing-callout.adoc @@ -1,6 +1,6 @@ :important-caption: Experiencing an active disaster? [IMPORTANT] ==== -See xref:deploy:redpanda/manual/disaster-recovery/shadowing/failover-runbook.adoc[] for immediate step-by-step disaster procedures. +See xref:manage:disaster-recovery/shadowing/failover-runbook.adoc[] for immediate step-by-step disaster procedures. ==== :important-caption: Important \ No newline at end of file diff --git a/modules/shared/partials/shadow-link-cloud-tip.adoc b/modules/shared/partials/shadow-link-cloud-tip.adoc new file mode 100644 index 0000000000..77eff27d60 --- /dev/null +++ b/modules/shared/partials/shadow-link-cloud-tip.adoc @@ -0,0 +1 @@ +You can create and manage shadow links using `rpk`, the Redpanda Cloud UI, or the Data Plane API, giving you flexibility in how you interact with your disaster recovery infrastructure. \ No newline at end of file From bffbfea0edf5f4537b9efb9700c373511f37275e Mon Sep 17 00:00:00 2001 From: micheleRP Date: Mon, 24 Nov 2025 17:11:44 -0700 Subject: [PATCH 02/20] single source rpk shadow --- modules/reference/pages/rpk/rpk-shadow/rpk-shadow.adoc | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/modules/reference/pages/rpk/rpk-shadow/rpk-shadow.adoc b/modules/reference/pages/rpk/rpk-shadow/rpk-shadow.adoc index 42226eab3f..681ae4532c 100644 --- a/modules/reference/pages/rpk/rpk-shadow/rpk-shadow.adoc +++ b/modules/reference/pages/rpk/rpk-shadow/rpk-shadow.adoc @@ -1,4 +1,5 @@ = rpk shadow +// tag::single-source[] Manage Redpanda shadow links. @@ -26,4 +27,6 @@ rpk shadow [command] [flags] |--profile |string |Profile to use. See xref:reference:rpk/rpk-profile.adoc[`rpk profile`] for more details. |-v, --verbose |- |Enable verbose logging. -|=== \ No newline at end of file +|=== + +// end::single-source[] \ No newline at end of file From d3db49379630787b11b1e2c05fe1bd92102c475f Mon Sep 17 00:00:00 2001 From: micheleRP Date: Mon, 24 Nov 2025 17:23:54 -0700 Subject: [PATCH 03/20] conditionalize parts for Cloud --- .../pages/disaster-recovery/shadowing/overview.adoc | 4 +++- .../pages/disaster-recovery/shadowing/setup.adoc | 12 ++++++++++++ 2 files changed, 15 insertions(+), 1 deletion(-) diff --git a/modules/manage/pages/disaster-recovery/shadowing/overview.adoc b/modules/manage/pages/disaster-recovery/shadowing/overview.adoc index 7e8644922d..4f4714bdc9 100644 --- a/modules/manage/pages/disaster-recovery/shadowing/overview.adoc +++ b/modules/manage/pages/disaster-recovery/shadowing/overview.adoc @@ -21,7 +21,7 @@ Unlike traditional replication tools that re-produce messages, Shadowing copies Shadowing replicates: * **Topic data**: All records with preserved offsets and timestamps -* **Topic configurations**: Partition counts, retention policies, and other xref:reference:properties/topic-properties.adoc[topic properties] +* **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 * **Schema Registry data**: Schema definitions and compatibility settings @@ -56,7 +56,9 @@ Shadowing for disaster recovery currently has the following limitations: To ensure reliable disaster recovery with Shadowing: +ifndef::env-cloud[] * **Avoid write caching on source topics**: Do not shadow source topics that have xref:develop:config-topics.adoc#configure-write-caching[write caching] enabled. Write caching can result in data loss on the source cluster during broker resets, causing cluster divergence if shadow links replicate data before it's lost on the source. +endif::[] * **Do not modify shadow topic properties**: Avoid modifying synced topic properties on shadow topics, as these properties automatically revert to source topic values. diff --git a/modules/manage/pages/disaster-recovery/shadowing/setup.adoc b/modules/manage/pages/disaster-recovery/shadowing/setup.adoc index 2fd1f68650..1f2e758070 100644 --- a/modules/manage/pages/disaster-recovery/shadowing/setup.adoc +++ b/modules/manage/pages/disaster-recovery/shadowing/setup.adoc @@ -65,7 +65,13 @@ endif::[] === Replication service permissions +ifdef::env-cloud[] +You must configure a service account on the source cluster with the following xref:security:authorization/acl.adoc[ACL] permissions for shadow link replication: +endif::[] + +ifndef::env-cloud[] You must configure a service account on the source cluster with the following xref:manage:security/authorization/acl.adoc[ACL] permissions for shadow link replication: +endif::[] * **Topics**: `read` permission on all topics you want to replicate * **Topic configurations**: `describe_configs` permission on topics for configuration synchronization @@ -500,7 +506,13 @@ client_options: === Create a shadow link +ifdef::env-cloud[] +You can establish a shadow link using either `rpk`, the Data Plane API, or the Redpanda Cloud UI. For example, to create a shadow link with the source cluster, run the following `rpk` command from the shadow cluster: +endif::[] + +ifndef::env-cloud[] You can establish a shadow link using either xref:get-started:rpk/index.adoc[`rpk`], the Admin API, or xref:console:index.adoc[Redpanda Console]. For example, to create a shadow link with the source cluster, run the following `rpk` command from the shadow cluster: +endif::[] [,bash] ---- From 05bac83f87f3e595887c41741296d9db62476d9a Mon Sep 17 00:00:00 2001 From: micheleRP Date: Mon, 24 Nov 2025 17:47:32 -0700 Subject: [PATCH 04/20] add description for rpk shadow (for index page) --- modules/reference/pages/rpk/rpk-shadow/rpk-shadow.adoc | 2 ++ 1 file changed, 2 insertions(+) diff --git a/modules/reference/pages/rpk/rpk-shadow/rpk-shadow.adoc b/modules/reference/pages/rpk/rpk-shadow/rpk-shadow.adoc index 681ae4532c..884d407f29 100644 --- a/modules/reference/pages/rpk/rpk-shadow/rpk-shadow.adoc +++ b/modules/reference/pages/rpk/rpk-shadow/rpk-shadow.adoc @@ -1,4 +1,5 @@ = rpk shadow +:description: These commands let you manage shadow links for disaster recovery. // tag::single-source[] Manage Redpanda shadow links. @@ -14,6 +15,7 @@ rpk shadow [command] [flags] == Flags + [cols="1m,1a,2a"] |=== |*Value* |*Type* |*Description* From d3e108c1297cb1cb1bc393bb98fde27f1d43a805 Mon Sep 17 00:00:00 2001 From: micheleRP Date: Mon, 24 Nov 2025 21:15:16 -0700 Subject: [PATCH 05/20] minor edits --- .../shadowing/failover-runbook.adoc | 6 ++--- .../disaster-recovery/shadowing/failover.adoc | 1 + .../disaster-recovery/shadowing/monitor.adoc | 7 +++--- .../disaster-recovery/shadowing/overview.adoc | 2 +- .../disaster-recovery/shadowing/setup.adoc | 22 +++++++++---------- 5 files changed, 20 insertions(+), 18 deletions(-) diff --git a/modules/manage/pages/disaster-recovery/shadowing/failover-runbook.adoc b/modules/manage/pages/disaster-recovery/shadowing/failover-runbook.adoc index aab7645c6a..4aa57b1e7a 100644 --- a/modules/manage/pages/disaster-recovery/shadowing/failover-runbook.adoc +++ b/modules/manage/pages/disaster-recovery/shadowing/failover-runbook.adoc @@ -132,9 +132,9 @@ Name: , State: ACTIVE The partition information shows: -* **SRC_LSO**: Source partition Last Stable Offset -* **SRC_HWM**: Source partition High Watermark -* **DST_HWM**: Shadow (destination) partition High Watermark +* **SRC_LSO**: Source partition last stable offset +* **SRC_HWM**: Source partition high watermark +* **DST_HWM**: Shadow (destination) partition high watermark * **Lag**: Message count difference between source and shadow partitions [IMPORTANT] diff --git a/modules/manage/pages/disaster-recovery/shadowing/failover.adoc b/modules/manage/pages/disaster-recovery/shadowing/failover.adoc index ab380862ad..1350b6becb 100644 --- a/modules/manage/pages/disaster-recovery/shadowing/failover.adoc +++ b/modules/manage/pages/disaster-recovery/shadowing/failover.adoc @@ -12,6 +12,7 @@ include::shared:partial$enterprise-license.adoc[] endif::[] Failover is the process of modifying shadow topics or an entire shadow cluster from read-only replicas to fully writable resources, and ceasing replication from the source cluster. You can fail over individual topics for selective workload migration or fail over the entire cluster for comprehensive disaster recovery. This critical operation transforms your shadow resources into operational production assets, allowing you to redirect application traffic when the source cluster becomes unavailable. + include::shared:partial$emergency-shadowing-callout.adoc[] == Failover behavior diff --git a/modules/manage/pages/disaster-recovery/shadowing/monitor.adoc b/modules/manage/pages/disaster-recovery/shadowing/monitor.adoc index 81f1c0ec23..bb827283f2 100644 --- a/modules/manage/pages/disaster-recovery/shadowing/monitor.adoc +++ b/modules/manage/pages/disaster-recovery/shadowing/monitor.adoc @@ -12,6 +12,7 @@ include::shared:partial$enterprise-license.adoc[] endif::[] Monitor your shadow links to ensure proper replication performance and understand your disaster recovery readiness. Use `rpk` commands, metrics, and status information to track shadow link health and troubleshoot issues. + include::shared:partial$emergency-shadowing-callout.adoc[] == Status commands @@ -52,10 +53,10 @@ For troubleshooting specific issues, you can use command options to show individ The status output includes: -* **Shadow link state**: Overall operational state (`ACTIVE`) -* **Individual topic states**: Current state of each replicated topic (`ACTIVE`, `FAULTED`, `FAILING_OVER`, `FAILED_OVER`) +* **Shadow link state**: Overall operational state (`ACTIVE`). +* **Individual topic states**: Current state of each replicated topic (`ACTIVE`, `FAULTED`, `FAILING_OVER`, `FAILED_OVER`). * **Task status**: Health of replication tasks across brokers (`ACTIVE`, `FAULTED`, `NOT_RUNNING`, `LINK_UNAVAILABLE`). For details about shadow link tasks, see xref:manage:disaster-recovery/shadowing/setup.adoc#shadow-link-tasks[Shadow link tasks]. -* **Lag information**: Replication lag per partition showing source vs shadow high watermarks (HWM) +* **Lag information**: Replication lag per partition showing source vs shadow high watermarks (HWM). [[shadow-link-metrics]] == Metrics diff --git a/modules/manage/pages/disaster-recovery/shadowing/overview.adoc b/modules/manage/pages/disaster-recovery/shadowing/overview.adoc index 4f4714bdc9..bfcea4bec5 100644 --- a/modules/manage/pages/disaster-recovery/shadowing/overview.adoc +++ b/modules/manage/pages/disaster-recovery/shadowing/overview.adoc @@ -52,7 +52,7 @@ Shadowing for disaster recovery currently has the following limitations: * During a disaster, xref:manage:audit-logging.adoc[audit log] history from the source cluster is lost, though the shadow cluster begins generating new audit logs immediately after the failover. * After you failover shadow topics, automatic fallback to the original source cluster is not supported. -== Best Practices +== Best practices To ensure reliable disaster recovery with Shadowing: diff --git a/modules/manage/pages/disaster-recovery/shadowing/setup.adoc b/modules/manage/pages/disaster-recovery/shadowing/setup.adoc index 1f2e758070..8b25dd8877 100644 --- a/modules/manage/pages/disaster-recovery/shadowing/setup.adoc +++ b/modules/manage/pages/disaster-recovery/shadowing/setup.adoc @@ -9,7 +9,7 @@ ifndef::env-cloud[] include::shared:partial$shadow-link-management-tip.adoc[] endif::[] -ifndef::env-cloud[] +ifdef::env-cloud[] include::shared:partial$shadow-link-cloud-tip.adoc[] endif::[] @@ -116,14 +116,14 @@ To set up Shadowing: * **Configure filters**: Define which topics, consumer groups, and ACLs should replicate by creating include/exclude patterns that match your disaster recovery requirements. See <>. * **Create a shadow link**: Establish the connection between clusters using `rpk`, the Admin API, or Redpanda Console with authentication and network settings. See <>. -== Shadow Link Tasks +== Shadow link tasks Shadow linking operates through specialized tasks that handle different aspects of replication. Each task corresponds to a configuration section in your shadow link setup and runs continuously to maintain synchronization with the source cluster. [#source-topic-sync-task] -=== Source Topic Sync Task +=== Source Topic Sync task -The **Source Topic Sync Task** manages topic discovery and metadata synchronization. This task periodically queries the source cluster to discover available topics, applies your configured topic filters to determine which topics should become shadow topics, and synchronizes topic properties between clusters. +The **Source Topic Sync task** manages topic discovery and metadata synchronization. This task periodically queries the source cluster to discover available topics, applies your configured topic filters to determine which topics should become shadow topics, and synchronizes topic properties between clusters. The task is controlled by the `topic_metadata_sync_options` configuration section, which includes: @@ -135,7 +135,7 @@ The task is controlled by the `topic_metadata_sync_options` configuration sectio When this task discovers a new topic that matches your filters, it creates the corresponding shadow topic and begins replication from your configured starting offset. [#consumer-group-shadowing-task] -=== Consumer Group Shadowing Task +=== Consumer Group Shadowing task The **Consumer Group Shadowing task** replicates consumer group offsets and membership information from the source cluster. This ensures that consumer applications can resume processing from the correct position after failover. @@ -148,9 +148,9 @@ The task is controlled by the `consumer_offset_sync_options` configuration secti This task runs on brokers that host the `__consumer_offsets` topic and continuously tracks consumer group coordinators to optimize offset synchronization. [#security-migrator-task] -=== Security Migrator Task +=== Security Migrator task -The **Security Migrator task** replicates security policies, primarily ACLs (Access Control Lists), from the source cluster to maintain consistent authorization across both environments. +The **Security Migrator task** replicates security policies, primarily ACLs (access control lists), from the source cluster to maintain consistent authorization across both environments. The task is controlled by the `security_sync_options` configuration section, which includes: @@ -159,7 +159,7 @@ The task is controlled by the `security_sync_options` configuration section, whi By default, all ACLs replicate to ensure your shadow cluster maintains the same security posture as your source cluster. -=== Task Status and Monitoring +=== Task status and monitoring Each task reports its status through the shadow link status API. Task states include: @@ -218,7 +218,7 @@ The filtering system you configure determines the precise scope of replication a Filters determine which resources Shadowing automatically creates when establishing your shadow link. -Topic filters select which topics Shadowing automatically creates as shadow topics when they appear on the source cluster. Once Shadowing creates a shadow topic, it continues replicating until you failover the topic, delete it, or delete the entire shadow link. +Topic filters select which topics Shadowing automatically creates as shadow topics when they appear on the source cluster. After Shadowing creates a shadow topic, it continues replicating until you failover the topic, delete it, or delete the entire shadow link. Consumer group and ACL filters control which groups and security policies replicate to maintain application functionality. @@ -300,7 +300,7 @@ schema_registry_sync_options: - The `_schemas` topic must not exist on the shadow cluster, or must be empty - Once enabled, the `_schemas` topic will be replicated completely -**Important:** Once the `_schemas` topic becomes a shadow topic, it cannot be stopped without either failing over the topic or deleting it entirely. +**Important:** After the `_schemas` topic becomes a shadow topic, it cannot be stopped without either failing over the topic or deleting it entirely. === System topic filtering rules @@ -402,7 +402,7 @@ topic_metadata_sync_options: [IMPORTANT] ==== -The starting offset only affects **new shadow topics**. Once a shadow topic exists and has data, changing this setting has no effect on that topic's replication. +The starting offset only affects **new shadow topics**. After a shadow topic exists and has data, changing this setting has no effect on that topic's replication. ==== === Generate a sample configuration From 9c5e1660fea15814792b3e374eb902bbd49aca59 Mon Sep 17 00:00:00 2001 From: micheleRP Date: Tue, 25 Nov 2025 08:34:47 -0700 Subject: [PATCH 06/20] fix headings --- modules/manage/pages/disaster-recovery/shadowing/setup.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/modules/manage/pages/disaster-recovery/shadowing/setup.adoc b/modules/manage/pages/disaster-recovery/shadowing/setup.adoc index 8b25dd8877..d9a6ac7786 100644 --- a/modules/manage/pages/disaster-recovery/shadowing/setup.adoc +++ b/modules/manage/pages/disaster-recovery/shadowing/setup.adoc @@ -504,7 +504,7 @@ client_options: fetch_partition_max_bytes: 1048576 # Default 1MB, maximum bytes to fetch per partition ---- -=== Create a shadow link +== Create a shadow link ifdef::env-cloud[] You can establish a shadow link using either `rpk`, the Data Plane API, or the Redpanda Cloud UI. For example, to create a shadow link with the source cluster, run the following `rpk` command from the shadow cluster: @@ -521,7 +521,7 @@ rpk shadow create --config-file shadow-config.yaml For detailed command options, see xref:reference:rpk/rpk-shadow/rpk-shadow-create.adoc[`rpk shadow create`]. -=== Update an existing shadow link +== Update an existing shadow link If you need to modify a shadow link configuration after creation, use the update command: From 7a6ffadc11aa5f14e787c10fb77c86c7d84868bf Mon Sep 17 00:00:00 2001 From: micheleRP Date: Tue, 25 Nov 2025 12:59:24 -0700 Subject: [PATCH 07/20] update conditionalizing --- .../pages/disaster-recovery/shadowing/setup.adoc | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/modules/manage/pages/disaster-recovery/shadowing/setup.adoc b/modules/manage/pages/disaster-recovery/shadowing/setup.adoc index d9a6ac7786..d97e057f84 100644 --- a/modules/manage/pages/disaster-recovery/shadowing/setup.adoc +++ b/modules/manage/pages/disaster-recovery/shadowing/setup.adoc @@ -40,6 +40,14 @@ Deploy clusters in different geographic regions to protect against regional disa Both source and shadow clusters must have the xref:reference:properties/cluster-properties.adoc#enable_shadow_linking[`enable_shadow_linking`] cluster property set to `true`. +ifdef::env-cloud[] +[NOTE] +==== +Starting with Redpanda v25.3, this cluster property is enabled by default on new Redpanda Cloud clusters. Existing clusters created before v25.3 must enable this property manually. See xref:manage:cluster-maintenance/config-cluster.adoc[]. +==== +endif::[] + +ifndef::env-cloud[] To enable this property, run: [,bash] ---- @@ -51,11 +59,6 @@ rpk cluster config set enable_shadow_linking true This cluster property must be configured using `rpk` or the Admin API v1 before you can create shadow links through any interface. ==== -ifdef::env-cloud[] -To learn more about configuring cluster properties, see xref:manage:cluster-maintenance/config-cluster.adoc[]. -endif::[] - -ifndef::env-cloud[] To learn more about configuring cluster properties, see xref:manage:cluster-maintenance/cluster-property-configuration.adoc[]. === Administrative access @@ -114,7 +117,7 @@ This creates a complete YAML configuration file that you can customize for your To set up Shadowing: * **Configure filters**: Define which topics, consumer groups, and ACLs should replicate by creating include/exclude patterns that match your disaster recovery requirements. See <>. -* **Create a shadow link**: Establish the connection between clusters using `rpk`, the Admin API, or Redpanda Console with authentication and network settings. See <>. +* **Create a shadow link**: Establish the connection between clusters using `rpk`, the API, or Redpanda Console with authentication and network settings. See <>. == Shadow link tasks From 781937a74cb0e6fc910a8133ae7b177368a4843e Mon Sep 17 00:00:00 2001 From: micheleRP Date: Tue, 25 Nov 2025 16:23:49 -0700 Subject: [PATCH 08/20] move conceptual sections from setup into overview --- .../disaster-recovery/shadowing/overview.adoc | 125 +++++++++++++++++- .../disaster-recovery/shadowing/setup.adoc | 104 +-------------- 2 files changed, 125 insertions(+), 104 deletions(-) diff --git a/modules/manage/pages/disaster-recovery/shadowing/overview.adoc b/modules/manage/pages/disaster-recovery/shadowing/overview.adoc index bfcea4bec5..e2949a8979 100644 --- a/modules/manage/pages/disaster-recovery/shadowing/overview.adoc +++ b/modules/manage/pages/disaster-recovery/shadowing/overview.adoc @@ -52,6 +52,123 @@ Shadowing for disaster recovery currently has the following limitations: * During a disaster, xref:manage:audit-logging.adoc[audit log] history from the source cluster is lost, though the shadow cluster begins generating new audit logs immediately after the failover. * After you failover shadow topics, automatic fallback to the original source cluster is not supported. +== Shadow link tasks + +Shadow linking operates through specialized tasks that handle different aspects of replication. Each task corresponds to a configuration section in your shadow link setup and runs continuously to maintain synchronization with the source cluster. + +[tabs] +==== +Source Topic Sync:: ++ +-- +[#source-topic-sync-task] +The **Source Topic Sync task** manages topic discovery and metadata synchronization. This task periodically queries the source cluster to discover available topics, applies your configured topic filters to determine which topics should become shadow topics, and synchronizes topic properties between clusters. + +The task is controlled by the `topic_metadata_sync_options` configuration section, which includes: + +* **Auto-creation filters**: Determines which source topics automatically become shadow topics +* **Property synchronization**: Controls which topic properties replicate from source to shadow +* **Starting offset**: Sets where new shadow topics begin replication (earliest, latest, or timestamp-based) +* **Sync interval**: How frequently to check for new topics and property changes + +When this task discovers a new topic that matches your filters, it creates the corresponding shadow topic and begins replication from your configured starting offset. +-- + +Consumer Group Shadowing:: ++ +-- +[#consumer-group-shadowing-task] +The **Consumer Group Shadowing task** replicates consumer group offsets and membership information from the source cluster. This ensures that consumer applications can resume processing from the correct position after failover. + +The task is controlled by the `consumer_offset_sync_options` configuration section, which includes: + +* **Group filters**: Determines which consumer groups have their offsets replicated +* **Sync interval**: How frequently to synchronize consumer group offsets +* **Offset clamping**: Automatically adjusts replicated offsets to valid ranges on the shadow cluster + +This task runs on brokers that host the `__consumer_offsets` topic and continuously tracks consumer group coordinators to optimize offset synchronization. +-- + +Security Migrator:: ++ +-- +[#security-migrator-task] +The **Security Migrator task** replicates security policies, primarily ACLs (access control lists), from the source cluster to maintain consistent authorization across both environments. + +The task is controlled by the `security_sync_options` configuration section, which includes: + +* **ACL filters**: Determines which security policies replicate +* **Sync interval**: How frequently to synchronize security settings + +By default, all ACLs replicate to ensure your shadow cluster maintains the same security posture as your source cluster. +-- +==== + +=== Task status and monitoring + +Each task reports its status through the shadow link status API. Task states include: + +* **`ACTIVE`**: Task is running normally and performing synchronization +* **`PAUSED`**: Task has been manually paused through configuration +* **`FAULTED`**: Task encountered an error and requires attention +* **`NOT_RUNNING`**: Task is not currently executing +* **`LINK_UNAVAILABLE`**: Task cannot communicate with the source cluster + +You can pause individual tasks by setting the `paused` field to `true` in the corresponding configuration section. This allows you to selectively disable parts of the replication process without affecting the entire shadow link. + +For monitoring task health and troubleshooting task issues, see xref:manage:disaster-recovery/shadowing/monitor.adoc[Monitor Shadow Links]. + +== What gets replicated + +Shadowing replicates your topic data with complete fidelity, preserving all message records with their original offsets, timestamps, headers, and metadata. The partition structure remains identical between source and shadow clusters, ensuring applications can resume processing from the exact same position after failover. + +Consumer group data flows according to your group filters, replicating offsets and membership information for matched groups. ACLs replicate based on your security filters. Schema Registry data synchronizes schema definitions, versions, and compatibility settings. + +Partition count is always replicated to ensure the shadow topic matches the source topic's partition structure. + +=== Topic properties replication + +The <> handles topic property replication. For topic properties, Redpanda follows these replication rules: + +[cols="1,1,1"] + +|=== +|Never replicated |Always replicated |Always replicated + +(unless `exclude_default` is `true`) + +|`redpanda.remote.readreplica` +|`max.message.bytes` +|`compression.type` + +|`redpanda.remote.recovery` +|`cleanup.policy` +|`retention.bytes` + +|`redpanda.remote.allowgaps` +|`message.timestamp.type` +|`retention.ms` + +|`redpanda.virtual.cluster.id` +| +|`delete.retention.ms` + +|`redpanda.leaders.preference` +| +|`replication.factor` + +|`redpanda.cloud_topic.enabled` +| +|`min.compaction.lag.ms` + +| +| +|`max.compaction.lag.ms` +|=== + +To replicate additional topic properties, explicitly list them in `synced_shadow_topic_properties`. + +The filtering system you configure determines the precise scope of replication across all components, allowing you to balance comprehensive disaster recovery with operational efficiency. + == Best practices To ensure reliable disaster recovery with Shadowing: @@ -66,10 +183,10 @@ endif::[] Choose your implementation approach: -* **xref:./setup.adoc[Setup and Configuration]** - Initial shadow configuration, authentication, and topic selection -* **xref:./monitor.adoc[Monitoring and Operations]** - Health checks, lag monitoring, and operational procedures -* **xref:./failover.adoc[Planned Failover]** - Controlled disaster recovery testing and migrations -* **xref:./failover-runbook.adoc[Failover Runbook]** - Rapid disaster response procedures +* **xref:./setup.adoc[Setup and Configuration]**: Initial shadow configuration, authentication, and topic selection +* **xref:./monitor.adoc[Monitoring and Operations]**: Health checks, lag monitoring, and operational procedures +* **xref:./failover.adoc[Planned Failover]**: Controlled disaster recovery testing and migrations +* **xref:./failover-runbook.adoc[Failover Runbook]**: Rapid disaster response procedures ifndef::env-cloud[] [TIP] diff --git a/modules/manage/pages/disaster-recovery/shadowing/setup.adoc b/modules/manage/pages/disaster-recovery/shadowing/setup.adoc index d97e057f84..f73f2a660c 100644 --- a/modules/manage/pages/disaster-recovery/shadowing/setup.adoc +++ b/modules/manage/pages/disaster-recovery/shadowing/setup.adoc @@ -119,104 +119,6 @@ To set up Shadowing: * **Configure filters**: Define which topics, consumer groups, and ACLs should replicate by creating include/exclude patterns that match your disaster recovery requirements. See <>. * **Create a shadow link**: Establish the connection between clusters using `rpk`, the API, or Redpanda Console with authentication and network settings. See <>. -== Shadow link tasks - -Shadow linking operates through specialized tasks that handle different aspects of replication. Each task corresponds to a configuration section in your shadow link setup and runs continuously to maintain synchronization with the source cluster. - -[#source-topic-sync-task] -=== Source Topic Sync task - -The **Source Topic Sync task** manages topic discovery and metadata synchronization. This task periodically queries the source cluster to discover available topics, applies your configured topic filters to determine which topics should become shadow topics, and synchronizes topic properties between clusters. - -The task is controlled by the `topic_metadata_sync_options` configuration section, which includes: - -* **Auto-creation filters**: Determines which source topics automatically become shadow topics -* **Property synchronization**: Controls which topic properties replicate from source to shadow -* **Starting offset**: Sets where new shadow topics begin replication (earliest, latest, or timestamp-based) -* **Sync interval**: How frequently to check for new topics and property changes - -When this task discovers a new topic that matches your filters, it creates the corresponding shadow topic and begins replication from your configured starting offset. - -[#consumer-group-shadowing-task] -=== Consumer Group Shadowing task - -The **Consumer Group Shadowing task** replicates consumer group offsets and membership information from the source cluster. This ensures that consumer applications can resume processing from the correct position after failover. - -The task is controlled by the `consumer_offset_sync_options` configuration section, which includes: - -* **Group filters**: Determines which consumer groups have their offsets replicated -* **Sync interval**: How frequently to synchronize consumer group offsets -* **Offset clamping**: Automatically adjusts replicated offsets to valid ranges on the shadow cluster - -This task runs on brokers that host the `__consumer_offsets` topic and continuously tracks consumer group coordinators to optimize offset synchronization. - -[#security-migrator-task] -=== Security Migrator task - -The **Security Migrator task** replicates security policies, primarily ACLs (access control lists), from the source cluster to maintain consistent authorization across both environments. - -The task is controlled by the `security_sync_options` configuration section, which includes: - -* **ACL filters**: Determines which security policies replicate -* **Sync interval**: How frequently to synchronize security settings - -By default, all ACLs replicate to ensure your shadow cluster maintains the same security posture as your source cluster. - -=== Task status and monitoring - -Each task reports its status through the shadow link status API. Task states include: - -* **`ACTIVE`**: Task is running normally and performing synchronization -* **`PAUSED`**: Task has been manually paused through configuration -* **`FAULTED`**: Task encountered an error and requires attention -* **`NOT_RUNNING`**: Task is not currently executing -* **`LINK_UNAVAILABLE`**: Task cannot communicate with the source cluster - -You can pause individual tasks by setting the `paused` field to `true` in the corresponding configuration section. This allows you to selectively disable parts of the replication process without affecting the entire shadow link. - -For monitoring task health and troubleshooting task issues, see xref:manage:disaster-recovery/shadowing/monitor.adoc[Monitor Shadow Links]. - -== What gets replicated - -Shadowing replicates your topic data with complete fidelity, preserving all message records with their original offsets, timestamps, headers, and metadata. The partition structure remains identical between source and shadow clusters, ensuring applications can resume processing from the exact same position after failover. - -Consumer group data flows according to your group filters, replicating offsets and membership information for matched groups. ACLs replicate based on your security filters. Schema Registry data synchronizes schema definitions, versions, and compatibility settings. - -Partition count is always replicated to ensure the shadow topic matches the source topic's partition structure. - -=== Topic properties replication - -The <> handles topic property replication. For topic properties, Redpanda follows these replication rules: - -**Never replicated:** - -* `redpanda.remote.readreplica` -* `redpanda.remote.recovery` -* `redpanda.remote.allowgaps` -* `redpanda.virtual.cluster.id` -* `redpanda.leaders.preference` -* `redpanda.cloud_topic.enabled` - -**Always replicated:** - -* `max.message.bytes` -* `cleanup.policy` -* `message.timestamp.type` - -**Always replicated, unless you set `exclude_default` to `true`:** - -* `compression.type` -* `retention.bytes` -* `retention.ms` -* `delete.retention.ms` -* `replication.factor` -* `min.compaction.lag.ms` -* `max.compaction.lag.ms` - -To replicate additional topic properties, explicitly list them in `synced_shadow_topic_properties`. - -The filtering system you configure determines the precise scope of replication across all components, allowing you to balance comprehensive disaster recovery with operational efficiency. - == Set filters Filters determine which resources Shadowing automatically creates when establishing your shadow link. @@ -510,7 +412,9 @@ client_options: == Create a shadow link ifdef::env-cloud[] -You can establish a shadow link using either `rpk`, the Data Plane API, or the Redpanda Cloud UI. For example, to create a shadow link with the source cluster, run the following `rpk` command from the shadow cluster: +You can establish a shadow link using either `rpk`, the Data Plane API, or the Redpanda Cloud UI. + +To create a shadow link with the source cluster using `rpk`, run the following command from the shadow cluster: endif::[] ifndef::env-cloud[] @@ -526,7 +430,7 @@ For detailed command options, see xref:reference:rpk/rpk-shadow/rpk-shadow-creat == Update an existing shadow link -If you need to modify a shadow link configuration after creation, use the update command: +To modify a shadow link configuration after creation, run: [,bash] ---- From 6e8ac753d9f4a0552d80e971e723553a343ab37d Mon Sep 17 00:00:00 2001 From: micheleRP Date: Wed, 26 Nov 2025 12:49:14 -0700 Subject: [PATCH 09/20] rearranging setup --- .../shadowing/failover-runbook.adoc | 2 +- .../disaster-recovery/shadowing/setup.adoc | 240 +++++++++--------- 2 files changed, 120 insertions(+), 122 deletions(-) diff --git a/modules/manage/pages/disaster-recovery/shadowing/failover-runbook.adoc b/modules/manage/pages/disaster-recovery/shadowing/failover-runbook.adoc index 4aa57b1e7a..22595fc35d 100644 --- a/modules/manage/pages/disaster-recovery/shadowing/failover-runbook.adoc +++ b/modules/manage/pages/disaster-recovery/shadowing/failover-runbook.adoc @@ -88,7 +88,7 @@ Verify that the following conditions exist before proceeding with failover: * Topics should be in `ACTIVE` state (not `FAULTED`). * Replication lag should be reasonable for your RPO requirements. -**Understanding replication lag:** +**Understanding replication lag** Use xref:reference:rpk/rpk-shadow/rpk-shadow-status.adoc[`rpk shadow status`] to check lag, which shows the message count difference between source and shadow partitions: diff --git a/modules/manage/pages/disaster-recovery/shadowing/setup.adoc b/modules/manage/pages/disaster-recovery/shadowing/setup.adoc index f73f2a660c..c1f7d543e6 100644 --- a/modules/manage/pages/disaster-recovery/shadowing/setup.adoc +++ b/modules/manage/pages/disaster-recovery/shadowing/setup.adoc @@ -98,26 +98,109 @@ endif::[] == Set up Shadowing -[TIP] -==== -You can use `rpk` to generate a configuration template: +To set up Shadowing, you need to create a shadow link and configure filters to select which topics, consumer groups, and ACLs to replicate. + +ifdef::env-cloud[] +You can use the Redpanda Cloud UI, `rpk`, or the Data Plane API. +endif::[] + +ifndef::env-cloud[] +You can use Redpanda Console, `rpk`, or the Admin API. +endif::[] + +== Create a shadow link + +To create a shadow link with the source cluster using `rpk`, run the following command from the shadow cluster: [,bash] ---- -# Generate a sample configuration file with placeholder values -rpk shadow config generate -o shadow-config.yaml - -# Or generate a template with detailed field documentation -rpk shadow config generate --print-template -o shadow-config-template.yaml +rpk shadow create --config-file shadow-config.yaml ---- -This creates a complete YAML configuration file that you can customize for your environment. The template includes all available fields with comments explaining their purpose. +For detailed command options, see xref:reference:rpk/rpk-shadow/rpk-shadow-create.adoc[`rpk shadow create`]. + +==== Sample configuration file + +.Explore the configuration file +[%collapsible] ==== +[,yaml] +---- +# Sample ShadowLinkConfig YAML with all fields +name: # Unique name for this shadow link, example: "production-dr" +client_options: + bootstrap_servers: # Source cluster brokers to connect to + - : # Example: "prod-kafka-1.example.com:9092" + - : # Example: "prod-kafka-2.example.com:9092" + - : # Example: "prod-kafka-3.example.com:9092" + source_cluster_id: # Optional: Expected source cluster ID for validation, example: "prod-cluster-123" + + # TLS settings using file paths + tls_settings: + enabled: true # Enable TLS + tls_file_settings: + ca_path: # Path to CA certificate, example: "/etc/ssl/certs/ca.crt" + key_path: # Optional: Path to client private key, example: "/etc/ssl/private/client.key" + cert_path: # Optional: Path to client certificate, example: "/etc/ssl/certs/client.crt" + do_not_set_sni_hostname: false # Optional: Skip SNI hostname when using TLS (default: false) + + authentication_configuration: + scram_configuration: + username: # SASL/SCRAM username, example: "shadow-replication-user" + password: # SASL/SCRAM password, example: "secure-password-123" + scram_mechanism: SCRAM_SHA_256 # SCRAM mechanism: "SCRAM_SHA_256" or "SCRAM_SHA_512" + + # Connection tuning - adjust based on network characteristics + metadata_max_age_ms: 10000 # How often to refresh cluster metadata (default: 10000ms) + connection_timeout_ms: 1000 # Connection timeout (default: 1000ms, increase for high latency) + retry_backoff_ms: 100 # Backoff between retries (default: 100ms) + fetch_wait_max_ms: 500 # Max time to wait for fetch requests (default: 500ms) + fetch_min_bytes: 5242880 # Min bytes per fetch (default: 5MB) + fetch_max_bytes: 20971520 # Max bytes per fetch (default: 20MB) + fetch_partition_max_bytes: 1048576 # Max bytes per partition fetch (default: 1MB) + +topic_metadata_sync_options: + interval: 30s # How often to sync topic metadata (examples: "30s", "1m", "5m") + auto_create_shadow_topic_filters: # Filters for automatic topic creation + - pattern_type: LITERAL # Include all topics (wildcard) + filter_type: INCLUDE + name: '*' + - pattern_type: PREFIX # Exclude topics with specific prefix + filter_type: EXCLUDE + name: # Examples: "temp-", "test-", "debug-" + synced_shadow_topic_properties: # Additional topic properties to sync (beyond defaults) + - retention.ms # Topic retention time + - segment.ms # Segment roll time + exclude_default: false # Include default properties (compression, retention, etc.) + start_at_earliest: {} # Start from the beginning of source topics (default) + paused: false # Enable topic metadata synchronization + +consumer_offset_sync_options: + interval: 30s # How often to sync consumer group offsets + paused: false # Enable consumer offset synchronization + group_filters: # Filters for consumer groups to sync + - pattern_type: LITERAL + filter_type: INCLUDE + name: '*' # Include all consumer groups -To set up Shadowing: +security_sync_options: + interval: 30s # How often to sync security settings + paused: false # Enable security settings synchronization + acl_filters: # Filters for ACLs to sync + - resource_filter: + resource_type: TOPIC # Resource type: "TOPIC", "GROUP", "CLUSTER" + pattern_type: PREFIXED # Pattern type: "LITERAL", "PREFIX", "PREFIXED" + name: # Examples: "prod-", "app-data-" + access_filter: + principal: User: # Principal name, example: "User:app-service" + operation: ANY # Operation: "READ", "WRITE", "CREATE", "DELETE", "ALTER", "DESCRIBE", "ANY" + permission_type: ALLOW # Permission: "ALLOW" or "DENY" + host: '*' # Host pattern, examples: "*", "10.0.0.0/8", "app-server.example.com" -* **Configure filters**: Define which topics, consumer groups, and ACLs should replicate by creating include/exclude patterns that match your disaster recovery requirements. See <>. -* **Create a shadow link**: Establish the connection between clusters using `rpk`, the API, or Redpanda Console with authentication and network settings. See <>. +schema_registry_sync_options: # Schema Registry synchronization options + shadow_schema_registry_topic: {} # Enable byte-for-byte _schemas topic replication +---- +==== == Set filters @@ -127,6 +210,22 @@ Topic filters select which topics Shadowing automatically creates as shadow topi Consumer group and ACL filters control which groups and security policies replicate to maintain application functionality. +[TIP] +==== +You can use `rpk` to generate a configuration template: + +[,bash] +---- +# Generate a sample configuration file with placeholder values +rpk shadow config generate -o shadow-config.yaml + +# Or generate a template with detailed field documentation +rpk shadow config generate --print-template -o shadow-config-template.yaml +---- + +This creates a complete YAML configuration file that you can customize for your environment. The template includes all available fields with comments explaining their purpose. +==== + === Filter types and patterns Each filter uses two key settings: @@ -142,9 +241,9 @@ Each filter uses two key settings: Redpanda processes filters in the order you define them with EXCLUDE filters taking precedence. Design your filter lists carefully: -1. **Exclude filters win**: If any EXCLUDE filter matches a resource, it is excluded regardless of INCLUDE filters -2. **Order matters for INCLUDE filters**: Among INCLUDE filters, the first match determines the result -3. **Default behavior**: Items that don't match any filter are excluded from replication +1. **Exclude filters win**: If any EXCLUDE filter matches a resource, it is excluded regardless of INCLUDE filters. +2. **Order matters for INCLUDE filters**: Among INCLUDE filters, the first match determines the result. +3. **Default behavior**: Items that don't match any filter are excluded from replication. === Common filtering patterns @@ -219,7 +318,7 @@ Redpanda system topics have the following specific filtering restrictions: === ACL filtering -ACLs are replicated by the <>. This is recommended to ensure that your shadow cluster has the same permissions as your source cluster. To configure ACL filters: +ACLs are replicated by the xref:manage:disaster-recovery/shadowing/overview.adoc#shadow-link-tasks[Security Migrator task]. This is recommended to ensure that your shadow cluster has the same permissions as your source cluster. To configure ACL filters: [,yaml] ---- @@ -249,7 +348,7 @@ security_sync_options: === Consumer group filtering and behavior -Consumer group filters determine which consumer groups have their offsets replicated to the shadow cluster by the <>. +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]. Offset replication operates selectively within each consumer group. Only committed offsets for active shadow topics are synchronized, even if the consumer group has offsets for additional topics that aren't being shadowed. For example, if consumer group "app-consumers" has committed offsets for "orders", "payments", and "inventory" topics, but only "orders" is an active shadow topic, then only the "orders" offsets will be replicated to the shadow cluster. @@ -267,7 +366,7 @@ consumer_offset_sync_options: name: test-consumer-group # Exclude specific test groups ---- -**Important consumer group considerations:** +**Important consumer group considerations** **Avoid name conflicts:** If you plan to consume data from the shadow cluster, do not use the same consumer group names as those used on the source cluster. While this won't break shadow linking, it can impact your RPO/RTO because conflicting group names may interfere with offset replication and consumer resumption during disaster recovery. @@ -275,7 +374,7 @@ consumer_offset_sync_options: === Starting offset for new shadow topics -When the <> creates a shadow topic for the first time, you can control where replication begins on the source topic. This setting only applies to empty shadow partitions and is crucial for disaster recovery planning. Changing this configuration only affects new shadow topics, existing shadow topics continue replicating from their current position. +When the xref:manage:disaster-recovery/shadowing/overview.adoc#shadow-link-tasks[Source Topic Sync task] creates a shadow topic for the first time, you can control where replication begins on the source topic. This setting only applies to empty shadow partitions and is crucial for disaster recovery planning. Changing this configuration only affects new shadow topics, existing shadow topics continue replicating from their current position. [,yaml] ---- @@ -409,24 +508,6 @@ client_options: fetch_partition_max_bytes: 1048576 # Default 1MB, maximum bytes to fetch per partition ---- -== Create a shadow link - -ifdef::env-cloud[] -You can establish a shadow link using either `rpk`, the Data Plane API, or the Redpanda Cloud UI. - -To create a shadow link with the source cluster using `rpk`, run the following command from the shadow cluster: -endif::[] - -ifndef::env-cloud[] -You can establish a shadow link using either xref:get-started:rpk/index.adoc[`rpk`], the Admin API, or xref:console:index.adoc[Redpanda Console]. For example, to create a shadow link with the source cluster, run the following `rpk` command from the shadow cluster: -endif::[] - -[,bash] ----- -rpk shadow create --config-file shadow-config.yaml ----- - -For detailed command options, see xref:reference:rpk/rpk-shadow/rpk-shadow-create.adoc[`rpk shadow create`]. == Update an existing shadow link @@ -443,90 +524,7 @@ This opens your default editor to modify the shadow link configuration. Only cha [TIP] ==== -Use xref:get-started:config-rpk-profile.adoc[`rpk profile`] to save your cluster connection details and credentials for both source and shadow clusters, allowing you to easily switch between the two configurations. -==== - -==== Sample configuration file - -.Explore the configuration file -[%collapsible] -==== -[,yaml] ----- -# Sample ShadowLinkConfig YAML with all fields -name: # Unique name for this shadow link, example: "production-dr" -client_options: - bootstrap_servers: # Source cluster brokers to connect to - - : # Example: "prod-kafka-1.example.com:9092" - - : # Example: "prod-kafka-2.example.com:9092" - - : # Example: "prod-kafka-3.example.com:9092" - source_cluster_id: # Optional: Expected source cluster ID for validation, example: "prod-cluster-123" - - # TLS settings using file paths - tls_settings: - enabled: true # Enable TLS - tls_file_settings: - ca_path: # Path to CA certificate, example: "/etc/ssl/certs/ca.crt" - key_path: # Optional: Path to client private key, example: "/etc/ssl/private/client.key" - cert_path: # Optional: Path to client certificate, example: "/etc/ssl/certs/client.crt" - do_not_set_sni_hostname: false # Optional: Skip SNI hostname when using TLS (default: false) - - authentication_configuration: - scram_configuration: - username: # SASL/SCRAM username, example: "shadow-replication-user" - password: # SASL/SCRAM password, example: "secure-password-123" - scram_mechanism: SCRAM_SHA_256 # SCRAM mechanism: "SCRAM_SHA_256" or "SCRAM_SHA_512" - - # Connection tuning - adjust based on network characteristics - metadata_max_age_ms: 10000 # How often to refresh cluster metadata (default: 10000ms) - connection_timeout_ms: 1000 # Connection timeout (default: 1000ms, increase for high latency) - retry_backoff_ms: 100 # Backoff between retries (default: 100ms) - fetch_wait_max_ms: 500 # Max time to wait for fetch requests (default: 500ms) - fetch_min_bytes: 5242880 # Min bytes per fetch (default: 5MB) - fetch_max_bytes: 20971520 # Max bytes per fetch (default: 20MB) - fetch_partition_max_bytes: 1048576 # Max bytes per partition fetch (default: 1MB) - -topic_metadata_sync_options: - interval: 30s # How often to sync topic metadata (examples: "30s", "1m", "5m") - auto_create_shadow_topic_filters: # Filters for automatic topic creation - - pattern_type: LITERAL # Include all topics (wildcard) - filter_type: INCLUDE - name: '*' - - pattern_type: PREFIX # Exclude topics with specific prefix - filter_type: EXCLUDE - name: # Examples: "temp-", "test-", "debug-" - synced_shadow_topic_properties: # Additional topic properties to sync (beyond defaults) - - retention.ms # Topic retention time - - segment.ms # Segment roll time - exclude_default: false # Include default properties (compression, retention, etc.) - start_at_earliest: {} # Start from the beginning of source topics (default) - paused: false # Enable topic metadata synchronization - -consumer_offset_sync_options: - interval: 30s # How often to sync consumer group offsets - paused: false # Enable consumer offset synchronization - group_filters: # Filters for consumer groups to sync - - pattern_type: LITERAL - filter_type: INCLUDE - name: '*' # Include all consumer groups - -security_sync_options: - interval: 30s # How often to sync security settings - paused: false # Enable security settings synchronization - acl_filters: # Filters for ACLs to sync - - resource_filter: - resource_type: TOPIC # Resource type: "TOPIC", "GROUP", "CLUSTER" - pattern_type: PREFIXED # Pattern type: "LITERAL", "PREFIX", "PREFIXED" - name: # Examples: "prod-", "app-data-" - access_filter: - principal: User: # Principal name, example: "User:app-service" - operation: ANY # Operation: "READ", "WRITE", "CREATE", "DELETE", "ALTER", "DESCRIBE", "ANY" - permission_type: ALLOW # Permission: "ALLOW" or "DENY" - host: '*' # Host pattern, examples: "*", "10.0.0.0/8", "app-server.example.com" - -schema_registry_sync_options: # Schema Registry synchronization options - shadow_schema_registry_topic: {} # Enable byte-for-byte _schemas topic replication ----- +Use xref:get-started:config-rpk-profile.adoc[`rpk profile`] to save your cluster connection details and credentials for both source and shadow clusters. This allows you to easily switch between the two configurations. ==== // end::single-source[] From 582e395c1bfbac081969b111d83380670afaa964 Mon Sep 17 00:00:00 2001 From: micheleRP Date: Mon, 1 Dec 2025 09:59:51 -0700 Subject: [PATCH 10/20] byoc/dedicated only --- .../shadowing/failover-runbook.adoc | 5 +++++ .../disaster-recovery/shadowing/failover.adoc | 4 ++++ .../disaster-recovery/shadowing/overview.adoc | 4 ++++ .../pages/disaster-recovery/shadowing/setup.adoc | 16 ++++++++++------ 4 files changed, 23 insertions(+), 6 deletions(-) diff --git a/modules/manage/pages/disaster-recovery/shadowing/failover-runbook.adoc b/modules/manage/pages/disaster-recovery/shadowing/failover-runbook.adoc index 22595fc35d..dd2421a270 100644 --- a/modules/manage/pages/disaster-recovery/shadowing/failover-runbook.adoc +++ b/modules/manage/pages/disaster-recovery/shadowing/failover-runbook.adoc @@ -5,6 +5,7 @@ :page-categories: Management, High Availability, Disaster Recovery, Emergency Response // tag::single-source[] + ifndef::env-cloud[] [NOTE] ==== @@ -20,6 +21,10 @@ This guide provides step-by-step procedures for emergency failover when your pri This is an emergency procedure. For planned failover testing or day-to-day shadow link management, see xref:./failover.adoc[]. Ensure you have completed the xref:manage:disaster-recovery/shadowing/overview.adoc#disaster-readiness-checklist[disaster readiness checklist] before an emergency occurs. ==== +ifdef::env-cloud[] +NOTE: Shadowing is supported on BYOC and Dedicated clusters running Redpanda version 25.3 and later. +endif::[] + == Emergency failover procedure Follow these steps during an active disaster: diff --git a/modules/manage/pages/disaster-recovery/shadowing/failover.adoc b/modules/manage/pages/disaster-recovery/shadowing/failover.adoc index 1350b6becb..b79ae43162 100644 --- a/modules/manage/pages/disaster-recovery/shadowing/failover.adoc +++ b/modules/manage/pages/disaster-recovery/shadowing/failover.adoc @@ -15,6 +15,10 @@ Failover is the process of modifying shadow topics or an entire shadow cluster f include::shared:partial$emergency-shadowing-callout.adoc[] +ifdef::env-cloud[] +NOTE: Shadowing is supported on BYOC and Dedicated clusters running Redpanda version 25.3 and later. +endif::[] + == Failover behavior When you initiate failover, Redpanda performs the following operations: diff --git a/modules/manage/pages/disaster-recovery/shadowing/overview.adoc b/modules/manage/pages/disaster-recovery/shadowing/overview.adoc index e2949a8979..86e17138fa 100644 --- a/modules/manage/pages/disaster-recovery/shadowing/overview.adoc +++ b/modules/manage/pages/disaster-recovery/shadowing/overview.adoc @@ -5,6 +5,10 @@ :page-aliases: deploy:redpanda/manual/disaster-recovery/shadowing/overview.adoc // tag::single-source[] +ifdef::env-cloud[] +NOTE: Shadowing is supported on BYOC and Dedicated clusters running Redpanda version 25.3 and later. +endif::[] + ifndef::env-cloud[] [NOTE] ==== diff --git a/modules/manage/pages/disaster-recovery/shadowing/setup.adoc b/modules/manage/pages/disaster-recovery/shadowing/setup.adoc index c1f7d543e6..ee4c3c53ac 100644 --- a/modules/manage/pages/disaster-recovery/shadowing/setup.adoc +++ b/modules/manage/pages/disaster-recovery/shadowing/setup.adoc @@ -13,6 +13,11 @@ ifdef::env-cloud[] include::shared:partial$shadow-link-cloud-tip.adoc[] endif::[] +[TIP] +==== +Deploy clusters in different geographic regions to protect against regional disasters. +==== + == Prerequisites ifndef::env-cloud[] @@ -24,18 +29,17 @@ endif::[] === License and cluster requirements -- Both clusters must be running Redpanda v25.3 or later. +ifdef::env-cloud[] +Shadowing is supported on BYOC and Dedicated clusters running Redpanda version 25.3 and later. +endif::[] + ifndef::env-cloud[] +- Both clusters must be running Redpanda v25.3 or later. - If you use Redpanda Console, ensure that it is running v3.30 or later. - You must have xref:get-started:licensing/overview.adoc[Enterprise Edition] licenses on both clusters. endif::[] -[TIP] -==== -Deploy clusters in different geographic regions to protect against regional disasters. -==== - === Cluster properties Both source and shadow clusters must have the xref:reference:properties/cluster-properties.adoc#enable_shadow_linking[`enable_shadow_linking`] cluster property set to `true`. From 614e5c5a5bc19bfda4146978a20c8fe66d8e1e4c Mon Sep 17 00:00:00 2001 From: micheleRP Date: Mon, 1 Dec 2025 13:34:55 -0700 Subject: [PATCH 11/20] conditionalizing --- .../pages/disaster-recovery/shadowing/failover.adoc | 8 ++++++++ .../pages/disaster-recovery/shadowing/overview.adoc | 8 ++++++-- .../manage/pages/disaster-recovery/shadowing/setup.adoc | 6 +++--- modules/shared/partials/shadow-link-cloud-tip.adoc | 2 +- modules/shared/partials/shadow-link-management-tip.adoc | 2 +- 5 files changed, 19 insertions(+), 7 deletions(-) diff --git a/modules/manage/pages/disaster-recovery/shadowing/failover.adoc b/modules/manage/pages/disaster-recovery/shadowing/failover.adoc index b79ae43162..105d65235f 100644 --- a/modules/manage/pages/disaster-recovery/shadowing/failover.adoc +++ b/modules/manage/pages/disaster-recovery/shadowing/failover.adoc @@ -13,6 +13,14 @@ endif::[] Failover is the process of modifying shadow topics or an entire shadow cluster from read-only replicas to fully writable resources, and ceasing replication from the source cluster. You can fail over individual topics for selective workload migration or fail over the entire cluster for comprehensive disaster recovery. This critical operation transforms your shadow resources into operational production assets, allowing you to redirect application traffic when the source cluster becomes unavailable. +ifdef::env-cloud[] +You can configure failover using the Redpanda Cloud UI, `rpk`, or the Data Plane API. +endif::[] + +ifndef::env-cloud[] +You can configure failover using Redpanda Console, `rpk`, or the Admin API. +endif::[] + include::shared:partial$emergency-shadowing-callout.adoc[] ifdef::env-cloud[] diff --git a/modules/manage/pages/disaster-recovery/shadowing/overview.adoc b/modules/manage/pages/disaster-recovery/shadowing/overview.adoc index 86e17138fa..f17c724aa4 100644 --- a/modules/manage/pages/disaster-recovery/shadowing/overview.adoc +++ b/modules/manage/pages/disaster-recovery/shadowing/overview.adoc @@ -34,7 +34,11 @@ Shadowing replicates: Shadowing addresses enterprise disaster recovery requirements driven by regulatory compliance and business continuity needs. Organizations typically want to minimize both recovery time objective (RTO) and recovery point objective (RPO), and Shadowing asynchronous replication helps you achieve both goals by reducing data loss during regional outages and enabling rapid application recovery. -The architecture follows an active-passive pattern. The source cluster processes all production traffic while the shadow cluster remains in read-only mode, continuously receiving updates. If a disaster occurs, you can failover the shadow topics using the Admin API or `rpk`, making them fully writable. At that point, you can redirect your applications to the shadow cluster, which becomes the new production cluster. +The architecture follows an active-passive pattern. The source cluster processes all production traffic while the shadow cluster remains in read-only mode, continuously receiving updates. If a disaster occurs, you can failover the shadow topics using the +ifndef::env-cloud[Admin API] +ifdef::env-cloud[Data Plane API] +or `rpk`, making them fully writable. At that point, you can redirect your applications to the shadow cluster, which becomes the new production cluster. + ifdef::env-cloud[] Shadowing complements Redpanda's existing availability and recovery capabilities. High availability actively protects your day-to-day operations, handling reads and writes seamlessly during node or availability zone failures within a region. Shadowing is your safety net for catastrophic regional disasters. Shadowing delivers near real-time, cross-region replication for mission-critical applications that require rapid failover with minimal data loss. @@ -120,7 +124,7 @@ Each task reports its status through the shadow link status API. Task states inc You can pause individual tasks by setting the `paused` field to `true` in the corresponding configuration section. This allows you to selectively disable parts of the replication process without affecting the entire shadow link. -For monitoring task health and troubleshooting task issues, see xref:manage:disaster-recovery/shadowing/monitor.adoc[Monitor Shadow Links]. +For monitoring task health and troubleshooting task issues, see xref:manage:disaster-recovery/shadowing/monitor.adoc[Monitor Shadowing]. == What gets replicated diff --git a/modules/manage/pages/disaster-recovery/shadowing/setup.adoc b/modules/manage/pages/disaster-recovery/shadowing/setup.adoc index ee4c3c53ac..5b17132413 100644 --- a/modules/manage/pages/disaster-recovery/shadowing/setup.adoc +++ b/modules/manage/pages/disaster-recovery/shadowing/setup.adoc @@ -402,11 +402,11 @@ topic_metadata_sync_options: **Starting offset options:** -* **`earliest`** (default): Replicates all existing data from the source topic. Use this for complete disaster recovery where you need full data history. +* **`earliest`** (default): This replicates all existing data from the source topic. Use this for complete disaster recovery where you need full data history. -* **`latest`**: Starts replication from the current end of the source topic, skipping existing data. Use this when you only need new data for disaster recovery and want to minimize initial replication time. +* **`latest`**: This starts replication from the current end of the source topic, skipping existing data. Use this when you only need new data for disaster recovery and want to minimize initial replication time. -* **`timestamp`**: Starts replication from the first record with a timestamp at or after the specified time. Use this for point-in-time disaster recovery scenarios. +* **`timestamp`**: This starts replication from the first record with a timestamp at or after the specified time. Use this for point-in-time disaster recovery scenarios. [IMPORTANT] ==== diff --git a/modules/shared/partials/shadow-link-cloud-tip.adoc b/modules/shared/partials/shadow-link-cloud-tip.adoc index 77eff27d60..d6eb75ea90 100644 --- a/modules/shared/partials/shadow-link-cloud-tip.adoc +++ b/modules/shared/partials/shadow-link-cloud-tip.adoc @@ -1 +1 @@ -You can create and manage shadow links using `rpk`, the Redpanda Cloud UI, or the Data Plane API, giving you flexibility in how you interact with your disaster recovery infrastructure. \ No newline at end of file +You can create and manage shadow links with the Redpanda Cloud UI, the Data Plane API, or `rpk`, giving you flexibility in how you interact with your disaster recovery infrastructure. \ No newline at end of file diff --git a/modules/shared/partials/shadow-link-management-tip.adoc b/modules/shared/partials/shadow-link-management-tip.adoc index 39d999b1fa..273072f8e6 100644 --- a/modules/shared/partials/shadow-link-management-tip.adoc +++ b/modules/shared/partials/shadow-link-management-tip.adoc @@ -1 +1 @@ -You can create and manage shadow links using xref:get-started:rpk/index.adoc[`rpk`], xref:console:index.adoc[Redpanda Console], or the link:https://docs.redpanda.com/api/doc/admin/v2/[Admin API v2^], giving you flexibility in how you interact with your disaster recovery infrastructure. \ No newline at end of file +You can create and manage shadow links with the xref:console:index.adoc[Redpanda Console], the link:https://docs.redpanda.com/api/doc/admin/v2/[Admin API v2^], or xref:get-started:rpk/index.adoc[`rpk`], giving you flexibility in how you interact with your disaster recovery infrastructure. \ No newline at end of file From 043e1663806349467679b4492fe49b29967711d6 Mon Sep 17 00:00:00 2001 From: micheleRP Date: Mon, 1 Dec 2025 16:31:38 -0700 Subject: [PATCH 12/20] change Configure Failover to Failover --- modules/ROOT/nav.adoc | 2 +- .../manage/pages/disaster-recovery/shadowing/failover.adoc | 6 +++--- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc index e96b68c595..eb3417ccb3 100644 --- a/modules/ROOT/nav.adoc +++ b/modules/ROOT/nav.adoc @@ -200,7 +200,7 @@ **** xref:manage:disaster-recovery/shadowing/overview.adoc[Overview] **** xref:manage:disaster-recovery/shadowing/setup.adoc[Configure Shadowing] **** xref:manage:disaster-recovery/shadowing/monitor.adoc[Monitor Shadowing] -**** xref:manage:disaster-recovery/shadowing/failover.adoc[Configure Failover] +**** xref:manage:disaster-recovery/shadowing/failover.adoc[Failover] **** xref:manage:disaster-recovery/shadowing/failover-runbook.adoc[Failover Runbook] *** xref:manage:disaster-recovery/whole-cluster-restore.adoc[Whole Cluster Restore] *** xref:manage:disaster-recovery/topic-recovery.adoc[Topic Recovery] diff --git a/modules/manage/pages/disaster-recovery/shadowing/failover.adoc b/modules/manage/pages/disaster-recovery/shadowing/failover.adoc index 105d65235f..a596a4c28a 100644 --- a/modules/manage/pages/disaster-recovery/shadowing/failover.adoc +++ b/modules/manage/pages/disaster-recovery/shadowing/failover.adoc @@ -1,4 +1,4 @@ -= Configure Failover += Failover :description: Learn how failover can transform shadow topics into fully writable resources during disasters. :page-categories: Management, High Availability, Disaster Recovery :page-aliases: deploy:redpanda/manual/disaster-recovery/shadowing/failover.adoc @@ -14,11 +14,11 @@ endif::[] Failover is the process of modifying shadow topics or an entire shadow cluster from read-only replicas to fully writable resources, and ceasing replication from the source cluster. You can fail over individual topics for selective workload migration or fail over the entire cluster for comprehensive disaster recovery. This critical operation transforms your shadow resources into operational production assets, allowing you to redirect application traffic when the source cluster becomes unavailable. ifdef::env-cloud[] -You can configure failover using the Redpanda Cloud UI, `rpk`, or the Data Plane API. +You can failover topics using the Redpanda Cloud UI, `rpk`, or the Data Plane API. endif::[] ifndef::env-cloud[] -You can configure failover using Redpanda Console, `rpk`, or the Admin API. +You can failover topics using Redpanda Console, `rpk`, or the Admin API. endif::[] include::shared:partial$emergency-shadowing-callout.adoc[] From 763f4da5ae69bb226ce1e963a7e4f73739eaee55 Mon Sep 17 00:00:00 2001 From: micheleRP Date: Mon, 1 Dec 2025 17:56:28 -0700 Subject: [PATCH 13/20] incorporate Trevor's review feedback --- .../disaster-recovery/shadowing/failover.adoc | 4 +-- .../disaster-recovery/shadowing/monitor.adoc | 27 ++++++------------- .../disaster-recovery/shadowing/setup.adoc | 20 +++++++------- 3 files changed, 20 insertions(+), 31 deletions(-) diff --git a/modules/manage/pages/disaster-recovery/shadowing/failover.adoc b/modules/manage/pages/disaster-recovery/shadowing/failover.adoc index a596a4c28a..ebe82a596a 100644 --- a/modules/manage/pages/disaster-recovery/shadowing/failover.adoc +++ b/modules/manage/pages/disaster-recovery/shadowing/failover.adoc @@ -14,11 +14,11 @@ endif::[] Failover is the process of modifying shadow topics or an entire shadow cluster from read-only replicas to fully writable resources, and ceasing replication from the source cluster. You can fail over individual topics for selective workload migration or fail over the entire cluster for comprehensive disaster recovery. This critical operation transforms your shadow resources into operational production assets, allowing you to redirect application traffic when the source cluster becomes unavailable. ifdef::env-cloud[] -You can failover topics using the Redpanda Cloud UI, `rpk`, or the Data Plane API. +You can failover a shadow link using the Redpanda Cloud UI, `rpk`, or the Data Plane API. endif::[] ifndef::env-cloud[] -You can failover topics using Redpanda Console, `rpk`, or the Admin API. +You can failover a shadow link using Redpanda Console, `rpk`, or the Admin API. endif::[] include::shared:partial$emergency-shadowing-callout.adoc[] diff --git a/modules/manage/pages/disaster-recovery/shadowing/monitor.adoc b/modules/manage/pages/disaster-recovery/shadowing/monitor.adoc index bb827283f2..804fa07236 100644 --- a/modules/manage/pages/disaster-recovery/shadowing/monitor.adoc +++ b/modules/manage/pages/disaster-recovery/shadowing/monitor.adoc @@ -17,41 +17,30 @@ include::shared:partial$emergency-shadowing-callout.adoc[] == Status commands -List existing shadow links: +To list existing shadow links, run: [,bash] ---- rpk shadow list ---- -View shadow link configuration details: +To view shadow link configuration details, run: [,bash] ---- rpk shadow describe ---- -For detailed command options, see xref:reference:rpk/rpk-shadow/rpk-shadow-list.adoc[`rpk shadow list`] and xref:reference:rpk/rpk-shadow/rpk-shadow-describe.adoc[`rpk shadow describe`]. +For detailed command options, see xref:reference:rpk/rpk-shadow/rpk-shadow-list.adoc[`rpk shadow list`] and xref:reference:rpk/rpk-shadow/rpk-shadow-describe.adoc[`rpk shadow describe`]. This command shows the complete configuration of the shadow link, including connection settings, filters, and synchronization options. -This command shows the complete configuration of the shadow link, including connection settings, filters, and synchronization options. - -Check your shadow link status to ensure proper operation: - -[,bash] ----- -rpk shadow status ----- - -**Status command options:** +To check your shadow link status to ensure proper operation, run: [,bash] ---- rpk shadow status ---- -For troubleshooting specific issues, you can use command options to show individual status sections. See xref:reference:rpk/rpk-shadow/rpk-shadow-status.adoc[`rpk shadow status`] for available status options. - -The status output includes: +For troubleshooting specific issues, you can use command options to show individual status sections. See xref:reference:rpk/rpk-shadow/rpk-shadow-status.adoc[`rpk shadow status`] for available status options. The status output includes: * **Shadow link state**: Overall operational state (`ACTIVE`). * **Individual topic states**: Current state of each replicated topic (`ACTIVE`, `FAULTED`, `FAILING_OVER`, `FAILED_OVER`). @@ -61,7 +50,7 @@ The status output includes: [[shadow-link-metrics]] == Metrics -Shadowing provides comprehensive metrics to track replication performance and health: +Shadowing provides comprehensive metrics to track replication performance and health with the xref:reference:public-metrics-reference.adoc[`public_metrics`] endpoint. [cols="1,1,2"] |=== @@ -113,9 +102,9 @@ rpk shadow list | grep -v "ACTIVE" || echo "All shadow links healthy" rpk shadow status | grep -E "LAG|Lag" ---- -=== Alert thresholds +=== Alert conditions -Configure monitoring alerts for: +Configure monitoring alerts for following conditions, which indicate problems with Shadowing: * **High replication lag**: When `redpanda_shadow_link_shadow_lag` exceeds your RPO requirements * **Connection errors**: When `redpanda_shadow_link_client_errors` increases rapidly diff --git a/modules/manage/pages/disaster-recovery/shadowing/setup.adoc b/modules/manage/pages/disaster-recovery/shadowing/setup.adoc index 5b17132413..d36d4eadda 100644 --- a/modules/manage/pages/disaster-recovery/shadowing/setup.adoc +++ b/modules/manage/pages/disaster-recovery/shadowing/setup.adoc @@ -114,16 +114,7 @@ endif::[] == Create a shadow link -To create a shadow link with the source cluster using `rpk`, run the following command from the shadow cluster: - -[,bash] ----- -rpk shadow create --config-file shadow-config.yaml ----- - -For detailed command options, see xref:reference:rpk/rpk-shadow/rpk-shadow-create.adoc[`rpk shadow create`]. - -==== Sample configuration file +Any cluster can create a shadow link to a source cluster. When you create a shadow link with `rpk` or the API, you provide a YAML configuration file that defines connection settings, filters, and synchronization options. .Explore the configuration file [%collapsible] @@ -206,6 +197,15 @@ schema_registry_sync_options: # Schema Registry synchronization options ---- ==== +To create a shadow link with the source cluster using `rpk`, run the following command from the shadow cluster: + +[,bash] +---- +rpk shadow create --config-file shadow-config.yaml +---- + +For detailed command options, see xref:reference:rpk/rpk-shadow/rpk-shadow-create.adoc[`rpk shadow create`]. + == Set filters Filters determine which resources Shadowing automatically creates when establishing your shadow link. From 6c97ab7c7e1566d48893bc53ab328878c0effba2 Mon Sep 17 00:00:00 2001 From: micheleRP Date: Mon, 1 Dec 2025 18:10:47 -0700 Subject: [PATCH 14/20] minor edit --- modules/manage/pages/disaster-recovery/shadowing/setup.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/modules/manage/pages/disaster-recovery/shadowing/setup.adoc b/modules/manage/pages/disaster-recovery/shadowing/setup.adoc index d36d4eadda..50212d2c46 100644 --- a/modules/manage/pages/disaster-recovery/shadowing/setup.adoc +++ b/modules/manage/pages/disaster-recovery/shadowing/setup.adoc @@ -105,11 +105,11 @@ endif::[] To set up Shadowing, you need to create a shadow link and configure filters to select which topics, consumer groups, and ACLs to replicate. ifdef::env-cloud[] -You can use the Redpanda Cloud UI, `rpk`, or the Data Plane API. +You can set up Shadowing with the Redpanda Cloud UI, `rpk`, or the Data Plane API. endif::[] ifndef::env-cloud[] -You can use Redpanda Console, `rpk`, or the Admin API. +You can set up Shadowing with Redpanda Console, `rpk`, or the Admin API. endif::[] == Create a shadow link From 841a5a601f6fd751033e29213be9eb608418ec6b Mon Sep 17 00:00:00 2001 From: micheleRP Date: Mon, 1 Dec 2025 19:16:59 -0700 Subject: [PATCH 15/20] move tip next to sample config file --- .../disaster-recovery/shadowing/setup.adoc | 34 +++++++++---------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/modules/manage/pages/disaster-recovery/shadowing/setup.adoc b/modules/manage/pages/disaster-recovery/shadowing/setup.adoc index 50212d2c46..dab8c61e91 100644 --- a/modules/manage/pages/disaster-recovery/shadowing/setup.adoc +++ b/modules/manage/pages/disaster-recovery/shadowing/setup.adoc @@ -114,7 +114,23 @@ endif::[] == Create a shadow link -Any cluster can create a shadow link to a source cluster. When you create a shadow link with `rpk` or the API, you provide a YAML configuration file that defines connection settings, filters, and synchronization options. +Any cluster can create a shadow link to a source cluster. When you create a shadow link with `rpk` or the API, you need to provide a YAML configuration file that defines connection settings, filters, and synchronization options. + +[TIP] +==== +You can use `rpk` to generate a configuration template: + +[,bash] +---- +# Generate a sample configuration file with placeholder values +rpk shadow config generate -o shadow-config.yaml + +# Or generate a template with detailed field documentation +rpk shadow config generate --print-template -o shadow-config-template.yaml +---- + +This creates a complete YAML configuration file that you can customize for your environment. The template includes all available fields with comments explaining their purpose. +==== .Explore the configuration file [%collapsible] @@ -214,22 +230,6 @@ Topic filters select which topics Shadowing automatically creates as shadow topi Consumer group and ACL filters control which groups and security policies replicate to maintain application functionality. -[TIP] -==== -You can use `rpk` to generate a configuration template: - -[,bash] ----- -# Generate a sample configuration file with placeholder values -rpk shadow config generate -o shadow-config.yaml - -# Or generate a template with detailed field documentation -rpk shadow config generate --print-template -o shadow-config-template.yaml ----- - -This creates a complete YAML configuration file that you can customize for your environment. The template includes all available fields with comments explaining their purpose. -==== - === Filter types and patterns Each filter uses two key settings: From d8e0bbc4b992cb0e3cab73c356cea2568d2bc423 Mon Sep 17 00:00:00 2001 From: micheleRP Date: Mon, 1 Dec 2025 19:19:01 -0700 Subject: [PATCH 16/20] remove disaster readiness checklist from overview --- .../pages/disaster-recovery/shadowing/overview.adoc | 10 ---------- 1 file changed, 10 deletions(-) diff --git a/modules/manage/pages/disaster-recovery/shadowing/overview.adoc b/modules/manage/pages/disaster-recovery/shadowing/overview.adoc index f17c724aa4..1c484b40ce 100644 --- a/modules/manage/pages/disaster-recovery/shadowing/overview.adoc +++ b/modules/manage/pages/disaster-recovery/shadowing/overview.adoc @@ -210,16 +210,6 @@ include::shared:partial$shadow-link-cloud-tip.adoc[] ==== endif::[] -== Disaster readiness checklist - -Before a disaster occurs, ensure you have: - -[%interactive] -* [ ] Access to shadow cluster administrative credentials -* [ ] Shadow link names and configuration details, and networking documented -* [ ] Application connection strings for the shadow cluster prepared -* [ ] Tested failover procedures in a non-production environment - == Next steps After setting up Shadowing for your Redpanda clusters, consider these additional steps: From f48eefdc6f75e75a49c20c079c29795512aae28b Mon Sep 17 00:00:00 2001 From: micheleRP Date: Mon, 1 Dec 2025 19:27:18 -0700 Subject: [PATCH 17/20] remove duplicated content --- .../pages/disaster-recovery/shadowing/setup.adoc | 15 ++------------- 1 file changed, 2 insertions(+), 13 deletions(-) diff --git a/modules/manage/pages/disaster-recovery/shadowing/setup.adoc b/modules/manage/pages/disaster-recovery/shadowing/setup.adoc index dab8c61e91..4bc1fa962a 100644 --- a/modules/manage/pages/disaster-recovery/shadowing/setup.adoc +++ b/modules/manage/pages/disaster-recovery/shadowing/setup.adoc @@ -118,7 +118,7 @@ Any cluster can create a shadow link to a source cluster. When you create a shad [TIP] ==== -You can use `rpk` to generate a configuration template: +You can use `rpk` to generate a sample configuration file with common filter patterns: [,bash] ---- @@ -129,7 +129,7 @@ rpk shadow config generate -o shadow-config.yaml rpk shadow config generate --print-template -o shadow-config-template.yaml ---- -This creates a complete YAML configuration file that you can customize for your environment. The template includes all available fields with comments explaining their purpose. +This creates a complete YAML configuration file that you can customize for your environment. The template includes all available fields with comments explaining their purpose. For detailed command options, see xref:reference:rpk/rpk-shadow/rpk-shadow-config-generate.adoc[`rpk shadow config generate`]. ==== .Explore the configuration file @@ -413,17 +413,6 @@ topic_metadata_sync_options: The starting offset only affects **new shadow topics**. After a shadow topic exists and has data, changing this setting has no effect on that topic's replication. ==== -=== Generate a sample configuration - -Use `rpk` to generate a sample configuration file with common filter patterns: - -[,bash] ----- -rpk shadow config generate -o shadow-config.yaml ----- - -This creates a template configuration file that you can customize for your environment. For detailed command options, see xref:reference:rpk/rpk-shadow/rpk-shadow-config-generate.adoc[`rpk shadow config generate`]. - === Networking Configure network connectivity between your source and shadow clusters to enable shadow link replication. The shadow cluster initiates connections to the source cluster using a pull-based architecture. From 1d9c18074c830ae923a2c3b9dae38e30ca936563 Mon Sep 17 00:00:00 2001 From: micheleRP Date: Tue, 2 Dec 2025 12:20:48 -0700 Subject: [PATCH 18/20] incorporate Simon's feedback --- .../shadowing/failover-runbook.adoc | 4 +- .../disaster-recovery/shadowing/failover.adoc | 14 +++-- .../disaster-recovery/shadowing/monitor.adoc | 4 +- .../disaster-recovery/shadowing/overview.adoc | 55 ++++++++----------- 4 files changed, 36 insertions(+), 41 deletions(-) diff --git a/modules/manage/pages/disaster-recovery/shadowing/failover-runbook.adoc b/modules/manage/pages/disaster-recovery/shadowing/failover-runbook.adoc index dd2421a270..a3d86378ff 100644 --- a/modules/manage/pages/disaster-recovery/shadowing/failover-runbook.adoc +++ b/modules/manage/pages/disaster-recovery/shadowing/failover-runbook.adoc @@ -93,7 +93,7 @@ Verify that the following conditions exist before proceeding with failover: * Topics should be in `ACTIVE` state (not `FAULTED`). * Replication lag should be reasonable for your RPO requirements. -**Understanding replication lag** +==== Understanding replication lag Use xref:reference:rpk/rpk-shadow/rpk-shadow-status.adoc[`rpk shadow status`] to check lag, which shows the message count difference between source and shadow partitions: @@ -135,7 +135,7 @@ Name: , State: ACTIVE 1 2345 2579 2568 11 ---- -The partition information shows: +The partition information shows the following: * **SRC_LSO**: Source partition last stable offset * **SRC_HWM**: Source partition high watermark diff --git a/modules/manage/pages/disaster-recovery/shadowing/failover.adoc b/modules/manage/pages/disaster-recovery/shadowing/failover.adoc index ebe82a596a..8d640cd2ba 100644 --- a/modules/manage/pages/disaster-recovery/shadowing/failover.adoc +++ b/modules/manage/pages/disaster-recovery/shadowing/failover.adoc @@ -37,13 +37,15 @@ When you initiate failover, Redpanda performs the following operations: Topic failover is irreversible. Once failed over, topics cannot return to shadow mode, and automatic fallback to the original source cluster is not supported. +NOTE: To avoid a split-brain scenario after failover, ensure that all clients are reconfigured to point to the shadow cluster before resuming write activity. + == Failover commands You can perform failover at different levels of granularity to match your disaster recovery needs: === Individual topic failover -To fail over a specific shadow topic while leaving other topics in the shadow link still replicating: +To fail over a specific shadow topic while leaving other topics in the shadow link still replicating, run: [,bash] ---- @@ -54,7 +56,7 @@ Use this approach when you need to selectively failover specific workloads or wh === Complete shadow link failover (cluster failover) -To fail over all shadow topics associated with the shadow link simultaneously: +To fail over all shadow topics associated with the shadow link simultaneously, run: [,bash] ---- @@ -82,6 +84,7 @@ Force deleting a shadow link is irreversible and immediately fails over all topi The shadow link itself has a simple state model: * **`ACTIVE`**: Shadow link is operating normally, replicating data +* **`PAUSED`**: Shadow link replication is temporarily halted by user action Shadow links do not have dedicated failover states. Instead, the link's operational status is determined by the collective state of its shadow topics. @@ -93,10 +96,11 @@ Individual shadow topics progress through specific states during failover: * **`FAULTED`**: Shadow topic has encountered an error and is not replicating * **`FAILING_OVER`**: Failover initiated, replication stopping * **`FAILED_OVER`**: Failover completed successfully, topic fully writable +* **`PAUSED`**: Replication temporarily halted by user action == Monitor failover progress -Monitor failover progress using the status command: +To monitor failover progress using the status command, run: [,bash] ---- @@ -105,7 +109,7 @@ rpk shadow status The output shows individual topic states and any issues encountered during the failover process. For detailed command options, see xref:reference:rpk/rpk-shadow/rpk-shadow-status.adoc[`rpk shadow status`]. -**Task states during monitoring:** +Task states during monitoring: * **`ACTIVE`**: Task is operating normally and replicating data * **`FAULTED`**: Task encountered an error and requires attention @@ -140,6 +144,8 @@ After successful failover, your shadow cluster exhibits the following characteri == Failover considerations and limitations +Before implementing failover procedures, understand these key considerations that affect your disaster recovery strategy and operational planning. + **Data consistency:** * Some data loss may occur due to replication lag at the time of failover. diff --git a/modules/manage/pages/disaster-recovery/shadowing/monitor.adoc b/modules/manage/pages/disaster-recovery/shadowing/monitor.adoc index 804fa07236..304dc44acb 100644 --- a/modules/manage/pages/disaster-recovery/shadowing/monitor.adoc +++ b/modules/manage/pages/disaster-recovery/shadowing/monitor.adoc @@ -42,8 +42,8 @@ rpk shadow status For troubleshooting specific issues, you can use command options to show individual status sections. See xref:reference:rpk/rpk-shadow/rpk-shadow-status.adoc[`rpk shadow status`] for available status options. The status output includes: -* **Shadow link state**: Overall operational state (`ACTIVE`). -* **Individual topic states**: Current state of each replicated topic (`ACTIVE`, `FAULTED`, `FAILING_OVER`, `FAILED_OVER`). +* **Shadow link state**: Overall operational state (`ACTIVE`, `PAUSED`). +* **Individual topic states**: Current state of each replicated topic (`ACTIVE`, `FAULTED`, `FAILING_OVER`, `FAILED_OVER`, `PAUSED`). * **Task status**: Health of replication tasks across brokers (`ACTIVE`, `FAULTED`, `NOT_RUNNING`, `LINK_UNAVAILABLE`). For details about shadow link tasks, see xref:manage:disaster-recovery/shadowing/setup.adoc#shadow-link-tasks[Shadow link tasks]. * **Lag information**: Replication lag per partition showing source vs shadow high watermarks (HWM). diff --git a/modules/manage/pages/disaster-recovery/shadowing/overview.adoc b/modules/manage/pages/disaster-recovery/shadowing/overview.adoc index 1c484b40ce..71484eb2a7 100644 --- a/modules/manage/pages/disaster-recovery/shadowing/overview.adoc +++ b/modules/manage/pages/disaster-recovery/shadowing/overview.adoc @@ -34,10 +34,9 @@ Shadowing replicates: Shadowing addresses enterprise disaster recovery requirements driven by regulatory compliance and business continuity needs. Organizations typically want to minimize both recovery time objective (RTO) and recovery point objective (RPO), and Shadowing asynchronous replication helps you achieve both goals by reducing data loss during regional outages and enabling rapid application recovery. -The architecture follows an active-passive pattern. The source cluster processes all production traffic while the shadow cluster remains in read-only mode, continuously receiving updates. If a disaster occurs, you can failover the shadow topics using the -ifndef::env-cloud[Admin API] -ifdef::env-cloud[Data Plane API] -or `rpk`, making them fully writable. At that point, you can redirect your applications to the shadow cluster, which becomes the new production cluster. +The architecture follows an active-passive pattern. The source cluster processes all production traffic while the shadow cluster remains in read-only mode, continuously receiving updates. If a disaster occurs, you can failover the shadow topics, making them fully writable. At that point, you can redirect your applications to the shadow cluster, which becomes the new production cluster. + +NOTE: To avoid a split-brain scenario after failover, ensure that all clients are reconfigured to point to the shadow cluster before resuming write activity. ifdef::env-cloud[] @@ -138,40 +137,30 @@ Partition count is always replicated to ensure the shadow topic matches the sour The <> handles topic property replication. For topic properties, Redpanda follows these replication rules: -[cols="1,1,1"] - -|=== -|Never replicated |Always replicated |Always replicated + -(unless `exclude_default` is `true`) - -|`redpanda.remote.readreplica` -|`max.message.bytes` -|`compression.type` - -|`redpanda.remote.recovery` -|`cleanup.policy` -|`retention.bytes` +**Never replicated** -|`redpanda.remote.allowgaps` -|`message.timestamp.type` -|`retention.ms` +* `redpanda.remote.readreplica` +* `redpanda.remote.recovery` +* `redpanda.remote.allowgaps` +* `redpanda.virtual.cluster.id` +* `redpanda.leaders.preference` +* `redpanda.cloud_topic.enabled` -|`redpanda.virtual.cluster.id` -| -|`delete.retention.ms` +**Always replicated** -|`redpanda.leaders.preference` -| -|`replication.factor` +* `max.message.bytes` +* `cleanup.policy` +* `message.timestamp.type` -|`redpanda.cloud_topic.enabled` -| -|`min.compaction.lag.ms` +**Always replicated (unless `exclude_default` is `true`)** -| -| -|`max.compaction.lag.ms` -|=== +* `compression.type` +* `retention.bytes` +* `retention.ms` +* `delete.retention.ms` +* `replication.factor` +* `min.compaction.lag.ms` +* `max.compaction.lag.ms` To replicate additional topic properties, explicitly list them in `synced_shadow_topic_properties`. From aea6e827c562c9a5e343d3367ef0becdf43a3218 Mon Sep 17 00:00:00 2001 From: Michele Cyran Date: Tue, 2 Dec 2025 12:31:28 -0700 Subject: [PATCH 19/20] Update modules/manage/pages/disaster-recovery/shadowing/setup.adoc Co-authored-by: Paulo Borges --- modules/manage/pages/disaster-recovery/shadowing/setup.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/manage/pages/disaster-recovery/shadowing/setup.adoc b/modules/manage/pages/disaster-recovery/shadowing/setup.adoc index 4bc1fa962a..db1f2ba3fd 100644 --- a/modules/manage/pages/disaster-recovery/shadowing/setup.adoc +++ b/modules/manage/pages/disaster-recovery/shadowing/setup.adoc @@ -200,7 +200,7 @@ security_sync_options: acl_filters: # Filters for ACLs to sync - resource_filter: resource_type: TOPIC # Resource type: "TOPIC", "GROUP", "CLUSTER" - pattern_type: PREFIXED # Pattern type: "LITERAL", "PREFIX", "PREFIXED" + pattern_type: PREFIXED # Pattern type: "LITERAL", "PREFIXED" name: # Examples: "prod-", "app-data-" access_filter: principal: User: # Principal name, example: "User:app-service" From 2b79cbc576999d9b47be22738a585ff9e0b445a4 Mon Sep 17 00:00:00 2001 From: micheleRP Date: Tue, 2 Dec 2025 14:37:24 -0700 Subject: [PATCH 20/20] revert playbook + minor edits --- local-antora-playbook.yml | 2 +- .../manage/pages/disaster-recovery/shadowing/monitor.adoc | 6 +++--- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/local-antora-playbook.yml b/local-antora-playbook.yml index e3ec36f597..391a6df4d3 100644 --- a/local-antora-playbook.yml +++ b/local-antora-playbook.yml @@ -17,7 +17,7 @@ content: - url: https://github.com/redpanda-data/docs branches: [v/*, shared, site-search,'!v-end-of-life/*'] - url: https://github.com/redpanda-data/cloud-docs - branches: 'DOC-1621-Document-Cloud-Feature-Shadowing-Disaster-Recovery-Enterprise' + branches: 'main' - url: https://github.com/redpanda-data/redpanda-labs branches: main start_paths: [docs,'*/docs'] diff --git a/modules/manage/pages/disaster-recovery/shadowing/monitor.adoc b/modules/manage/pages/disaster-recovery/shadowing/monitor.adoc index 304dc44acb..b7d0cf044b 100644 --- a/modules/manage/pages/disaster-recovery/shadowing/monitor.adoc +++ b/modules/manage/pages/disaster-recovery/shadowing/monitor.adoc @@ -33,14 +33,14 @@ rpk shadow describe For detailed command options, see xref:reference:rpk/rpk-shadow/rpk-shadow-list.adoc[`rpk shadow list`] and xref:reference:rpk/rpk-shadow/rpk-shadow-describe.adoc[`rpk shadow describe`]. This command shows the complete configuration of the shadow link, including connection settings, filters, and synchronization options. -To check your shadow link status to ensure proper operation, run: +To check your shadow link status and ensure proper operation, run: [,bash] ---- rpk shadow status ---- -For troubleshooting specific issues, you can use command options to show individual status sections. See xref:reference:rpk/rpk-shadow/rpk-shadow-status.adoc[`rpk shadow status`] for available status options. The status output includes: +For troubleshooting specific issues, you can use command options to show individual status sections. See xref:reference:rpk/rpk-shadow/rpk-shadow-status.adoc[`rpk shadow status`] for available status options. The status output includes the following: * **Shadow link state**: Overall operational state (`ACTIVE`, `PAUSED`). * **Individual topic states**: Current state of each replicated topic (`ACTIVE`, `FAULTED`, `FAILING_OVER`, `FAILED_OVER`, `PAUSED`). @@ -104,7 +104,7 @@ rpk shadow status | grep -E "LAG|Lag" === Alert conditions -Configure monitoring alerts for following conditions, which indicate problems with Shadowing: +Configure monitoring alerts for the following conditions, which indicate problems with Shadowing: * **High replication lag**: When `redpanda_shadow_link_shadow_lag` exceeds your RPO requirements * **Connection errors**: When `redpanda_shadow_link_client_errors` increases rapidly