From 9f3227986c7f390270d898e81293a5b463d18cd5 Mon Sep 17 00:00:00 2001 From: micheleRP Date: Tue, 2 Jun 2026 15:54:41 -0600 Subject: [PATCH 1/2] docs(DOC-2222): expose 3 default topic settings as customer-managed Cloud configs Tag default_topic_partitions, log_retention_ms, and retention_bytes for Redpanda Cloud (BYOC + Dedicated), where they are now customer-managed via cloudv2#26519 (added to the customer_managed_configs allow-list in install-pack 25.3 and 26.1). They render as "Available in the Redpanda Cloud Console (editable)". Because the Cloud docs have no topic-properties reference page, drop the inline topic-properties xref from the log_retention_ms and retention_bytes descriptions (use inline code) and mark their related_topics self-managed-only. Scoped to these three properties only; unrelated property drift from the full regen is intentionally excluded. Co-Authored-By: Claude Opus 4.8 (1M context) --- docs-data/property-overrides.json | 8 ++++---- .../redpanda-properties-v26.1.9.json | 20 +++++++++---------- .../properties/cluster-properties.adoc | 20 ++++++++++++++----- 3 files changed, 29 insertions(+), 19 deletions(-) diff --git a/docs-data/property-overrides.json b/docs-data/property-overrides.json index 85b9ec4ced..45334aa852 100644 --- a/docs-data/property-overrides.json +++ b/docs-data/property-overrides.json @@ -1375,9 +1375,9 @@ }, "log_retention_ms": { "config_scope": "cluster", - "description": "The amount of time to keep a log file before deleting it (in milliseconds). If set to `-1`, no time limit is applied. This is a cluster-wide default when a topic does not set or disable xref:./topic-properties.adoc#retentionms[`retention.ms`].", + "description": "The amount of time to keep a log file before deleting it (in milliseconds). If set to `-1`, no time limit is applied. This is a cluster-wide default that applies when a topic does not set or disable its own `retention.ms`.", "related_topics": [ - "xref:reference:properties/topic-properties.adoc#retentionms[`retention.ms`]" + "self-managed-only:xref:reference:properties/topic-properties.adoc#retentionms[`retention.ms`]" ] }, "log_segment_ms": { @@ -1901,9 +1901,9 @@ "config_scope": "topic" }, "retention_bytes": { - "description": "Default maximum number of bytes per partition on disk before triggering deletion of the oldest messages. If `null` (the default value), no limit is applied.\n\nThe topic property xref:./topic-properties.adoc#retentionbytes[`retention.bytes`] overrides the value of `retention_bytes` at the topic level.", + "description": "Default maximum number of bytes per partition on disk before triggering deletion of the oldest messages. If `null` (the default value), no limit is applied.\n\nThe topic property `retention.bytes` overrides the value of `retention_bytes` at the topic level.", "related_topics": [ - "xref:reference:properties/topic-properties.adoc#retentionbytes[`retention.bytes`]" + "self-managed-only:xref:reference:properties/topic-properties.adoc#retentionbytes[`retention.bytes`]" ], "config_scope": "cluster" }, diff --git a/modules/reference/attachments/redpanda-properties-v26.1.9.json b/modules/reference/attachments/redpanda-properties-v26.1.9.json index b3c4b5fb6b..75ff1cd52d 100644 --- a/modules/reference/attachments/redpanda-properties-v26.1.9.json +++ b/modules/reference/attachments/redpanda-properties-v26.1.9.json @@ -5523,9 +5523,9 @@ "default_topic_partitions": { "c_type": "int32_t", "cloud_byoc_only": false, - "cloud_editable": false, + "cloud_editable": true, "cloud_readonly": false, - "cloud_supported": false, + "cloud_supported": true, "config_scope": "cluster", "default": 1, "defined_in": "src/v/config/configuration.cc", @@ -9183,21 +9183,21 @@ ], "c_type": "retention_duration_property", "cloud_byoc_only": false, - "cloud_editable": false, + "cloud_editable": true, "cloud_readonly": false, - "cloud_supported": false, + "cloud_supported": true, "config_scope": "cluster", "default": 604800000, "default_human_readable": "1 week", "defined_in": "src/v/config/configuration.cc", - "description": "The amount of time to keep a log file before deleting it (in milliseconds). If set to `-1`, no time limit is applied. This is a cluster-wide default when a topic does not set or disable xref:./topic-properties.adoc#retentionms[`retention.ms`].", + "description": "The amount of time to keep a log file before deleting it (in milliseconds). If set to `-1`, no time limit is applied. This is a cluster-wide default that applies when a topic does not set or disable its own `retention.ms`.", "is_deprecated": false, "is_enterprise": false, "name": "log_retention_ms", "needs_restart": false, "nullable": false, "related_topics": [ - "xref:reference:properties/topic-properties.adoc#retentionms[`retention.ms`]" + "self-managed-only:xref:reference:properties/topic-properties.adoc#retentionms[`retention.ms`]" ], "type": "retention_duration_property", "visibility": "user" @@ -11964,20 +11964,20 @@ "retention_bytes": { "c_type": "size_t", "cloud_byoc_only": false, - "cloud_editable": false, + "cloud_editable": true, "cloud_readonly": false, - "cloud_supported": false, + "cloud_supported": true, "config_scope": "cluster", "default": null, "defined_in": "src/v/config/configuration.cc", - "description": "Default maximum number of bytes per partition on disk before triggering deletion of the oldest messages. If `null` (the default value), no limit is applied.\n\nThe topic property xref:./topic-properties.adoc#retentionbytes[`retention.bytes`] overrides the value of `retention_bytes` at the topic level.", + "description": "Default maximum number of bytes per partition on disk before triggering deletion of the oldest messages. If `null` (the default value), no limit is applied.\n\nThe topic property `retention.bytes` overrides the value of `retention_bytes` at the topic level.", "is_deprecated": false, "is_enterprise": false, "name": "retention_bytes", "needs_restart": false, "nullable": true, "related_topics": [ - "xref:reference:properties/topic-properties.adoc#retentionbytes[`retention.bytes`]" + "self-managed-only:xref:reference:properties/topic-properties.adoc#retentionbytes[`retention.bytes`]" ], "type": "integer", "visibility": "user" diff --git a/modules/reference/partials/properties/cluster-properties.adoc b/modules/reference/partials/properties/cluster-properties.adoc index b9836dd2c3..f07790da16 100644 --- a/modules/reference/partials/properties/cluster-properties.adoc +++ b/modules/reference/partials/properties/cluster-properties.adoc @@ -5008,6 +5008,7 @@ endif::[] // end::redpanda-cloud[] +// tag::redpanda-cloud[] === default_topic_partitions Default number of partitions per topic. @@ -5027,7 +5028,7 @@ Default number of partitions per topic. | Default | ifdef::env-cloud[] -Available in the Redpanda Cloud Console +Available in the Redpanda Cloud Console (editable) endif::[] ifndef::env-cloud[] `1` @@ -5054,6 +5055,7 @@ endif::[] |=== +// end::redpanda-cloud[] === default_topic_replication @@ -12594,9 +12596,10 @@ endif::[] |=== +// tag::redpanda-cloud[] === log_retention_ms -The amount of time to keep a log file before deleting it (in milliseconds). If set to `-1`, no time limit is applied. This is a cluster-wide default when a topic does not set or disable xref:./topic-properties.adoc#retentionms[`retention.ms`]. +The amount of time to keep a log file before deleting it (in milliseconds). If set to `-1`, no time limit is applied. This is a cluster-wide default that applies when a topic does not set or disable its own `retention.ms`. [cols="1s,2a"] |=== @@ -12610,7 +12613,7 @@ The amount of time to keep a log file before deleting it (in milliseconds). If s | Default | ifdef::env-cloud[] -Available in the Redpanda Cloud Console +Available in the Redpanda Cloud Console (editable) endif::[] ifndef::env-cloud[] `604800000` (1 week) @@ -12640,11 +12643,14 @@ ifndef::env-cloud[] | `delete_retention_ms` endif::[] +ifndef::env-cloud[] | Related topics |xref:reference:properties/topic-properties.adoc#retentionms[`retention.ms`] +endif::[] |=== +// end::redpanda-cloud[] // tag::redpanda-cloud[] === log_segment_ms @@ -16215,11 +16221,12 @@ endif::[] |=== +// tag::redpanda-cloud[] === retention_bytes Default maximum number of bytes per partition on disk before triggering deletion of the oldest messages. If `null` (the default value), no limit is applied. -The topic property xref:./topic-properties.adoc#retentionbytes[`retention.bytes`] overrides the value of `retention_bytes` at the topic level. +The topic property `retention.bytes` overrides the value of `retention_bytes` at the topic level. [cols="1s,2a"] |=== @@ -16233,7 +16240,7 @@ The topic property xref:./topic-properties.adoc#retentionbytes[`retention.bytes` | Default | ifdef::env-cloud[] -Available in the Redpanda Cloud Console +Available in the Redpanda Cloud Console (editable) endif::[] ifndef::env-cloud[] `null` @@ -16258,11 +16265,14 @@ ifndef::env-cloud[] | User endif::[] +ifndef::env-cloud[] | Related topics |xref:reference:properties/topic-properties.adoc#retentionbytes[`retention.bytes`] +endif::[] |=== +// end::redpanda-cloud[] === retention_local_strict From 76cf358bc1a238198da449ec2513abe747778228 Mon Sep 17 00:00:00 2001 From: micheleRP Date: Wed, 3 Jun 2026 09:43:24 -0600 Subject: [PATCH 2/2] docs: fix retention property xref anchors and dedupe related topic Address review nits and fix broken anchors on the retention properties: - Add the space after the `self-managed-only:` prefix in related_topics entries so they read as `key: value` (review nits). - Fix `#retentionms`/`#retentionbytes` xref anchors to the hyphenated `#retention-ms`/`#retention-bytes` form generated by the current version (idseparator `-`), so the links resolve. - Remove the duplicate `retention_bytes` link from the `retention.bytes` topic property's related topics, keeping the full resource ID. - Fix the broken `retention.ms` reference in audit-logging (wrong page path and anchor). Generated property partials and the attachment carry only the matching retention hunks. The broader no-hyphen anchor breakage across other properties is tracked for a separate sweep. Co-Authored-By: Claude Opus 4.8 (1M context) --- docs-data/property-overrides.json | 7 +++---- .../cluster-maintenance/topic-property-configuration.adoc | 4 ++-- modules/manage/partials/audit-logging.adoc | 2 +- .../reference/attachments/redpanda-properties-v26.1.9.json | 7 +++---- .../reference/partials/properties/cluster-properties.adoc | 4 ++-- .../reference/partials/properties/topic-properties.adoc | 4 +--- 6 files changed, 12 insertions(+), 16 deletions(-) diff --git a/docs-data/property-overrides.json b/docs-data/property-overrides.json index 45334aa852..281f92f2f1 100644 --- a/docs-data/property-overrides.json +++ b/docs-data/property-overrides.json @@ -1377,7 +1377,7 @@ "config_scope": "cluster", "description": "The amount of time to keep a log file before deleting it (in milliseconds). If set to `-1`, no time limit is applied. This is a cluster-wide default that applies when a topic does not set or disable its own `retention.ms`.", "related_topics": [ - "self-managed-only:xref:reference:properties/topic-properties.adoc#retentionms[`retention.ms`]" + "self-managed-only: xref:reference:properties/topic-properties.adoc#retention-ms[`retention.ms`]" ] }, "log_segment_ms": { @@ -1869,14 +1869,13 @@ "retention.bytes": { "description": "A size-based retention limit that configures the maximum size that a topic partition can grow before becoming eligible for cleanup.\n\nIf `retention.bytes` is set to a positive value, it overrides the cluster property xref:cluster-properties.adoc#retention_bytes[`retention_bytes`] for the topic, and the total retained size for the topic is `retention.bytes` multiplied by the number of partitions for the topic.\n\nWhen both size-based (`retention.bytes`) and time-based (`retention.ms`) retention limits are set, cleanup occurs when either limit is reached.\n\nThis property supports three states:\n\n* Positive value: Sets the maximum bytes per partition. When exceeded, oldest data becomes eligible for cleanup.\n* 0: Partitions are immediately eligible for cleanup.\n* Negative value: Disables size-based retention for this topic.", "related_topics": [ - "xref:cluster-properties.adoc#retention_bytes[`retention_bytes`]", "xref:reference:properties/cluster-properties.adoc#retention_bytes[`retention_bytes`]", "xref:manage:cluster-maintenance/disk-utilization.adoc#configure-message-retention[Configure message retention]" ], "config_scope": "topic" }, "retention.local.target.bytes": { - "description": "A size-based retention limit for Tiered Storage that configures the maximum size that a topic partition in local storage can grow before becoming eligible for cleanup. It applies per partition and is equivalent to <> without Tiered Storage.\n\nThis property supports three states:\n\n* Positive value: Sets the maximum bytes per partition in local storage before cleanup.\n* 0: Data in local storage is immediately eligible for cleanup.\n* Negative value: Disables size-based local retention override for this topic.", + "description": "A size-based retention limit for Tiered Storage that configures the maximum size that a topic partition in local storage can grow before becoming eligible for cleanup. It applies per partition and is equivalent to <> without Tiered Storage.\n\nThis property supports three states:\n\n* Positive value: Sets the maximum bytes per partition in local storage before cleanup.\n* 0: Data in local storage is immediately eligible for cleanup.\n* Negative value: Disables size-based local retention override for this topic.", "related_topics": [ "xref:reference:properties/cluster-properties.adoc#retention_local_target_bytes[`retention_local_target_bytes`]", "xref:manage:tiered-storage.adoc[Tiered Storage]" @@ -1903,7 +1902,7 @@ "retention_bytes": { "description": "Default maximum number of bytes per partition on disk before triggering deletion of the oldest messages. If `null` (the default value), no limit is applied.\n\nThe topic property `retention.bytes` overrides the value of `retention_bytes` at the topic level.", "related_topics": [ - "self-managed-only:xref:reference:properties/topic-properties.adoc#retentionbytes[`retention.bytes`]" + "self-managed-only: xref:reference:properties/topic-properties.adoc#retention-bytes[`retention.bytes`]" ], "config_scope": "cluster" }, diff --git a/modules/manage/pages/cluster-maintenance/topic-property-configuration.adoc b/modules/manage/pages/cluster-maintenance/topic-property-configuration.adoc index 7f1d6410f1..88023d0673 100644 --- a/modules/manage/pages/cluster-maintenance/topic-property-configuration.adoc +++ b/modules/manage/pages/cluster-maintenance/topic-property-configuration.adoc @@ -202,8 +202,8 @@ When using `cleanup.policy=compact` or `cleanup.policy=compact,delete`, configur When using `cleanup.policy=delete` or `cleanup.policy=compact,delete`, configure: -- xref:reference:properties/topic-properties.adoc#retentionbytes[`retention.bytes`] - Maximum size before cleanup (size-based retention) -- xref:reference:properties/topic-properties.adoc#retentionms[`retention.ms`] - Maximum age before cleanup (time-based retention) +- xref:reference:properties/topic-properties.adoc#retention-bytes[`retention.bytes`] - Maximum size before cleanup (size-based retention) +- xref:reference:properties/topic-properties.adoc#retention-ms[`retention.ms`] - Maximum age before cleanup (time-based retention) - xref:reference:properties/topic-properties.adoc#segmentbytes[`segment.bytes`] - Control how frequently cleanup can occur by setting segment size === Performance diff --git a/modules/manage/partials/audit-logging.adoc b/modules/manage/partials/audit-logging.adoc index 52020f974a..f80120afb6 100644 --- a/modules/manage/partials/audit-logging.adoc +++ b/modules/manage/partials/audit-logging.adoc @@ -425,7 +425,7 @@ With audit logging, the pattern of message generation may be very different from A typical scenario with audit logging is to route the messages to an analytics platform like Splunk. If your retention period is too long, you may find that you are storing excessive amounts of replicated messages in both Redpanda and in your analytics suite. Identifying the right balance of retention and replication settings minimizes this duplication while retaining your data in a system that provides actionable intelligence. -Assess the retention needs for your audit logs. You may not need to keep the logs for the default seven days. This is controlled by setting xref:reference:topic-properties.adoc#retentionms[`retention.ms`] for the `_redpanda.audit_log` topic or by setting xref:reference:cluster-properties.adoc#log_retention_ms[`log_retention_ms`] at the cluster level. +Assess the retention needs for your audit logs. You may not need to keep the logs for the default seven days. This is controlled by setting xref:reference:properties/topic-properties.adoc#retention-ms[`retention.ms`] for the `_redpanda.audit_log` topic or by setting xref:reference:cluster-properties.adoc#log_retention_ms[`log_retention_ms`] at the cluster level. == Next steps diff --git a/modules/reference/attachments/redpanda-properties-v26.1.9.json b/modules/reference/attachments/redpanda-properties-v26.1.9.json index 75ff1cd52d..9c3f22324c 100644 --- a/modules/reference/attachments/redpanda-properties-v26.1.9.json +++ b/modules/reference/attachments/redpanda-properties-v26.1.9.json @@ -9197,7 +9197,7 @@ "needs_restart": false, "nullable": false, "related_topics": [ - "self-managed-only:xref:reference:properties/topic-properties.adoc#retentionms[`retention.ms`]" + "self-managed-only: xref:reference:properties/topic-properties.adoc#retention-ms[`retention.ms`]" ], "type": "retention_duration_property", "visibility": "user" @@ -11874,7 +11874,6 @@ "name": "retention.bytes", "needs_restart": false, "related_topics": [ - "xref:cluster-properties.adoc#retention_bytes[`retention_bytes`]", "xref:reference:properties/cluster-properties.adoc#retention_bytes[`retention_bytes`]", "xref:manage:cluster-maintenance/disk-utilization.adoc#configure-message-retention[Configure message retention]" ], @@ -11894,7 +11893,7 @@ "corresponding_cluster_property": "retention_local_target_bytes_default", "default": null, "defined_in": "src/v/kafka/protocol/topic_properties.h", - "description": "A size-based retention limit for Tiered Storage that configures the maximum size that a topic partition in local storage can grow before becoming eligible for cleanup. It applies per partition and is equivalent to <> without Tiered Storage.\n\nThis property supports three states:\n\n* Positive value: Sets the maximum bytes per partition in local storage before cleanup.\n* 0: Data in local storage is immediately eligible for cleanup.\n* Negative value: Disables size-based local retention override for this topic.", + "description": "A size-based retention limit for Tiered Storage that configures the maximum size that a topic partition in local storage can grow before becoming eligible for cleanup. It applies per partition and is equivalent to <> without Tiered Storage.\n\nThis property supports three states:\n\n* Positive value: Sets the maximum bytes per partition in local storage before cleanup.\n* 0: Data in local storage is immediately eligible for cleanup.\n* Negative value: Disables size-based local retention override for this topic.", "is_deprecated": false, "is_enterprise": false, "is_topic_property": true, @@ -11977,7 +11976,7 @@ "needs_restart": false, "nullable": true, "related_topics": [ - "self-managed-only:xref:reference:properties/topic-properties.adoc#retentionbytes[`retention.bytes`]" + "self-managed-only: xref:reference:properties/topic-properties.adoc#retention-bytes[`retention.bytes`]" ], "type": "integer", "visibility": "user" diff --git a/modules/reference/partials/properties/cluster-properties.adoc b/modules/reference/partials/properties/cluster-properties.adoc index f07790da16..76f6b4d589 100644 --- a/modules/reference/partials/properties/cluster-properties.adoc +++ b/modules/reference/partials/properties/cluster-properties.adoc @@ -12645,7 +12645,7 @@ endif::[] ifndef::env-cloud[] | Related topics -|xref:reference:properties/topic-properties.adoc#retentionms[`retention.ms`] +|xref:reference:properties/topic-properties.adoc#retention-ms[`retention.ms`] endif::[] |=== @@ -16267,7 +16267,7 @@ endif::[] ifndef::env-cloud[] | Related topics -|xref:reference:properties/topic-properties.adoc#retentionbytes[`retention.bytes`] +|xref:reference:properties/topic-properties.adoc#retention-bytes[`retention.bytes`] endif::[] |=== diff --git a/modules/reference/partials/properties/topic-properties.adoc b/modules/reference/partials/properties/topic-properties.adoc index 73aed1720a..c7d86baeaf 100644 --- a/modules/reference/partials/properties/topic-properties.adoc +++ b/modules/reference/partials/properties/topic-properties.adoc @@ -1861,8 +1861,6 @@ endif::[] | Related topics | -* xref:cluster-properties.adoc#retention_bytes[`retention_bytes`] - * xref:reference:properties/cluster-properties.adoc#retention_bytes[`retention_bytes`] * xref:manage:cluster-maintenance/disk-utilization.adoc#configure-message-retention[Configure message retention] @@ -1874,7 +1872,7 @@ endif::[] // tag::category-tiered-storage[] === retention.local.target.bytes -A size-based retention limit for Tiered Storage that configures the maximum size that a topic partition in local storage can grow before becoming eligible for cleanup. It applies per partition and is equivalent to <> without Tiered Storage. +A size-based retention limit for Tiered Storage that configures the maximum size that a topic partition in local storage can grow before becoming eligible for cleanup. It applies per partition and is equivalent to <> without Tiered Storage. This property supports three states: