From 8ae61530b8ae961bbcc08be3c4e4a6bf66726167 Mon Sep 17 00:00:00 2001 From: David Yu Date: Thu, 9 Jul 2026 20:42:15 -0700 Subject: [PATCH] k8s - Create Cloud Topics section and Whole Cluster Restore page for Cloud Topics (#1778) - Give Cloud Topics its own nav tree with an index page - Move How Cloud Topics work section to the Cloud Topics index page - Add Whole Cluster Restore page for Cloud Topics - Address review feedback Co-Authored-By: Claude Fable 5 --- modules/ROOT/nav.adoc | 4 +- .../pages/release-notes/operator.adoc | 2 +- .../pages/kubernetes/cloud-topics/index.adoc | 32 +++ .../k-cloud-topics-whole-cluster-restore.adoc | 201 ++++++++++++++++++ .../{ => cloud-topics}/k-cloud-topics.adoc | 23 +- modules/manage/partials/tiered-storage.adoc | 14 -- .../partials/whole-cluster-restore.adoc | 15 +- 7 files changed, 253 insertions(+), 38 deletions(-) create mode 100644 modules/manage/pages/kubernetes/cloud-topics/index.adoc create mode 100644 modules/manage/pages/kubernetes/cloud-topics/k-cloud-topics-whole-cluster-restore.adoc rename modules/manage/pages/kubernetes/{ => cloud-topics}/k-cloud-topics.adoc (93%) diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc index 3d464ddcff..4e0213a040 100644 --- a/modules/ROOT/nav.adoc +++ b/modules/ROOT/nav.adoc @@ -107,7 +107,6 @@ *** xref:manage:kubernetes/k-configure-helm-chart.adoc[Customize the Helm Chart] *** xref:manage:kubernetes/k-cluster-property-configuration.adoc[Cluster Properties] *** xref:manage:kubernetes/k-manage-topics.adoc[Manage Topics] -*** xref:manage:kubernetes/k-cloud-topics.adoc[Cloud Topics] *** xref:manage:kubernetes/k-manage-connectors.adoc[Manage Kafka Connect] *** xref:manage:kubernetes/storage/index.adoc[Storage] **** xref:manage:kubernetes/storage/k-volume-types.adoc[Volume Types] @@ -117,6 +116,9 @@ ***** xref:manage:kubernetes/storage/k-emptydir.adoc[emptyDir] **** xref:manage:kubernetes/storage/k-resize-persistentvolumes.adoc[Expand PersistentVolumes] **** xref:manage:kubernetes/storage/k-delete-persistentvolume.adoc[Delete PersistentVolumes] +*** xref:manage:kubernetes/cloud-topics/index.adoc[Cloud Topics] +**** xref:manage:kubernetes/cloud-topics/k-cloud-topics.adoc[Use Cloud Topics] +**** xref:manage:kubernetes/cloud-topics/k-cloud-topics-whole-cluster-restore.adoc[Whole Cluster Restore for Cloud Topics] *** xref:manage:kubernetes/tiered-storage/index.adoc[Tiered Storage] **** xref:manage:kubernetes/tiered-storage/k-tiered-storage.adoc[Use Tiered Storage] **** xref:manage:kubernetes/tiered-storage/k-fast-commission-decommission.adoc[] diff --git a/modules/get-started/pages/release-notes/operator.adoc b/modules/get-started/pages/release-notes/operator.adoc index e6c7be8ddd..0cc6eb594c 100644 --- a/modules/get-started/pages/release-notes/operator.adoc +++ b/modules/get-started/pages/release-notes/operator.adoc @@ -43,7 +43,7 @@ When you enable Schema Registry authentication, you can control which users and The Redpanda custom resource supports Cloud Topics in Kubernetes deployments. You can configure topics to use cloud storage as the primary backing store by setting the appropriate storage mode properties. -Cloud Topics in Kubernetes provide the same cost savings and architectural benefits as self-managed deployments. You configure them declaratively through the Redpanda custom resource. For setup instructions, see xref:manage:kubernetes/k-cloud-topics.adoc[Cloud Topics for Kubernetes]. +Cloud Topics in Kubernetes provide the same cost savings and architectural benefits as self-managed deployments. You configure them declaratively through the Redpanda custom resource. For setup instructions, see xref:manage:kubernetes/cloud-topics/k-cloud-topics.adoc[Cloud Topics for Kubernetes]. === Group-based access control (GBAC) diff --git a/modules/manage/pages/kubernetes/cloud-topics/index.adoc b/modules/manage/pages/kubernetes/cloud-topics/index.adoc new file mode 100644 index 0000000000..7c07228894 --- /dev/null +++ b/modules/manage/pages/kubernetes/cloud-topics/index.adoc @@ -0,0 +1,32 @@ += Cloud Topics in Kubernetes +:description: Cloud Topics use object storage as the primary data tier to optimize for latency-tolerant, high-throughput workloads. +:page-layout: index +:page-categories: Management +:env-kubernetes: true + +{description} + +Because the data lives in object storage, Cloud Topics also support recovery after total cluster loss: a xref:manage:kubernetes/cloud-topics/k-cloud-topics-whole-cluster-restore.adoc[whole cluster restore] brings the topics back in cloud storage mode with their data. + +== How Cloud Topics work + +With standard Redpanda topics, data is replicated across brokers using Raft consensus and stored locally on each replica. Cloud Topics change this model: data is acknowledged only after it is uploaded to object storage, making object storage the source of truth for both replication and consumption. + +include::develop:partial$cloud-topics-overview.adoc[tag=latency-explanation] + +=== Storage modes + +Redpanda supports multiple storage modes that you can set at the cluster or topic level using the `redpanda.storage.mode` property: + +include::manage:partial$storage-modes-table.adoc[tag=storage-modes] + +=== Ideal use cases + +include::develop:partial$cloud-topics-use-cases.adoc[tag=use-cases] + +=== Limitations + +include::develop:partial$cloud-topics-limitations.adoc[tag=limitations] +include::develop:partial$cloud-topics-limitations.adoc[tag=latency-limitation] + +== Suggested reading diff --git a/modules/manage/pages/kubernetes/cloud-topics/k-cloud-topics-whole-cluster-restore.adoc b/modules/manage/pages/kubernetes/cloud-topics/k-cloud-topics-whole-cluster-restore.adoc new file mode 100644 index 0000000000..77667bd4dc --- /dev/null +++ b/modules/manage/pages/kubernetes/cloud-topics/k-cloud-topics-whole-cluster-restore.adoc @@ -0,0 +1,201 @@ += Restore Cloud Topics with Whole Cluster Restore +:description: Recover Cloud Topics onto a new Kubernetes cluster after total cluster loss, with topics returning in cloud storage mode and no manual data migration. +:page-topic-type: how-to +:page-categories: Management, High Availability, Disaster Recovery +:personas: platform_admin +:learning-objective-1: Deploy a target cluster that restores Cloud Topics from object storage on bootstrap +:learning-objective-2: Verify that restored topics retain cloud storage mode and their data +:learning-objective-3: Identify the recovery point for Cloud Topics data +:env-kubernetes: true + +You can recover xref:manage:kubernetes/cloud-topics/k-cloud-topics.adoc[Cloud Topics] onto a new cluster after the loss of an entire Redpanda cluster. Because object storage is the source of truth for Cloud Topics, a xref:manage:kubernetes/tiered-storage/k-whole-cluster-restore.adoc[Whole Cluster Restore] brings the topics back in cloud storage mode, with their data and offsets, ready to serve producers and consumers again. + +After reading this page, you will be able to: + +* [ ] {learning-objective-1} +* [ ] {learning-objective-2} +* [ ] {learning-objective-3} + +[NOTE] +==== +include::shared:partial$enterprise-license.adoc[] +==== + +== How Whole Cluster Restore works with Cloud Topics + +Cloud Topics acknowledge writes only after the data is uploaded to object storage, so the bucket already holds both the topic data and the cluster metadata that Whole Cluster Restore needs. When you bootstrap a new (target) cluster against the same bucket with restore enabled, Redpanda: + +* Recreates the topics from the most recent cluster metadata upload. +* Restores Cloud Topics in cloud storage mode (`redpanda.storage.mode=cloud`). Topics do not fall back to Tiered Storage or local storage. +* Restores users, ACLs, schemas, consumer offsets, and cluster configuration, as described in xref:manage:kubernetes/tiered-storage/k-whole-cluster-restore.adoc[Whole Cluster Restore]. + +NOTE: Topics without per-topic archival to object storage are restored empty, with their definitions but no data. This does not apply to Cloud Topics (`redpanda.storage.mode=cloud`), whose data always resides in object storage and is fully restored. + +Restored Cloud Topics are immediately writable. New records continue from the next offset after the restored high watermark. + +=== Recovery point + +Whole Cluster Restore recovers each Cloud Topic partition up to the point covered by the most recent topic metadata in object storage. Records that were acknowledged shortly before the cluster loss might not yet be reflected in that metadata and are not restored. + +For planned scenarios, such as migrations or recovery drills, stop producers and wait for metadata uploads to complete before removing the source cluster. This results in a restore with no data loss. To make uploads more frequent, see xref:manage:kubernetes/tiered-storage/k-whole-cluster-restore.adoc#manage-source-metadata-uploads[Manage source metadata uploads]. + +== Prerequisites + +You must have the following: + +* Redpanda v26.1 or later on both the source and target clusters. Cloud Topics require v26.1 or later. +* xref:manage:kubernetes/cloud-topics/k-cloud-topics.adoc[Cloud Topics enabled] on the source cluster, with cluster metadata uploads enabled (`enable_cluster_metadata_upload_loop` is enabled by default). +* The object storage bucket or container used by the source cluster. The restore reads everything from this bucket, so it must survive the cluster loss. +* A valid Redpanda Enterprise license for the target cluster. + +The limitations in xref:manage:kubernetes/tiered-storage/k-whole-cluster-restore.adoc#limitations[Whole Cluster Restore] also apply to clusters with Cloud Topics. + +== Start a target cluster with restore enabled + +Here we describe how to deploy a new, empty cluster configured with the same object storage settings as the failed source cluster, with Cloud Topics enabled, and with restore on bootstrap enabled. + +CAUTION: Before you bootstrap the target cluster against the bucket, make sure that the failed source cluster is fully destroyed, including any persistent volumes. If brokers from the previous cluster are still running against the same bucket, the storage subsystems of the two clusters may interfere with each other. + +[tabs] +====== +Operator:: ++ +-- +.`redpanda-cluster.yaml` +[,yaml] +---- +apiVersion: cluster.redpanda.com/v1alpha2 +kind: Redpanda +metadata: + name: redpanda +spec: + chartRef: {} + clusterSpec: + storage: + tiered: + + config: + cluster: + cloud_topics_enabled: true + cloud_storage_attempt_cluster_restore_on_bootstrap: true +---- + +```bash +kubectl apply -f redpanda-cluster.yaml --namespace +``` +-- +Helm:: ++ +-- +[tabs] +==== +--values:: ++ +.`cluster-restore.yaml` +[,yaml] +---- +storage: + tiered: + +config: + cluster: + cloud_topics_enabled: true + cloud_storage_attempt_cluster_restore_on_bootstrap: true +---- ++ +```bash +helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ +--values cluster-restore.yaml +``` + +--set:: ++ +```bash +helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ + --set storage.tiered. \ + --set config.cluster.cloud_topics_enabled=true \ + --set config.cluster.cloud_storage_attempt_cluster_restore_on_bootstrap=true +``` +==== +-- +====== + +* `storage.tiered`: Configure the target cluster with the same object storage settings as the failed source cluster, including the same bucket or container. +* `config.cluster.cloud_topics_enabled`: Enable Cloud Topics on the target cluster so that restored topics can be served in cloud storage mode. +* `config.cluster.cloud_storage_attempt_cluster_restore_on_bootstrap`: Run the restore automatically when the new cluster bootstraps. No manual restore command is required. + +The restore runs while the cluster starts. Cluster size does not need to match the source cluster, but the target cluster must be empty of user-managed data. + +== Verify that the restore is complete + +. Run the following command until it returns `inactive`: ++ +[,bash] +---- +rpk cluster storage restore status +---- + +. Check if a rolling restart is required: ++ +[,bash] +---- +rpk cluster config status +---- ++ +Example output when a restart is required: ++ +[,bash] +---- +NODE CONFIG-VERSION NEEDS-RESTART INVALID UNKNOWN +1 4 true [] [] +---- + +. If a restart is required, perform a xref:manage:kubernetes/k-rolling-restart.adoc[rolling restart]. + +. After the restore completes, set `cloud_storage_attempt_cluster_restore_on_bootstrap` back to `false` so that future bootstraps of the same deployment do not attempt another restore. Update the value in your Redpanda resource or Helm values, then perform a rolling restart if `rpk cluster config status` reports one is needed. + +== Verify restored Cloud Topics + +. Confirm that the topic is restored in cloud storage mode: ++ +[,bash] +---- +rpk topic describe -c +---- ++ +The output includes `redpanda.storage.mode` with the value `cloud`: ++ +---- +redpanda.storage.mode cloud DYNAMIC_TOPIC_CONFIG +---- ++ +If the topic inherited cloud storage mode from the cluster default (`default_redpanda_storage_mode`), the source column shows `DEFAULT_CONFIG` instead of `DYNAMIC_TOPIC_CONFIG`. + +. Confirm that the partitions contain the restored data: ++ +[,bash] +---- +rpk topic describe -p +---- ++ +The high watermark of each partition reflects the restored records. + +. Confirm that the topic accepts new records: ++ +[,bash] +---- +echo "restore-probe" | rpk topic produce +---- ++ +The record is produced at the next offset after the restored high watermark. + +When verification succeeds, redirect your application workload to the new cluster. Make sure to update your application code to use the new addresses of your brokers. + +== Next steps + +* xref:manage:kubernetes/cloud-topics/k-cloud-topics.adoc[] +* xref:manage:kubernetes/tiered-storage/k-whole-cluster-restore.adoc[] + +== Suggested reading + +* xref:manage:kubernetes/tiered-storage/k-topic-recovery.adoc[Topic recovery], to restore only a subset of topic data diff --git a/modules/manage/pages/kubernetes/k-cloud-topics.adoc b/modules/manage/pages/kubernetes/cloud-topics/k-cloud-topics.adoc similarity index 93% rename from modules/manage/pages/kubernetes/k-cloud-topics.adoc rename to modules/manage/pages/kubernetes/cloud-topics/k-cloud-topics.adoc index b21ab21425..29110b4eb4 100644 --- a/modules/manage/pages/kubernetes/k-cloud-topics.adoc +++ b/modules/manage/pages/kubernetes/cloud-topics/k-cloud-topics.adoc @@ -6,6 +6,7 @@ :learning-objective-2: Enable and create Cloud Topics using the Redpanda Operator or Helm :learning-objective-3: Verify topic storage mode configuration :env-kubernetes: true +:page-aliases: manage:kubernetes/k-cloud-topics.adoc include::develop:partial$cloud-topics-overview.adoc[tag=intro] @@ -15,26 +16,7 @@ After reading this page, you will be able to: * [ ] {learning-objective-2} * [ ] {learning-objective-3} -== How Cloud Topics work - -With standard Redpanda topics, data is replicated across brokers using Raft consensus and stored locally on each replica. Cloud Topics change this model: data is acknowledged only after it is uploaded to object storage, making object storage the source of truth for both replication and consumption. - -include::develop:partial$cloud-topics-overview.adoc[tag=latency-explanation] - -=== Storage modes - -Redpanda supports multiple storage modes that you can set at the cluster or topic level using the `redpanda.storage.mode` property: - -include::manage:partial$storage-modes-table.adoc[tag=storage-modes] - -=== Ideal use cases - -include::develop:partial$cloud-topics-use-cases.adoc[tag=use-cases] - -=== Limitations - -include::develop:partial$cloud-topics-limitations.adoc[tag=limitations] -include::develop:partial$cloud-topics-limitations.adoc[tag=latency-limitation] +For an overview of how Cloud Topics work, including storage modes, use cases, and limitations, see xref:manage:kubernetes/cloud-topics/index.adoc[Cloud Topics in Kubernetes]. == Prerequisites @@ -483,5 +465,6 @@ The `source` field indicates whether the value was inherited from the cluster de == Suggested reading +- xref:manage:kubernetes/cloud-topics/k-cloud-topics-whole-cluster-restore.adoc[Restore Cloud Topics with Whole Cluster Restore] - xref:manage:kubernetes/tiered-storage/k-tiered-storage.adoc[Use Tiered Storage on Kubernetes] - xref:manage:kubernetes/k-manage-topics.adoc[Manage Topics with the Redpanda Operator] diff --git a/modules/manage/partials/tiered-storage.adoc b/modules/manage/partials/tiered-storage.adoc index bf940b4326..c7e2ca4ddf 100644 --- a/modules/manage/partials/tiered-storage.adoc +++ b/modules/manage/partials/tiered-storage.adoc @@ -141,8 +141,6 @@ Replace the following placeholders: + include::manage:partial$kubernetes/reset-object-storage-properties.adoc[] -include::manage:partial$kubernetes/extraclusterconfig.adoc[] - ===== **Configure access with access keys** . In AWS, grant an IAM user the following permissions to read and create objects in your buckets: @@ -261,8 +259,6 @@ Replace the following placeholders: + include::manage:partial$kubernetes/reset-object-storage-properties.adoc[] -include::manage:partial$kubernetes/extraclusterconfig.adoc[] - include::manage:partial$tiered-storage/aws-kms-key.adoc[leveloffset=+4] ==== Google Cloud Storage @@ -348,8 +344,6 @@ Replace the following placeholders: + include::manage:partial$kubernetes/reset-object-storage-properties.adoc[] -include::manage:partial$kubernetes/extraclusterconfig.adoc[] - ===== **Configure access with access keys** To configure access to Google Cloud Storage with access keys instead of an IAM role: @@ -469,8 +463,6 @@ Replace the following placeholders: + include::manage:partial$kubernetes/reset-object-storage-properties.adoc[] -include::manage:partial$kubernetes/extraclusterconfig.adoc[] - include::manage:partial$tiered-storage/gcp-kms-key.adoc[leveloffset=+4] ==== Microsoft ABS/ADLS @@ -579,8 +571,6 @@ include::manage:partial$kubernetes/reset-object-storage-properties.adoc[] The `serviceAccount` annotations and the `statefulset` Pod labels are essential for the Azure webhook to inject the necessary Azure-specific environment variables and the projected service account token volume into the pods. For more information, visit https://learn.microsoft.com/en-us/azure/aks/workload-identity-overview?tabs=dotnet[Microsoft Entra Workload ID with Azure Kubernetes Service (AKS)^]. -include::manage:partial$kubernetes/extraclusterconfig.adoc[] - ===== **Configure access with account access keys** . Get an account access key for the Azure container that Redpanda will run on. For information on how to view your account access keys, see the https://learn.microsoft.com/en-us/azure/storage/common/storage-account-keys-manage?toc=%2Fazure%2Fstorage%2Fblobs%2Ftoc.json&bc=%2Fazure%2Fstorage%2Fblobs%2Fbreadcrumb%2Ftoc.json&tabs=azure-portal#view-account-access-keys[Azure documentation^]. @@ -682,8 +672,6 @@ Replace the following placeholders: + include::manage:partial$kubernetes/reset-object-storage-properties.adoc[] -include::manage:partial$kubernetes/extraclusterconfig.adoc[] - - For information about how to grant access from an internet IP range (if you need to open additional routes/ports between your broker nodes and Azure Blob Storage; for example, in a hybrid cloud deployment), see the https://learn.microsoft.com/en-us/azure/storage/common/storage-network-security?toc=%2Fazure%2Fstorage%2Fblobs%2Ftoc.json&bc=%2Fazure%2Fstorage%2Fblobs%2Fbreadcrumb%2Ftoc.json&tabs=azure-portal#grant-access-from-an-internet-ip-range[Microsoft documentation^]. - For more information about Shared Key authentication, see the https://learn.microsoft.com/en-us/rest/api/storageservices/authorize-with-shared-key[Microsoft documentation^]. @@ -1100,8 +1088,6 @@ A constant stream of data is necessary to build up the log segments and roll the To see new log segments faster, you can edit the `segment.bytes` topic-level property. Or, you can edit the xref:reference:properties/object-storage-properties.adoc#cloud_storage_segment_max_upload_interval_sec[`cloud_storage_segment_max_upload_interval_sec`] property, which sets the frequency with which new segments are generated in Tiered Storage, even if the local segment has not exceeded the `segment.bytes` size or the `segment.ms` age. ==== -NOTE: Starting in version 22.3, when you delete a topic in Redpanda, the data is also deleted in object storage. See <>. - === Idle timeout You can configure Redpanda to start a remote write periodically. This is useful if the ingestion rate is low and the segments are kept open for long periods of time. You specify a number of seconds for the timeout, and if that time has passed since the previous write and the partition has new data, Redpanda starts a new write. This limits data loss in the event of catastrophic failure and adds a guarantee that you only lose the specified number of seconds of data. diff --git a/modules/manage/partials/whole-cluster-restore.adoc b/modules/manage/partials/whole-cluster-restore.adoc index dd7b6f9178..62bcca0fa5 100644 --- a/modules/manage/partials/whole-cluster-restore.adoc +++ b/modules/manage/partials/whole-cluster-restore.adoc @@ -23,7 +23,19 @@ TIP: If you need to restore only a subset of topic data, consider using xref:man The following metadata is included in a Whole Cluster Restore: -* Topic definitions. If you have enabled Tiered Storage only for specific topics, topics without Tiered Storage enabled will be restored empty. +* Topic definitions. Topic data is restored only for topics that are archived to object storage. ++ +[NOTE] +==== +Topics without archival to object storage are restored empty, with their definitions and configuration but no data. +ifdef::env-kubernetes[] +In Kubernetes, enabling Tiered Storage enables archival for every topic by default: the Redpanda Helm chart sets `cloud_storage_enable_remote_write: true` when Tiered Storage is enabled. A topic is restored empty only if archival was explicitly disabled, for example with the `redpanda.remote.write=false` topic property. +endif::[] +This does not apply to Cloud Topics (`redpanda.storage.mode=cloud`), whose data always resides in object storage and is fully restored. +ifdef::env-kubernetes[] +See xref:manage:kubernetes/cloud-topics/k-cloud-topics-whole-cluster-restore.adoc[Whole Cluster Restore for Cloud Topics]. +endif::[] +==== * Users and access control lists (ACLs). * xref:manage:schema-reg/schema-reg-overview.adoc[Schemas]. To ensure that your schemas are also archived and restored, you must also enable Tiered Storage for the `_schemas` topic. * The xref:develop:consume-data/consumer-offsets.adoc[consumer offsets topic]. Some restored committed consumer offsets may be truncated to a lower value than in the original cluster, to keep offsets at or below the highest restored offset in the partition. @@ -154,7 +166,6 @@ helm upgrade --install redpanda redpanda/redpanda --namespace --crea - `storage.tiered`: Make sure to configure the target cluster with the same Tiered Storage settings as the failed source cluster. - `config.cluster.cloud_storage_attempt_cluster_restore_on_bootstrap`: Automate cluster restore in Kubernetes. Setting to `true` is recommended when using an automated method for deployment. When bootstrapping a cluster with a given bucket, make sure that any previous cluster using the bucket is fully destroyed, otherwise Tiered Storage subsystems may interfere with each other. -include::manage:partial$kubernetes/extraclusterconfig.adoc[] endif::[] ifndef::env-kubernetes[]