From 57e4f5e42cf9786fdcaf742694e28f4966c641ae Mon Sep 17 00:00:00 2001 From: Paulo Borges Date: Fri, 19 Dec 2025 12:25:19 -0300 Subject: [PATCH 1/7] github: modify github action to trigger whenever a commit is made to property-overrides --- .github/workflows/update-property-docs.yaml | 79 +++++++++++++++++---- 1 file changed, 64 insertions(+), 15 deletions(-) diff --git a/.github/workflows/update-property-docs.yaml b/.github/workflows/update-property-docs.yaml index 82cc43451..96a2283ae 100644 --- a/.github/workflows/update-property-docs.yaml +++ b/.github/workflows/update-property-docs.yaml @@ -10,6 +10,8 @@ on: type: string repository_dispatch: types: [trigger-property-docs-generation] + push: + paths: ['docs-data/property-overrides.json'] jobs: generate-property-docs: @@ -36,7 +38,7 @@ jobs: - name: Checkout the repository uses: actions/checkout@v4 with: - ref: main + ref: ${{ github.event_name == 'push' && github.ref || 'main' }} token: ${{ env.ACTIONS_BOT_TOKEN }} - name: Set up Node.js @@ -54,32 +56,62 @@ jobs: echo "tag=${{ github.event.inputs.tag }}" >> $GITHUB_OUTPUT elif [ -n "${{ github.event.client_payload.tag }}" ]; then echo "tag=${{ github.event.client_payload.tag }}" >> $GITHUB_OUTPUT + elif [ "${{ github.event_name }}" = "push" ]; then + # For push events, use the current latest-redpanda-tag from antora.yml + CURRENT=$(grep 'latest-redpanda-tag:' antora.yml | awk '{print $2}' | tr -d "\"'") + echo "tag=$CURRENT" >> $GITHUB_OUTPUT + echo "🔄 Using current latest-redpanda-tag for override changes: $CURRENT" else echo "❌ No tag provided via input or dispatch payload" >&2 exit 1 fi - - name: Check if tag is newer than antora.yml latest + - name: Check if docs need regeneration id: version_check + env: + GH_TOKEN: ${{ env.ACTIONS_BOT_TOKEN }} run: | set -euo pipefail TAG="${{ steps.tag.outputs.tag }}" CURRENT=$(grep 'latest-redpanda-tag:' antora.yml | awk '{print $2}' | tr -d "\"'") echo "📄 Current latest-redpanda-tag in antora.yml: $CURRENT" - echo "🔖 Incoming tag: $TAG" - - # Strip leading 'v' for numeric comparison - CUR_NUM=$(echo "$CURRENT" | sed 's/^v//') - NEW_NUM=$(echo "$TAG" | sed 's/^v//') + echo "🔖 Using tag: $TAG" - # Compare semver using sort -V - if [ "$(printf "%s\n%s" "$CUR_NUM" "$NEW_NUM" | sort -V | tail -n1)" = "$NEW_NUM" ] && [ "$CUR_NUM" != "$NEW_NUM" ]; then - echo "$TAG is newer than $CURRENT" - echo "is_newer=true" >> $GITHUB_OUTPUT + # For push events (override file changes), check if generated docs are up to date + if [ "${{ github.event_name }}" = "push" ]; then + echo "🔄 Override file changed — checking if generated docs need update" + + # Check if generated property docs exist and are newer than the override file + OVERRIDE_FILE="docs-data/property-overrides.json" + GENERATED_FILE="modules/reference/pages/properties/broker-properties.adoc" + + if [ -f "$GENERATED_FILE" ]; then + # Compare file modification times + if [ "$OVERRIDE_FILE" -nt "$GENERATED_FILE" ]; then + echo "🔄 Override file is newer than generated docs — regeneration needed" + echo "is_newer=true" >> $GITHUB_OUTPUT + else + echo "✅ Generated docs are up to date with override file — skipping" + echo "is_newer=false" >> $GITHUB_OUTPUT + fi + else + echo "🔄 Generated docs don't exist — regeneration needed" + echo "is_newer=true" >> $GITHUB_OUTPUT + fi else - echo "$TAG is not newer than $CURRENT — skipping doc generation" - echo "is_newer=false" >> $GITHUB_OUTPUT + # Strip leading 'v' for numeric comparison + CUR_NUM=$(echo "$CURRENT" | sed 's/^v//') + NEW_NUM=$(echo "$TAG" | sed 's/^v//') + + # Compare semver using sort -V + if [ "$(printf "%s\n%s" "$CUR_NUM" "$NEW_NUM" | sort -V | tail -n1)" = "$NEW_NUM" ] && [ "$CUR_NUM" != "$NEW_NUM" ]; then + echo "$TAG is newer than $CURRENT" + echo "is_newer=true" >> $GITHUB_OUTPUT + else + echo "$TAG is not newer than $CURRENT — skipping doc generation" + echo "is_newer=false" >> $GITHUB_OUTPUT + fi fi - name: Generate property docs @@ -95,13 +127,30 @@ jobs: env: GITHUB_TOKEN: ${{ env.ACTIONS_BOT_TOKEN }} + - name: Commit generated docs to current branch + if: steps.version_check.outputs.is_newer == 'true' && github.event_name == 'push' + run: | + git config --local user.email "vbotbuildovich@users.noreply.github.com" + git config --local user.name "vbotbuildovich" + + # Add generated files + git add modules/reference/pages/properties/ modules/reference/partials/properties/ + + # Check if there are changes to commit + if git diff --staged --quiet; then + echo "No changes to commit" + else + git commit -m "auto-docs: Regenerate property docs after override changes" + git push origin HEAD + fi + - name: Create pull request - if: steps.version_check.outputs.is_newer == 'true' + if: steps.version_check.outputs.is_newer == 'true' && github.event_name != 'push' uses: peter-evans/create-pull-request@v6 with: token: ${{ env.ACTIONS_BOT_TOKEN }} commit-message: "auto-docs: Update property docs for ${{ steps.tag.outputs.tag }}" - branch: update-property-docs-${{ steps.tag.outputs.tag }} + branch: "update-property-docs-${{ steps.tag.outputs.tag }}" title: "auto-docs: Update property docs for tag ${{ steps.tag.outputs.tag }}" body: | This PR auto-generates updated Redpanda property documentation for **${{ steps.tag.outputs.tag }}**. From 94eb975d96492ebfdde855e72a477ed3b68d2d0c Mon Sep 17 00:00:00 2001 From: Paulo Borges Date: Fri, 19 Dec 2025 12:25:31 -0300 Subject: [PATCH 2/7] topic-prop: update tristate behavior topic prop update additional changes revert audit change revert cluster prop change update with links --- docs-data/property-overrides.json | 18 ++--- .../partials/properties/topic-properties.adoc | 69 ++++++++++++++++--- 2 files changed, 67 insertions(+), 20 deletions(-) diff --git a/docs-data/property-overrides.json b/docs-data/property-overrides.json index b9be30e9c..88c9d568b 100644 --- a/docs-data/property-overrides.json +++ b/docs-data/property-overrides.json @@ -670,7 +670,7 @@ "config_scope": "cluster" }, "delete.retention.ms": { - "description": "The retention time for tombstone records in a compacted topic. Redpanda removes tombstone records after the retention limit is exceeded.\n\nIf you have enabled Tiered Storage and set <> or <> for the topic, you cannot enable tombstone removal.\n\nIf both `delete.retention.ms` and the cluster property config_ref:tombstone_retention_ms,true,properties/cluster-properties[] are set, `delete.retention.ms` overrides the cluster level tombstone retention for an individual topic.", + "description": "The retention time for tombstone records in a compacted topic. Redpanda removes tombstone records after the retention limit is exceeded.\n\nIf you have enabled Tiered Storage and set <> or <> for the topic, you cannot enable tombstone removal.\n\nIf both `delete.retention.ms` and the cluster property config_ref:tombstone_retention_ms,true,properties/cluster-properties[] are set, `delete.retention.ms` overrides the cluster level tombstone retention for an individual topic.\n\nThis property supports three states:\n\n* Positive value: Sets the milliseconds to retain tombstone records before removal.\n* 0: Tombstone records are immediately eligible for removal.\n* Negative value: No per-topic limit applied, inherits cluster default from xref:reference:properties/cluster-properties.adoc#tombstone_retention_ms[`tombstone_retention_ms`].", "related_topics": [ "xref:reference:properties/cluster-properties.adoc#tombstone_retention_ms[`tombstone_retention_ms`]", "xref:manage:cluster-maintenance/compaction-settings.adoc#tombstone-record-removal[Tombstone record removal]" @@ -955,7 +955,7 @@ "config_scope": "cluster" }, "initial.retention.local.target.bytes": { - "description": "A size-based initial retention limit for Tiered Storage that determines how much data in local storage is transferred to a partition replica when a cluster is resized. If `null` (default), all locally retained data is transferred.", + "description": "A size-based initial retention limit for Tiered Storage that determines how much data in local storage is transferred to a partition replica when a cluster is resized. If `null` (default), all locally retained data is transferred.\n\nThis property supports three states:\n\n* Positive value: Sets the maximum bytes of local data to transfer during cluster resize.\n* 0: No local data is transferred during cluster resize.\n* Negative value: All locally retained data is transferred (default behavior).", "related_topics": [ "xref:reference:properties/cluster-properties.adoc#initial_retention_local_target_bytes[`initial_retention_local_target_bytes`]", "xref:manage:tiered-storage.adoc#fast-commission-and-decommission[Fast commission and decommission through Tiered Storage]" @@ -963,7 +963,7 @@ "config_scope": "topic" }, "initial.retention.local.target.ms": { - "description": "A time-based initial retention limit for Tiered Storage that determines how much data in local storage is transferred to a partition replica when a cluster is resized. If `null` (default), all locally retained data is transferred.", + "description": "A time-based initial retention limit for Tiered Storage that determines how much data in local storage is transferred to a partition replica when a cluster is resized. If `null` (default), all locally retained data is transferred.\n\nThis property supports three states:\n\n* Positive value: Sets the maximum age (milliseconds) of local data to transfer during cluster resize.\n* 0: No local data is transferred during cluster resize.\n* Negative value: All locally retained data is transferred (default behavior).", "related_topics": [ "xref:reference:properties/cluster-properties.adoc#initial_retention_local_target_ms[`initial_retention_local_target_ms`]", "xref:manage:tiered-storage.adoc#fast-commission-and-decommission[Fast commission and decommission through Tiered Storage]" @@ -1319,7 +1319,7 @@ "config_scope": "cluster" }, "min.cleanable.dirty.ratio": { - "description": "The minimum ratio between the number of bytes in dirty segments and the total number of bytes in closed segments that must be reached before a partition's log is eligible for compaction in a compact topic.", + "description": "The minimum ratio between dirty and total bytes in closed segments before a partition's log is eligible for compaction in a compact topic.\n\nThis property supports three states:\n\n* Positive value: Sets the minimum dirty ratio (0.0 to 1.0) required before compaction.\n* 0: Compaction is always eligible regardless of dirty ratio.\n* Negative value: Uses the cluster default from xref:reference:properties/cluster-properties.adoc#min_cleanable_dirty_ratio[`min_cleanable_dirty_ratio`].", "related_topics": [ "xref:reference:properties/cluster-properties.adoc#min_cleanable_dirty_ratio[`min_cleanable_dirty_ratio`]" ], @@ -1688,7 +1688,7 @@ "config_scope": "topic" }, "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.", + "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: No per-topic limit applied, inherits cluster default from xref:reference:properties/cluster-properties.adoc#retention_bytes[`retention_bytes`].", "related_topics": [ "xref:cluster-properties.adoc#retention_bytes[`retention_bytes`]", "xref:reference:properties/cluster-properties.adoc#retention_bytes[`retention_bytes`]", @@ -1697,7 +1697,7 @@ "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.", + "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: No per-topic limit applied, inherits cluster default from xref:reference:properties/cluster-properties.adoc#retention_local_target_bytes[`retention_local_target_bytes`].", "related_topics": [ "xref:reference:properties/cluster-properties.adoc#retention_local_target_bytes[`retention_local_target_bytes`]", "xref:manage:tiered-storage.adoc[Tiered Storage]" @@ -1705,7 +1705,7 @@ "config_scope": "topic" }, "retention.local.target.ms": { - "description": "A time-based retention limit for Tiered Storage that sets the maximum duration that a log's segment file for a topic is retained in local storage before it's eligible for cleanup. This property is equivalent to <> without Tiered Storage.", + "description": "A time-based retention limit for Tiered Storage that sets the maximum duration that a log's segment file for a topic is retained in local storage before cleanup.\n\nThis property supports three states:\n\n* Positive value: Sets the maximum milliseconds to retain data in local storage.\n* 0: Data in local storage is immediately eligible for cleanup.\n* Negative value: No per-topic limit applied, inherits cluster default from xref:reference:properties/cluster-properties.adoc#retention_local_target_ms_default[`retention_local_target_ms_default`].", "related_topics": [ "xref:reference:properties/cluster-properties.adoc#retention_local_target_ms[`retention_local_target_ms`]", "xref:manage:tiered-storage.adoc[Tiered Storage]", @@ -1714,7 +1714,7 @@ "config_scope": "topic" }, "retention.ms": { - "description": "A time-based retention limit that configures the maximum duration that a log's segment file for a topic is retained before it becomes eligible to be cleaned up. To consume all data, a consumer of the topic must read from a segment before its `retention.ms` elapses, otherwise the segment may be compacted and/or deleted. If a non-positive value, no per-topic limit is applied.\n\nIf `retention.ms` is set to a positive value, it overrides the cluster property xref:./cluster-properties.adoc#log_retention_ms[`log_retention_ms`] for the topic.\n\nWhen both size-based (`retention.bytes`) and time-based (`retention.ms`) retention limits are set, the earliest occurring limit applies.", + "description": "A time-based retention limit that configures the maximum duration that a log's segment file for a topic is retained before it becomes eligible to be cleaned up. To consume all data, a consumer of the topic must read from a segment before its `retention.ms` elapses, otherwise the segment may be compacted and/or deleted.\n\nIf `retention.ms` is set to a positive value, it overrides the cluster property xref:./cluster-properties.adoc#log_retention_ms[`log_retention_ms`] for the topic.\n\nWhen both size-based (`retention.bytes`) and time-based (`retention.ms`) retention limits are set, the earliest occurring limit applies.\n\nThis property supports three states:\n\n* Positive value: Sets the maximum milliseconds to retain data. After this duration, segments become eligible for cleanup.\n* 0: Data is immediately eligible for cleanup.\n* Negative value: No per-topic limit applied, inherits cluster default from xref:reference:properties/cluster-properties.adoc#log_retention_ms[`log_retention_ms`].", "related_topics": [ "xref:reference:properties/cluster-properties.adoc#log_retention_ms[`log_retention_ms`]", "xref:manage:cluster-maintenance/disk-utilization.adoc#configure-message-retention[Configure message retention]" @@ -1926,7 +1926,7 @@ "config_scope": "topic" }, "segment.ms": { - "description": "The maximum duration that a log segment of a topic is active (open for writes and not deletable). A periodic event, with `segment.ms` as its period, forcibly closes the active segment and transitions, or rolls, to a new active segment. The closed (inactive) segment is then eligible to be cleaned up according to cleanup and retention properties.\n\nIf set to a positive duration, `segment.ms` overrides the cluster property xref:./cluster-properties.adoc#log_segment_ms[`log_segment_ms`]. Values are automatically clamped between the cluster bounds set by xref:./cluster-properties.adoc#log_segment_ms_min[`log_segment_ms_min`] (default: 10 minutes) and xref:./cluster-properties.adoc#log_segment_ms_max[`log_segment_ms_max`] (default: 1 year). If your configured value exceeds these bounds, Redpanda uses the bound value and logs a warning. Check current cluster bounds with `rpk cluster config get log_segment_ms_min log_segment_ms_max`.", + "description": "The maximum duration that a log segment of a topic is active (open for writes and not deletable). A periodic event, with `segment.ms` as its period, forcibly closes the active segment and transitions, or rolls, to a new active segment. The closed (inactive) segment is then eligible to be cleaned up according to cleanup and retention properties.\n\nIf set to a positive duration, `segment.ms` overrides the cluster property xref:./cluster-properties.adoc#log_segment_ms[`log_segment_ms`]. Values are automatically clamped between the cluster bounds set by xref:./cluster-properties.adoc#log_segment_ms_min[`log_segment_ms_min`] (default: 10 minutes) and xref:./cluster-properties.adoc#log_segment_ms_max[`log_segment_ms_max`] (default: 1 year). If your configured value exceeds these bounds, Redpanda uses the bound value and logs a warning. Check current cluster bounds with `rpk cluster config get log_segment_ms_min log_segment_ms_max`.\n\nThis property supports three states:\n\n* Positive value: Sets the maximum milliseconds a segment remains active before rolling to a new segment.\n* 0: Segments are immediately eligible for closure.\n* Negative value: Uses the cluster default from xref:reference:properties/cluster-properties.adoc#log_segment_ms[`log_segment_ms`].", "related_topics": [ "xref:reference:properties/cluster-properties.adoc#log_segment_ms[`log_segment_ms`]", "xref:reference:properties/cluster-properties.adoc#log_segment_ms_min[`log_segment_ms_min`]", diff --git a/modules/reference/partials/properties/topic-properties.adoc b/modules/reference/partials/properties/topic-properties.adoc index 9a90ffe40..237673d67 100644 --- a/modules/reference/partials/properties/topic-properties.adoc +++ b/modules/reference/partials/properties/topic-properties.adoc @@ -321,6 +321,12 @@ If you have enabled Tiered Storage and set <> without Tiered Storage. +This property supports three states: + +* Positive value: Sets the maximum bytes per partition in local storage before cleanup. +* 0: Data in local storage is immediately eligible for cleanup. +* Negative value: No per-topic limit applied, inherits cluster default from xref:reference:properties/cluster-properties.adoc#retention_local_target_bytes[`retention_local_target_bytes`]. + [cols="1s,2a"] |=== | Property | Value @@ -1799,7 +1828,13 @@ endif::[] // tag::category-tiered-storage[] === retention.local.target.ms -A time-based retention limit for Tiered Storage that sets the maximum duration that a log's segment file for a topic is retained in local storage before it's eligible for cleanup. This property is equivalent to <> without Tiered Storage. +A time-based retention limit for Tiered Storage that sets the maximum duration that a log's segment file for a topic is retained in local storage before cleanup. + +This property supports three states: + +* Positive value: Sets the maximum milliseconds to retain data in local storage. +* 0: Data in local storage is immediately eligible for cleanup. +* Negative value: No per-topic limit applied, inherits cluster default from xref:reference:properties/cluster-properties.adoc#retention_local_target_ms_default[`retention_local_target_ms_default`]. [cols="1s,2a"] |=== @@ -1848,12 +1883,18 @@ endif::[] // tag::category-retention-compaction[] === retention.ms -A time-based retention limit that configures the maximum duration that a log's segment file for a topic is retained before it becomes eligible to be cleaned up. To consume all data, a consumer of the topic must read from a segment before its `retention.ms` elapses, otherwise the segment may be compacted and/or deleted. If a non-positive value, no per-topic limit is applied. +A time-based retention limit that configures the maximum duration that a log's segment file for a topic is retained before it becomes eligible to be cleaned up. To consume all data, a consumer of the topic must read from a segment before its `retention.ms` elapses, otherwise the segment may be compacted and/or deleted. If `retention.ms` is set to a positive value, it overrides the cluster property xref:./cluster-properties.adoc#log_retention_ms[`log_retention_ms`] for the topic. When both size-based (`retention.bytes`) and time-based (`retention.ms`) retention limits are set, the earliest occurring limit applies. +This property supports three states: + +* Positive value: Sets the maximum milliseconds to retain data. After this duration, segments become eligible for cleanup. +* 0: Data is immediately eligible for cleanup. +* Negative value: No per-topic limit applied, inherits cluster default from xref:reference:properties/cluster-properties.adoc#log_retention_ms[`log_retention_ms`]. + [cols="1s,2a"] |=== | Property | Value @@ -1958,6 +1999,12 @@ The maximum duration that a log segment of a topic is active (open for writes an If set to a positive duration, `segment.ms` overrides the cluster property xref:./cluster-properties.adoc#log_segment_ms[`log_segment_ms`]. Values are automatically clamped between the cluster bounds set by xref:./cluster-properties.adoc#log_segment_ms_min[`log_segment_ms_min`] (default: 10 minutes) and xref:./cluster-properties.adoc#log_segment_ms_max[`log_segment_ms_max`] (default: 1 year). If your configured value exceeds these bounds, Redpanda uses the bound value and logs a warning. Check current cluster bounds with `rpk cluster config get log_segment_ms_min log_segment_ms_max`. +This property supports three states: + +* Positive value: Sets the maximum milliseconds a segment remains active before rolling to a new segment. +* 0: Segments are immediately eligible for closure. +* Negative value: Uses the cluster default from xref:reference:properties/cluster-properties.adoc#log_segment_ms[`log_segment_ms`]. + [cols="1s,2a"] |=== | Property | Value From 73afd148def1bc9c6f5d80870bc90bb22c0202b5 Mon Sep 17 00:00:00 2001 From: Paulo Borges Date: Fri, 19 Dec 2025 17:56:55 -0300 Subject: [PATCH 3/7] add note about changes change admonition --- modules/develop/pages/config-topics.adoc | 5 +++++ .../pages/release-notes/redpanda.adoc | 17 +++++++++++++++++ .../pages/rpk/rpk-topic/rpk-topic-create.adoc | 5 +++++ .../partials/tristate-behavior-change-25-3.adoc | 1 + modules/upgrade/partials/incompat-changes.adoc | 6 ++++++ 5 files changed, 34 insertions(+) create mode 100644 modules/shared/partials/tristate-behavior-change-25-3.adoc diff --git a/modules/develop/pages/config-topics.adoc b/modules/develop/pages/config-topics.adoc index 68e05506c..a2e711703 100644 --- a/modules/develop/pages/config-topics.adoc +++ b/modules/develop/pages/config-topics.adoc @@ -98,6 +98,11 @@ The cleanup policy determines how to clean up the partition log files when they Unlike compacted topics, which keep only the most recent message for a given key, topics configured with a `delete` cleanup policy provide a running history of all changes for those topics. +[NOTE] +==== +include::shared:partial$tristate-behavior-change-25-3.adoc[] +==== + include::develop:partial$topic-properties-warning.adoc[] For example, to change a topic's policy to `compact`, run: diff --git a/modules/get-started/pages/release-notes/redpanda.adoc b/modules/get-started/pages/release-notes/redpanda.adoc index 2eef7c25c..270f85d21 100644 --- a/modules/get-started/pages/release-notes/redpanda.adoc +++ b/modules/get-started/pages/release-notes/redpanda.adoc @@ -144,6 +144,23 @@ The following configuration properties have new default values in v25.3: * xref:reference:properties/cluster-properties.adoc#partition_autobalancing_mode[`partition_autobalancing_mode`]: Changed from `node_add` to `continuous` (Enterprise license required). * xref:reference:properties/cluster-properties.adoc#iceberg_throttle_backlog_size_ratio[`iceberg_throttle_backlog_size_ratio`]: Changed from `0.3` to `null`. +[[behavior-changes]] +=== Behavior changes + +The following topic properties now support enhanced tristate behavior: + +* xref:reference:properties/topic-properties.adoc#segmentms[`segment.ms`] +* xref:reference:properties/topic-properties.adoc#retentionbytes[`retention.bytes`] +* xref:reference:properties/topic-properties.adoc#retentionms[`retention.ms`] +* xref:reference:properties/topic-properties.adoc#retentionlocaltargetbytes[`retention.local.target.bytes`] +* xref:reference:properties/topic-properties.adoc#retentionlocaltargetms[`retention.local.target.ms`] +* xref:reference:properties/topic-properties.adoc#initialretentionlocaltargetbytes[`initial.retention.local.target.bytes`] +* xref:reference:properties/topic-properties.adoc#initialretentionlocaltargetms[`initial.retention.local.target.ms`] +* xref:reference:properties/topic-properties.adoc#deleteretentionms[`delete.retention.ms`] +* xref:reference:properties/topic-properties.adoc#mincleanabledirtyratio[`min.cleanable.dirty.ratio`] + +Previously, these properties treated zero and negative values the same way. Now they support three distinct states: positive values set specific limits, zero provides immediate eligibility for cleanup/compaction, and negative values inherit cluster defaults. Review your topic configurations if you currently use zero values for these properties. + === Deprecations The following configuration properties have been deprecated in v25.3 and will be removed in a future release: diff --git a/modules/reference/pages/rpk/rpk-topic/rpk-topic-create.adoc b/modules/reference/pages/rpk/rpk-topic/rpk-topic-create.adoc index dd953a9b3..f2d2668d4 100644 --- a/modules/reference/pages/rpk/rpk-topic/rpk-topic-create.adoc +++ b/modules/reference/pages/rpk/rpk-topic/rpk-topic-create.adoc @@ -53,6 +53,11 @@ NOTE: For the full list of properties, see xref:reference:topic-properties.adoc[ endif::[] +[IMPORTANT] +==== +include::shared:partial$tristate-behavior-change-25-3.adoc[] +==== + == Examples === Create a topic diff --git a/modules/shared/partials/tristate-behavior-change-25-3.adoc b/modules/shared/partials/tristate-behavior-change-25-3.adoc new file mode 100644 index 000000000..17f640a92 --- /dev/null +++ b/modules/shared/partials/tristate-behavior-change-25-3.adoc @@ -0,0 +1 @@ +Starting in Redpanda v25.3, several topic properties support enhanced tristate behavior. Properties like `retention.ms`, `retention.bytes`, `segment.ms`, and others now distinguish between zero values (immediate eligibility for cleanup/compaction) and negative values (inherit cluster defaults). Previously, zero and negative values were treated the same way. For the complete list of affected properties and detailed information, see xref:25.3@get-started:release-notes/redpanda.adoc#behavior-changes[Redpanda v25.3 behavior changes]. Review your topic configurations if you currently use zero values for these properties. \ No newline at end of file diff --git a/modules/upgrade/partials/incompat-changes.adoc b/modules/upgrade/partials/incompat-changes.adoc index 2ecca5d9a..9610dfe84 100644 --- a/modules/upgrade/partials/incompat-changes.adoc +++ b/modules/upgrade/partials/incompat-changes.adoc @@ -8,6 +8,12 @@ include::upgrade:partial$iceberg-breaking-changes.adoc[] -- ** Schema Registry no longer allows specifying a schema ID and version when registering a schema in read-write mode. You must use import mode to register a schema with a specific ID and version. See xref:manage:schema-reg/schema-reg-api.adoc#set-schema-registry-mode[Use the Schema Registry API] for more information. +** {empty} ++ +-- +include::shared:partial$tristate-behavior-change-25-3.adoc[] +-- + * {empty} + -- From ebb937eeff5a768cb045a52cb1c77678b0658103 Mon Sep 17 00:00:00 2001 From: Paulo Borges Date: Sat, 20 Dec 2025 15:32:03 -0300 Subject: [PATCH 4/7] update descriptions --- docs-data/property-overrides.json | 14 +++++++------- .../pages/release-notes/redpanda.adoc | 2 +- .../partials/properties/topic-properties.adoc | 18 ++++++++++-------- .../tristate-behavior-change-25-3.adoc | 2 +- 4 files changed, 19 insertions(+), 17 deletions(-) diff --git a/docs-data/property-overrides.json b/docs-data/property-overrides.json index 88c9d568b..acd3eab1f 100644 --- a/docs-data/property-overrides.json +++ b/docs-data/property-overrides.json @@ -670,7 +670,7 @@ "config_scope": "cluster" }, "delete.retention.ms": { - "description": "The retention time for tombstone records in a compacted topic. Redpanda removes tombstone records after the retention limit is exceeded.\n\nIf you have enabled Tiered Storage and set <> or <> for the topic, you cannot enable tombstone removal.\n\nIf both `delete.retention.ms` and the cluster property config_ref:tombstone_retention_ms,true,properties/cluster-properties[] are set, `delete.retention.ms` overrides the cluster level tombstone retention for an individual topic.\n\nThis property supports three states:\n\n* Positive value: Sets the milliseconds to retain tombstone records before removal.\n* 0: Tombstone records are immediately eligible for removal.\n* Negative value: No per-topic limit applied, inherits cluster default from xref:reference:properties/cluster-properties.adoc#tombstone_retention_ms[`tombstone_retention_ms`].", + "description": "The retention time for tombstone records in a compacted topic. Redpanda removes tombstone records after the retention limit is exceeded.\n\nIf you have enabled Tiered Storage and set <> or <> for the topic, you cannot enable tombstone removal.\n\nIf both `delete.retention.ms` and the cluster property config_ref:tombstone_retention_ms,true,properties/cluster-properties[] are set, `delete.retention.ms` overrides the cluster level tombstone retention for an individual topic.\n\nThis property supports three states:\n\n* Positive value: Sets the milliseconds to retain tombstone records before removal.\n* 0: Tombstone records are immediately eligible for removal.\n* Negative value: Disables tombstone removal entirely for this topic.", "related_topics": [ "xref:reference:properties/cluster-properties.adoc#tombstone_retention_ms[`tombstone_retention_ms`]", "xref:manage:cluster-maintenance/compaction-settings.adoc#tombstone-record-removal[Tombstone record removal]" @@ -1319,7 +1319,7 @@ "config_scope": "cluster" }, "min.cleanable.dirty.ratio": { - "description": "The minimum ratio between dirty and total bytes in closed segments before a partition's log is eligible for compaction in a compact topic.\n\nThis property supports three states:\n\n* Positive value: Sets the minimum dirty ratio (0.0 to 1.0) required before compaction.\n* 0: Compaction is always eligible regardless of dirty ratio.\n* Negative value: Uses the cluster default from xref:reference:properties/cluster-properties.adoc#min_cleanable_dirty_ratio[`min_cleanable_dirty_ratio`].", + "description": "The minimum ratio between dirty and total bytes in closed segments before a partition's log is eligible for compaction in a compact topic.\n\nThis property supports three states:\n\n* Positive value: Sets the minimum dirty ratio (0.0 to 1.0) required before compaction.\n* 0: Compaction is always eligible regardless of dirty ratio.\n* Negative value: This property is not considered when deciding if a log is eligible for compaction.", "related_topics": [ "xref:reference:properties/cluster-properties.adoc#min_cleanable_dirty_ratio[`min_cleanable_dirty_ratio`]" ], @@ -1688,7 +1688,7 @@ "config_scope": "topic" }, "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: No per-topic limit applied, inherits cluster default from xref:reference:properties/cluster-properties.adoc#retention_bytes[`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`]", @@ -1697,7 +1697,7 @@ "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: No per-topic limit applied, inherits cluster default from xref:reference:properties/cluster-properties.adoc#retention_local_target_bytes[`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.", "related_topics": [ "xref:reference:properties/cluster-properties.adoc#retention_local_target_bytes[`retention_local_target_bytes`]", "xref:manage:tiered-storage.adoc[Tiered Storage]" @@ -1705,7 +1705,7 @@ "config_scope": "topic" }, "retention.local.target.ms": { - "description": "A time-based retention limit for Tiered Storage that sets the maximum duration that a log's segment file for a topic is retained in local storage before cleanup.\n\nThis property supports three states:\n\n* Positive value: Sets the maximum milliseconds to retain data in local storage.\n* 0: Data in local storage is immediately eligible for cleanup.\n* Negative value: No per-topic limit applied, inherits cluster default from xref:reference:properties/cluster-properties.adoc#retention_local_target_ms_default[`retention_local_target_ms_default`].", + "description": "A time-based retention limit for Tiered Storage that sets the maximum duration that a log's segment file for a topic is retained in local storage before 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 milliseconds to retain data in local storage.\n* 0: Data in local storage is immediately eligible for cleanup.\n* Negative value: Disables time-based local retention override for this topic.", "related_topics": [ "xref:reference:properties/cluster-properties.adoc#retention_local_target_ms[`retention_local_target_ms`]", "xref:manage:tiered-storage.adoc[Tiered Storage]", @@ -1714,7 +1714,7 @@ "config_scope": "topic" }, "retention.ms": { - "description": "A time-based retention limit that configures the maximum duration that a log's segment file for a topic is retained before it becomes eligible to be cleaned up. To consume all data, a consumer of the topic must read from a segment before its `retention.ms` elapses, otherwise the segment may be compacted and/or deleted.\n\nIf `retention.ms` is set to a positive value, it overrides the cluster property xref:./cluster-properties.adoc#log_retention_ms[`log_retention_ms`] for the topic.\n\nWhen both size-based (`retention.bytes`) and time-based (`retention.ms`) retention limits are set, the earliest occurring limit applies.\n\nThis property supports three states:\n\n* Positive value: Sets the maximum milliseconds to retain data. After this duration, segments become eligible for cleanup.\n* 0: Data is immediately eligible for cleanup.\n* Negative value: No per-topic limit applied, inherits cluster default from xref:reference:properties/cluster-properties.adoc#log_retention_ms[`log_retention_ms`].", + "description": "A time-based retention limit that configures the maximum duration that a log's segment file for a topic is retained before it becomes eligible to be cleaned up. To consume all data, a consumer of the topic must read from a segment before its `retention.ms` elapses, otherwise the segment may be compacted and/or deleted.\n\nIf `retention.ms` is set to a positive value, it overrides the cluster property xref:./cluster-properties.adoc#log_retention_ms[`log_retention_ms`] for the topic.\n\nWhen both size-based (`retention.bytes`) and time-based (`retention.ms`) retention limits are set, the earliest occurring limit applies.\n\nThis property supports three states:\n\n* Positive value: Sets the maximum milliseconds to retain data. After this duration, segments become eligible for cleanup.\n* 0: Data is immediately eligible for cleanup.\n* Negative value: Disables time-based retention for this topic.", "related_topics": [ "xref:reference:properties/cluster-properties.adoc#log_retention_ms[`log_retention_ms`]", "xref:manage:cluster-maintenance/disk-utilization.adoc#configure-message-retention[Configure message retention]" @@ -1926,7 +1926,7 @@ "config_scope": "topic" }, "segment.ms": { - "description": "The maximum duration that a log segment of a topic is active (open for writes and not deletable). A periodic event, with `segment.ms` as its period, forcibly closes the active segment and transitions, or rolls, to a new active segment. The closed (inactive) segment is then eligible to be cleaned up according to cleanup and retention properties.\n\nIf set to a positive duration, `segment.ms` overrides the cluster property xref:./cluster-properties.adoc#log_segment_ms[`log_segment_ms`]. Values are automatically clamped between the cluster bounds set by xref:./cluster-properties.adoc#log_segment_ms_min[`log_segment_ms_min`] (default: 10 minutes) and xref:./cluster-properties.adoc#log_segment_ms_max[`log_segment_ms_max`] (default: 1 year). If your configured value exceeds these bounds, Redpanda uses the bound value and logs a warning. Check current cluster bounds with `rpk cluster config get log_segment_ms_min log_segment_ms_max`.\n\nThis property supports three states:\n\n* Positive value: Sets the maximum milliseconds a segment remains active before rolling to a new segment.\n* 0: Segments are immediately eligible for closure.\n* Negative value: Uses the cluster default from xref:reference:properties/cluster-properties.adoc#log_segment_ms[`log_segment_ms`].", + "description": "The maximum duration that a log segment of a topic is active (open for writes and not deletable). A periodic event, with `segment.ms` as its period, forcibly closes the active segment and transitions, or rolls, to a new active segment. The closed (inactive) segment is then eligible to be cleaned up according to cleanup and retention properties.\n\nIf set to a positive duration, `segment.ms` overrides the cluster property xref:./cluster-properties.adoc#log_segment_ms[`log_segment_ms`]. Values are automatically clamped between the cluster bounds set by xref:./cluster-properties.adoc#log_segment_ms_min[`log_segment_ms_min`] (default: 10 minutes) and xref:./cluster-properties.adoc#log_segment_ms_max[`log_segment_ms_max`] (default: 1 year). If your configured value exceeds these bounds, Redpanda uses the bound value and logs a warning. Check current cluster bounds with `rpk cluster config get log_segment_ms_min log_segment_ms_max`.\n\nFor topics with compaction enabled, `max.compaction.lag.ms` also acts as a limit to `segment.ms`.\n\nThis property supports three states:\n\n* Positive value: Sets the maximum milliseconds a segment remains active before rolling to a new segment.\n* 0: Segments are immediately eligible for closure.\n* Negative value: Disables time-based segment rolling for this topic.", "related_topics": [ "xref:reference:properties/cluster-properties.adoc#log_segment_ms[`log_segment_ms`]", "xref:reference:properties/cluster-properties.adoc#log_segment_ms_min[`log_segment_ms_min`]", diff --git a/modules/get-started/pages/release-notes/redpanda.adoc b/modules/get-started/pages/release-notes/redpanda.adoc index 270f85d21..376c7071d 100644 --- a/modules/get-started/pages/release-notes/redpanda.adoc +++ b/modules/get-started/pages/release-notes/redpanda.adoc @@ -159,7 +159,7 @@ The following topic properties now support enhanced tristate behavior: * xref:reference:properties/topic-properties.adoc#deleteretentionms[`delete.retention.ms`] * xref:reference:properties/topic-properties.adoc#mincleanabledirtyratio[`min.cleanable.dirty.ratio`] -Previously, these properties treated zero and negative values the same way. Now they support three distinct states: positive values set specific limits, zero provides immediate eligibility for cleanup/compaction, and negative values inherit cluster defaults. Review your topic configurations if you currently use zero values for these properties. +Previously, these properties treated zero and negative values the same way. Now they support three distinct states: positive values set specific limits, zero provides immediate eligibility for cleanup/compaction, and negative values disable the feature entirely. Review your topic configurations if you currently use zero values for these properties. === Deprecations diff --git a/modules/reference/partials/properties/topic-properties.adoc b/modules/reference/partials/properties/topic-properties.adoc index 237673d67..c0d8f86c5 100644 --- a/modules/reference/partials/properties/topic-properties.adoc +++ b/modules/reference/partials/properties/topic-properties.adoc @@ -325,7 +325,7 @@ This property supports three states: * Positive value: Sets the milliseconds to retain tombstone records before removal. * 0: Tombstone records are immediately eligible for removal. -* Negative value: No per-topic limit applied, inherits cluster default from xref:reference:properties/cluster-properties.adoc#tombstone_retention_ms[`tombstone_retention_ms`]. +* Negative value: Disables tombstone removal entirely for this topic. [cols="1s,2a"] |=== @@ -847,7 +847,7 @@ This property supports three states: * Positive value: Sets the minimum dirty ratio (0.0 to 1.0) required before compaction. * 0: Compaction is always eligible regardless of dirty ratio. -* Negative value: Uses the cluster default from xref:reference:properties/cluster-properties.adoc#min_cleanable_dirty_ratio[`min_cleanable_dirty_ratio`]. +* Negative value: This property is not considered when deciding if a log is eligible for compaction. [cols="1s,2a"] |=== @@ -1726,7 +1726,7 @@ This property supports three states: * Positive value: Sets the maximum bytes per partition. When exceeded, oldest data becomes eligible for cleanup. * 0: Partitions are immediately eligible for cleanup. -* Negative value: No per-topic limit applied, inherits cluster default from xref:reference:properties/cluster-properties.adoc#retention_bytes[`retention_bytes`]. +* Negative value: Disables size-based retention for this topic. [cols="1s,2a"] |=== @@ -1781,7 +1781,7 @@ This property supports three states: * Positive value: Sets the maximum bytes per partition in local storage before cleanup. * 0: Data in local storage is immediately eligible for cleanup. -* Negative value: No per-topic limit applied, inherits cluster default from xref:reference:properties/cluster-properties.adoc#retention_local_target_bytes[`retention_local_target_bytes`]. +* Negative value: Disables size-based local retention override for this topic. [cols="1s,2a"] |=== @@ -1828,13 +1828,13 @@ endif::[] // tag::category-tiered-storage[] === retention.local.target.ms -A time-based retention limit for Tiered Storage that sets the maximum duration that a log's segment file for a topic is retained in local storage before cleanup. +A time-based retention limit for Tiered Storage that sets the maximum duration that a log's segment file for a topic is retained in local storage before cleanup. It applies per partition and is equivalent to <> without Tiered Storage. This property supports three states: * Positive value: Sets the maximum milliseconds to retain data in local storage. * 0: Data in local storage is immediately eligible for cleanup. -* Negative value: No per-topic limit applied, inherits cluster default from xref:reference:properties/cluster-properties.adoc#retention_local_target_ms_default[`retention_local_target_ms_default`]. +* Negative value: Disables time-based local retention override for this topic. [cols="1s,2a"] |=== @@ -1893,7 +1893,7 @@ This property supports three states: * Positive value: Sets the maximum milliseconds to retain data. After this duration, segments become eligible for cleanup. * 0: Data is immediately eligible for cleanup. -* Negative value: No per-topic limit applied, inherits cluster default from xref:reference:properties/cluster-properties.adoc#log_retention_ms[`log_retention_ms`]. +* Negative value: Disables time-based retention for this topic. [cols="1s,2a"] |=== @@ -1999,11 +1999,13 @@ The maximum duration that a log segment of a topic is active (open for writes an If set to a positive duration, `segment.ms` overrides the cluster property xref:./cluster-properties.adoc#log_segment_ms[`log_segment_ms`]. Values are automatically clamped between the cluster bounds set by xref:./cluster-properties.adoc#log_segment_ms_min[`log_segment_ms_min`] (default: 10 minutes) and xref:./cluster-properties.adoc#log_segment_ms_max[`log_segment_ms_max`] (default: 1 year). If your configured value exceeds these bounds, Redpanda uses the bound value and logs a warning. Check current cluster bounds with `rpk cluster config get log_segment_ms_min log_segment_ms_max`. +For topics with compaction enabled, `max.compaction.lag.ms` also acts as a limit to `segment.ms`. + This property supports three states: * Positive value: Sets the maximum milliseconds a segment remains active before rolling to a new segment. * 0: Segments are immediately eligible for closure. -* Negative value: Uses the cluster default from xref:reference:properties/cluster-properties.adoc#log_segment_ms[`log_segment_ms`]. +* Negative value: Disables time-based segment rolling for this topic. [cols="1s,2a"] |=== diff --git a/modules/shared/partials/tristate-behavior-change-25-3.adoc b/modules/shared/partials/tristate-behavior-change-25-3.adoc index 17f640a92..8e7fa2460 100644 --- a/modules/shared/partials/tristate-behavior-change-25-3.adoc +++ b/modules/shared/partials/tristate-behavior-change-25-3.adoc @@ -1 +1 @@ -Starting in Redpanda v25.3, several topic properties support enhanced tristate behavior. Properties like `retention.ms`, `retention.bytes`, `segment.ms`, and others now distinguish between zero values (immediate eligibility for cleanup/compaction) and negative values (inherit cluster defaults). Previously, zero and negative values were treated the same way. For the complete list of affected properties and detailed information, see xref:25.3@get-started:release-notes/redpanda.adoc#behavior-changes[Redpanda v25.3 behavior changes]. Review your topic configurations if you currently use zero values for these properties. \ No newline at end of file +Starting in Redpanda v25.3, several topic properties support enhanced tristate behavior. Properties like `retention.ms`, `retention.bytes`, `segment.ms`, and others now distinguish between zero values (immediate eligibility for cleanup/compaction) and negative values (disable the feature entirely). Previously, zero and negative values were treated the same way. For the complete list of affected properties and detailed information, see xref:25.3@get-started:release-notes/redpanda.adoc#behavior-changes[Redpanda v25.3 behavior changes]. Review your topic configurations if you currently use zero values for these properties. \ No newline at end of file From af6651d695c4ea9a050b669a2c9121ad92af56aa Mon Sep 17 00:00:00 2001 From: Paulo Borges Date: Tue, 30 Dec 2025 19:43:53 -0300 Subject: [PATCH 5/7] Revert "github: modify github action to trigger whenever a commit is made to property-overrides" This reverts commit c94d60039f09ba77e6d91d04f873d3af6f67cad7. --- .github/workflows/update-property-docs.yaml | 79 ++++----------------- 1 file changed, 15 insertions(+), 64 deletions(-) diff --git a/.github/workflows/update-property-docs.yaml b/.github/workflows/update-property-docs.yaml index 96a2283ae..82cc43451 100644 --- a/.github/workflows/update-property-docs.yaml +++ b/.github/workflows/update-property-docs.yaml @@ -10,8 +10,6 @@ on: type: string repository_dispatch: types: [trigger-property-docs-generation] - push: - paths: ['docs-data/property-overrides.json'] jobs: generate-property-docs: @@ -38,7 +36,7 @@ jobs: - name: Checkout the repository uses: actions/checkout@v4 with: - ref: ${{ github.event_name == 'push' && github.ref || 'main' }} + ref: main token: ${{ env.ACTIONS_BOT_TOKEN }} - name: Set up Node.js @@ -56,62 +54,32 @@ jobs: echo "tag=${{ github.event.inputs.tag }}" >> $GITHUB_OUTPUT elif [ -n "${{ github.event.client_payload.tag }}" ]; then echo "tag=${{ github.event.client_payload.tag }}" >> $GITHUB_OUTPUT - elif [ "${{ github.event_name }}" = "push" ]; then - # For push events, use the current latest-redpanda-tag from antora.yml - CURRENT=$(grep 'latest-redpanda-tag:' antora.yml | awk '{print $2}' | tr -d "\"'") - echo "tag=$CURRENT" >> $GITHUB_OUTPUT - echo "🔄 Using current latest-redpanda-tag for override changes: $CURRENT" else echo "❌ No tag provided via input or dispatch payload" >&2 exit 1 fi - - name: Check if docs need regeneration + - name: Check if tag is newer than antora.yml latest id: version_check - env: - GH_TOKEN: ${{ env.ACTIONS_BOT_TOKEN }} run: | set -euo pipefail TAG="${{ steps.tag.outputs.tag }}" CURRENT=$(grep 'latest-redpanda-tag:' antora.yml | awk '{print $2}' | tr -d "\"'") echo "📄 Current latest-redpanda-tag in antora.yml: $CURRENT" - echo "🔖 Using tag: $TAG" + echo "🔖 Incoming tag: $TAG" - # For push events (override file changes), check if generated docs are up to date - if [ "${{ github.event_name }}" = "push" ]; then - echo "🔄 Override file changed — checking if generated docs need update" - - # Check if generated property docs exist and are newer than the override file - OVERRIDE_FILE="docs-data/property-overrides.json" - GENERATED_FILE="modules/reference/pages/properties/broker-properties.adoc" - - if [ -f "$GENERATED_FILE" ]; then - # Compare file modification times - if [ "$OVERRIDE_FILE" -nt "$GENERATED_FILE" ]; then - echo "🔄 Override file is newer than generated docs — regeneration needed" - echo "is_newer=true" >> $GITHUB_OUTPUT - else - echo "✅ Generated docs are up to date with override file — skipping" - echo "is_newer=false" >> $GITHUB_OUTPUT - fi - else - echo "🔄 Generated docs don't exist — regeneration needed" - echo "is_newer=true" >> $GITHUB_OUTPUT - fi - else - # Strip leading 'v' for numeric comparison - CUR_NUM=$(echo "$CURRENT" | sed 's/^v//') - NEW_NUM=$(echo "$TAG" | sed 's/^v//') + # Strip leading 'v' for numeric comparison + CUR_NUM=$(echo "$CURRENT" | sed 's/^v//') + NEW_NUM=$(echo "$TAG" | sed 's/^v//') - # Compare semver using sort -V - if [ "$(printf "%s\n%s" "$CUR_NUM" "$NEW_NUM" | sort -V | tail -n1)" = "$NEW_NUM" ] && [ "$CUR_NUM" != "$NEW_NUM" ]; then - echo "$TAG is newer than $CURRENT" - echo "is_newer=true" >> $GITHUB_OUTPUT - else - echo "$TAG is not newer than $CURRENT — skipping doc generation" - echo "is_newer=false" >> $GITHUB_OUTPUT - fi + # Compare semver using sort -V + if [ "$(printf "%s\n%s" "$CUR_NUM" "$NEW_NUM" | sort -V | tail -n1)" = "$NEW_NUM" ] && [ "$CUR_NUM" != "$NEW_NUM" ]; then + echo "$TAG is newer than $CURRENT" + echo "is_newer=true" >> $GITHUB_OUTPUT + else + echo "$TAG is not newer than $CURRENT — skipping doc generation" + echo "is_newer=false" >> $GITHUB_OUTPUT fi - name: Generate property docs @@ -127,30 +95,13 @@ jobs: env: GITHUB_TOKEN: ${{ env.ACTIONS_BOT_TOKEN }} - - name: Commit generated docs to current branch - if: steps.version_check.outputs.is_newer == 'true' && github.event_name == 'push' - run: | - git config --local user.email "vbotbuildovich@users.noreply.github.com" - git config --local user.name "vbotbuildovich" - - # Add generated files - git add modules/reference/pages/properties/ modules/reference/partials/properties/ - - # Check if there are changes to commit - if git diff --staged --quiet; then - echo "No changes to commit" - else - git commit -m "auto-docs: Regenerate property docs after override changes" - git push origin HEAD - fi - - name: Create pull request - if: steps.version_check.outputs.is_newer == 'true' && github.event_name != 'push' + if: steps.version_check.outputs.is_newer == 'true' uses: peter-evans/create-pull-request@v6 with: token: ${{ env.ACTIONS_BOT_TOKEN }} commit-message: "auto-docs: Update property docs for ${{ steps.tag.outputs.tag }}" - branch: "update-property-docs-${{ steps.tag.outputs.tag }}" + branch: update-property-docs-${{ steps.tag.outputs.tag }} title: "auto-docs: Update property docs for tag ${{ steps.tag.outputs.tag }}" body: | This PR auto-generates updated Redpanda property documentation for **${{ steps.tag.outputs.tag }}**. From e7fef2a5301cbb745031290d5daf0b77539e62f0 Mon Sep 17 00:00:00 2001 From: Paulo Borges Date: Wed, 7 Jan 2026 12:12:30 -0300 Subject: [PATCH 6/7] fix links --- docs-data/property-overrides.json | 2 +- .../pages/release-notes/redpanda.adoc | 18 +++++++++--------- 2 files changed, 10 insertions(+), 10 deletions(-) diff --git a/docs-data/property-overrides.json b/docs-data/property-overrides.json index acd3eab1f..fc707e32b 100644 --- a/docs-data/property-overrides.json +++ b/docs-data/property-overrides.json @@ -1705,7 +1705,7 @@ "config_scope": "topic" }, "retention.local.target.ms": { - "description": "A time-based retention limit for Tiered Storage that sets the maximum duration that a log's segment file for a topic is retained in local storage before 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 milliseconds to retain data in local storage.\n* 0: Data in local storage is immediately eligible for cleanup.\n* Negative value: Disables time-based local retention override for this topic.", + "description": "A time-based retention limit for Tiered Storage that sets the maximum duration that a log's segment file for a topic is retained in local storage before 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 milliseconds to retain data in local storage.\n* 0: Data in local storage is immediately eligible for cleanup.\n* Negative value: Disables time-based local retention override for this topic.", "related_topics": [ "xref:reference:properties/cluster-properties.adoc#retention_local_target_ms[`retention_local_target_ms`]", "xref:manage:tiered-storage.adoc[Tiered Storage]", diff --git a/modules/get-started/pages/release-notes/redpanda.adoc b/modules/get-started/pages/release-notes/redpanda.adoc index 376c7071d..2dc4ad7b5 100644 --- a/modules/get-started/pages/release-notes/redpanda.adoc +++ b/modules/get-started/pages/release-notes/redpanda.adoc @@ -149,15 +149,15 @@ The following configuration properties have new default values in v25.3: The following topic properties now support enhanced tristate behavior: -* xref:reference:properties/topic-properties.adoc#segmentms[`segment.ms`] -* xref:reference:properties/topic-properties.adoc#retentionbytes[`retention.bytes`] -* xref:reference:properties/topic-properties.adoc#retentionms[`retention.ms`] -* xref:reference:properties/topic-properties.adoc#retentionlocaltargetbytes[`retention.local.target.bytes`] -* xref:reference:properties/topic-properties.adoc#retentionlocaltargetms[`retention.local.target.ms`] -* xref:reference:properties/topic-properties.adoc#initialretentionlocaltargetbytes[`initial.retention.local.target.bytes`] -* xref:reference:properties/topic-properties.adoc#initialretentionlocaltargetms[`initial.retention.local.target.ms`] -* xref:reference:properties/topic-properties.adoc#deleteretentionms[`delete.retention.ms`] -* xref:reference:properties/topic-properties.adoc#mincleanabledirtyratio[`min.cleanable.dirty.ratio`] +* xref:reference:properties/topic-properties.adoc#segment-ms[`segment.ms`] +* xref:reference:properties/topic-properties.adoc#retention-bytes[`retention.bytes`] +* xref:reference:properties/topic-properties.adoc#retention-ms[`retention.ms`] +* xref:reference:properties/topic-properties.adoc#retention-local-target-bytes[`retention.local.target.bytes`] +* xref:reference:properties/topic-properties.adoc#retention-local-target-ms[`retention.local.target.ms`] +* xref:reference:properties/topic-properties.adoc#initial-retention-local-target-bytes[`initial.retention.local.target.bytes`] +* xref:reference:properties/topic-properties.adoc#initial-retention-local-target-ms[`initial.retention.local.target.ms`] +* xref:reference:properties/topic-properties.adoc#delete-retention-ms[`delete.retention.ms`] +* xref:reference:properties/topic-properties.adoc#min-cleanable-dirty-ratio[`min.cleanable.dirty.ratio`] Previously, these properties treated zero and negative values the same way. Now they support three distinct states: positive values set specific limits, zero provides immediate eligibility for cleanup/compaction, and negative values disable the feature entirely. Review your topic configurations if you currently use zero values for these properties. From 0dc9aed1e18fce501f36a7460a31e6f97722fde8 Mon Sep 17 00:00:00 2001 From: Paulo Borges Date: Wed, 7 Jan 2026 15:54:17 -0300 Subject: [PATCH 7/7] update --- .../redpanda-properties-v25.3.4.json | 18 +++++++++--------- .../partials/properties/topic-properties.adoc | 11 +++++++++-- 2 files changed, 18 insertions(+), 11 deletions(-) diff --git a/modules/reference/attachments/redpanda-properties-v25.3.4.json b/modules/reference/attachments/redpanda-properties-v25.3.4.json index cfea58e4e..80785ea92 100644 --- a/modules/reference/attachments/redpanda-properties-v25.3.4.json +++ b/modules/reference/attachments/redpanda-properties-v25.3.4.json @@ -5094,7 +5094,7 @@ "corresponding_cluster_property": "tombstone_retention_ms", "default": null, "defined_in": "src/v/kafka/protocol/topic_properties.h", - "description": "The retention time for tombstone records in a compacted topic. Redpanda removes tombstone records after the retention limit is exceeded.\n\nIf you have enabled Tiered Storage and set <> or <> for the topic, you cannot enable tombstone removal.\n\nIf both `delete.retention.ms` and the cluster property config_ref:tombstone_retention_ms,true,properties/cluster-properties[] are set, `delete.retention.ms` overrides the cluster level tombstone retention for an individual topic.", + "description": "The retention time for tombstone records in a compacted topic. Redpanda removes tombstone records after the retention limit is exceeded.\n\nIf you have enabled Tiered Storage and set <> or <> for the topic, you cannot enable tombstone removal.\n\nIf both `delete.retention.ms` and the cluster property config_ref:tombstone_retention_ms,true,properties/cluster-properties[] are set, `delete.retention.ms` overrides the cluster level tombstone retention for an individual topic.\n\nThis property supports three states:\n\n* Positive value: Sets the milliseconds to retain tombstone records before removal.\n* 0: Tombstone records are immediately eligible for removal.\n* Negative value: Disables tombstone removal entirely for this topic.", "is_deprecated": false, "is_enterprise": false, "is_topic_property": true, @@ -7063,7 +7063,7 @@ "corresponding_cluster_property": "initial_retention_local_target_bytes_default", "default": null, "defined_in": "src/v/kafka/protocol/topic_properties.h", - "description": "A size-based initial retention limit for Tiered Storage that determines how much data in local storage is transferred to a partition replica when a cluster is resized. If `null` (default), all locally retained data is transferred.", + "description": "A size-based initial retention limit for Tiered Storage that determines how much data in local storage is transferred to a partition replica when a cluster is resized. If `null` (default), all locally retained data is transferred.\n\nThis property supports three states:\n\n* Positive value: Sets the maximum bytes of local data to transfer during cluster resize.\n* 0: No local data is transferred during cluster resize.\n* Negative value: All locally retained data is transferred (default behavior).", "is_deprecated": false, "is_enterprise": false, "is_topic_property": true, @@ -7089,7 +7089,7 @@ "corresponding_cluster_property": "initial_retention_local_target_ms_default", "default": null, "defined_in": "src/v/kafka/protocol/topic_properties.h", - "description": "A time-based initial retention limit for Tiered Storage that determines how much data in local storage is transferred to a partition replica when a cluster is resized. If `null` (default), all locally retained data is transferred.", + "description": "A time-based initial retention limit for Tiered Storage that determines how much data in local storage is transferred to a partition replica when a cluster is resized. If `null` (default), all locally retained data is transferred.\n\nThis property supports three states:\n\n* Positive value: Sets the maximum age (milliseconds) of local data to transfer during cluster resize.\n* 0: No local data is transferred during cluster resize.\n* Negative value: All locally retained data is transferred (default behavior).", "is_deprecated": false, "is_enterprise": false, "is_topic_property": true, @@ -9489,7 +9489,7 @@ "corresponding_cluster_property": "min_cleanable_dirty_ratio", "default": 0.2, "defined_in": "src/v/kafka/server/handlers/topics/types.h", - "description": "The minimum ratio between the number of bytes in dirty segments and the total number of bytes in closed segments that must be reached before a partition's log is eligible for compaction in a compact topic.", + "description": "The minimum ratio between dirty and total bytes in closed segments before a partition's log is eligible for compaction in a compact topic.\n\nThis property supports three states:\n\n* Positive value: Sets the minimum dirty ratio (0.0 to 1.0) required before compaction.\n* 0: Compaction is always eligible regardless of dirty ratio.\n* Negative value: This property is not considered when deciding if a log is eligible for compaction.", "is_deprecated": false, "is_enterprise": false, "is_topic_property": true, @@ -11485,7 +11485,7 @@ "corresponding_cluster_property": "retention_bytes", "default": null, "defined_in": "src/v/kafka/protocol/topic_properties.h", - "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.", + "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.", "is_deprecated": false, "is_enterprise": false, "is_topic_property": true, @@ -11512,7 +11512,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.", + "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, @@ -11539,7 +11539,7 @@ "default": 86400000, "default_human_readable": "1 day", "defined_in": "src/v/kafka/protocol/topic_properties.h", - "description": "A time-based retention limit for Tiered Storage that sets the maximum duration that a log's segment file for a topic is retained in local storage before it's eligible for cleanup. This property is equivalent to <> without Tiered Storage.", + "description": "A time-based retention limit for Tiered Storage that sets the maximum duration that a log's segment file for a topic is retained in local storage before 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 milliseconds to retain data in local storage.\n* 0: Data in local storage is immediately eligible for cleanup.\n* Negative value: Disables time-based local retention override for this topic.", "is_deprecated": false, "is_enterprise": false, "is_topic_property": true, @@ -11567,7 +11567,7 @@ "default": 604800000, "default_human_readable": "1 week", "defined_in": "src/v/kafka/protocol/topic_properties.h", - "description": "A time-based retention limit that configures the maximum duration that a log's segment file for a topic is retained before it becomes eligible to be cleaned up. To consume all data, a consumer of the topic must read from a segment before its `retention.ms` elapses, otherwise the segment may be compacted and/or deleted. If a non-positive value, no per-topic limit is applied.\n\nIf `retention.ms` is set to a positive value, it overrides the cluster property xref:./cluster-properties.adoc#log_retention_ms[`log_retention_ms`] for the topic.\n\nWhen both size-based (`retention.bytes`) and time-based (`retention.ms`) retention limits are set, the earliest occurring limit applies.", + "description": "A time-based retention limit that configures the maximum duration that a log's segment file for a topic is retained before it becomes eligible to be cleaned up. To consume all data, a consumer of the topic must read from a segment before its `retention.ms` elapses, otherwise the segment may be compacted and/or deleted.\n\nIf `retention.ms` is set to a positive value, it overrides the cluster property xref:./cluster-properties.adoc#log_retention_ms[`log_retention_ms`] for the topic.\n\nWhen both size-based (`retention.bytes`) and time-based (`retention.ms`) retention limits are set, the earliest occurring limit applies.\n\nThis property supports three states:\n\n* Positive value: Sets the maximum milliseconds to retain data. After this duration, segments become eligible for cleanup.\n* 0: Data is immediately eligible for cleanup.\n* Negative value: Disables time-based retention for this topic.", "is_deprecated": false, "is_enterprise": false, "is_topic_property": true, @@ -12564,7 +12564,7 @@ "corresponding_cluster_property": "log_segment_ms", "default": "2 weeks", "defined_in": "src/v/kafka/server/handlers/topics/types.h", - "description": "The maximum duration that a log segment of a topic is active (open for writes and not deletable). A periodic event, with `segment.ms` as its period, forcibly closes the active segment and transitions, or rolls, to a new active segment. The closed (inactive) segment is then eligible to be cleaned up according to cleanup and retention properties.\n\nIf set to a positive duration, `segment.ms` overrides the cluster property xref:./cluster-properties.adoc#log_segment_ms[`log_segment_ms`]. Values are automatically clamped between the cluster bounds set by xref:./cluster-properties.adoc#log_segment_ms_min[`log_segment_ms_min`] (default: 10 minutes) and xref:./cluster-properties.adoc#log_segment_ms_max[`log_segment_ms_max`] (default: 1 year). If your configured value exceeds these bounds, Redpanda uses the bound value and logs a warning. Check current cluster bounds with `rpk cluster config get log_segment_ms_min log_segment_ms_max`.", + "description": "The maximum duration that a log segment of a topic is active (open for writes and not deletable). A periodic event, with `segment.ms` as its period, forcibly closes the active segment and transitions, or rolls, to a new active segment. The closed (inactive) segment is then eligible to be cleaned up according to cleanup and retention properties.\n\nIf set to a positive duration, `segment.ms` overrides the cluster property xref:./cluster-properties.adoc#log_segment_ms[`log_segment_ms`]. Values are automatically clamped between the cluster bounds set by xref:./cluster-properties.adoc#log_segment_ms_min[`log_segment_ms_min`] (default: 10 minutes) and xref:./cluster-properties.adoc#log_segment_ms_max[`log_segment_ms_max`] (default: 1 year). If your configured value exceeds these bounds, Redpanda uses the bound value and logs a warning. Check current cluster bounds with `rpk cluster config get log_segment_ms_min log_segment_ms_max`.\n\nFor topics with compaction enabled, `max.compaction.lag.ms` also acts as a limit to `segment.ms`.\n\nThis property supports three states:\n\n* Positive value: Sets the maximum milliseconds a segment remains active before rolling to a new segment.\n* 0: Segments are immediately eligible for closure.\n* Negative value: Disables time-based segment rolling for this topic.", "is_deprecated": false, "is_enterprise": false, "is_topic_property": true, diff --git a/modules/reference/partials/properties/topic-properties.adoc b/modules/reference/partials/properties/topic-properties.adoc index c0d8f86c5..1463d30bf 100644 --- a/modules/reference/partials/properties/topic-properties.adoc +++ b/modules/reference/partials/properties/topic-properties.adoc @@ -457,10 +457,16 @@ endif::[] // end::category-performance-cluster[] +// tag::redpanda-cloud[] === iceberg_rest_catalog_credentials_source Configuration property: iceberg_rest_catalog_credentials_source +ifdef::env-cloud[] +NOTE: This property is available only in Redpanda Cloud BYOC deployments. +endif::[] + + [cols="1s,2a"] |=== | Property | Value @@ -473,7 +479,7 @@ Configuration property: iceberg_rest_catalog_credentials_source | Default | ifdef::env-cloud[] -Available in the Redpanda Cloud Console +Available in the Redpanda Cloud Console (editable) endif::[] ifndef::env-cloud[] `null` @@ -492,6 +498,7 @@ endif::[] |=== +// end::redpanda-cloud[] // tag::category-tiered-storage[] === initial.retention.local.target.bytes @@ -1828,7 +1835,7 @@ endif::[] // tag::category-tiered-storage[] === retention.local.target.ms -A time-based retention limit for Tiered Storage that sets the maximum duration that a log's segment file for a topic is retained in local storage before cleanup. It applies per partition and is equivalent to <> without Tiered Storage. +A time-based retention limit for Tiered Storage that sets the maximum duration that a log's segment file for a topic is retained in local storage before cleanup. It applies per partition and is equivalent to <> without Tiered Storage. This property supports three states: