Skip to content

docs(DOC-2222): expose default topic settings as customer-managed Cloud configs #1728

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
micheleRP merged 2 commits into from
Jun 3, 2026
Merged

docs(DOC-2222): expose default topic settings as customer-managed Cloud configs #1728

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
9f32279
docs(DOC-2222): expose 3 default topic settings as customer-managed C…
micheleRP Jun 2, 2026
76cf358
docs: fix retention property xref anchors and dedupe related topic
micheleRP Jun 3, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 5 additions & 6 deletions docs-data/property-overrides.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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#retention-ms[`retention.ms`]"
]
},
"log_segment_ms": {
Expand Down Expand Up @@ -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 <<retentionbytes, `retention.bytes`>> 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 <<retention-bytes, `retention.bytes`>> 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]"
Expand All @@ -1901,9 +1900,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.",

@coderabbitai coderabbitai Bot Jun 2, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Remove default-value metadata from the override description.

Line 1904 includes default metadata (null/default value), which should stay out of property descriptions in this file. Keep this behavior-focused.

Suggested edit 
-      "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.",
+      "description": "Maximum number of bytes per partition on disk before triggering deletion of the oldest messages.\n\nThe topic property `retention.bytes` overrides `retention_bytes` at the topic level.",

As per coding guidelines: “In property descriptions, keep descriptions focused on behavior and avoid metadata information like ... default values ...”.

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
"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.",
"description": "Maximum number of bytes per partition on disk before triggering deletion of the oldest messages.\n\nThe topic property `retention.bytes` overrides `retention_bytes` at the topic level.",
🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs-data/property-overrides.json` at line 1904, The description for the
"retention_bytes" override contains default-value metadata ("If `null` (the
default value), no limit is applied.") which should be removed; edit the
description string in property-overrides.json for the "retention_bytes" entry to
drop any mention of `null`/default value while preserving the behavior note that
the topic property `retention.bytes` overrides the topic-level
`retention_bytes`.

"related_topics": [
"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"
},
Expand Down
4 changes: 2 additions & 2 deletions modules/manage/pages/cluster-maintenance/topic-property-configuration.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion modules/manage/partials/audit-logging.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
23 changes: 11 additions & 12 deletions modules/reference/attachments/redpanda-properties-v26.1.9.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down Expand Up @@ -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#retention-ms[`retention.ms`]"
],
"type": "retention_duration_property",
"visibility": "user"
Expand Down Expand Up @@ -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]"
],
Expand All @@ -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 <<retentionbytes, `retention.bytes`>> 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 <<retention-bytes, `retention.bytes`>> 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,
Expand Down Expand Up @@ -11964,20 +11963,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#retention-bytes[`retention.bytes`]"
],
"type": "integer",
"visibility": "user"
Expand Down
24 changes: 17 additions & 7 deletions modules/reference/partials/properties/cluster-properties.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5008,6 +5008,7 @@ endif::[]

// end::redpanda-cloud[]

// tag::redpanda-cloud[]
=== default_topic_partitions

Default number of partitions per topic.
Expand All @@ -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`
Expand All @@ -5054,6 +5055,7 @@ endif::[]

|===

// end::redpanda-cloud[]

=== default_topic_replication

Expand Down Expand Up @@ -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"]
|===
Expand All @@ -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)
Expand Down Expand Up @@ -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`]
|xref:reference:properties/topic-properties.adoc#retention-ms[`retention.ms`]
endif::[]

|===

// end::redpanda-cloud[]

// tag::redpanda-cloud[]
=== log_segment_ms
Expand Down Expand Up @@ -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"]
|===
Expand All @@ -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`
Expand All @@ -16258,11 +16265,14 @@ ifndef::env-cloud[]
| User
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::[]

|===

// end::redpanda-cloud[]

=== retention_local_strict

Expand Down
4 changes: 1 addition & 3 deletions modules/reference/partials/properties/topic-properties.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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]
Expand All @@ -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 <<retentionbytes, `retention.bytes`>> 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 <<retention-bytes, `retention.bytes`>> without Tiered Storage.

This property supports three states:

Expand Down
Loading