fix(backups): restore Kafka 3.x topic configs that Kafka 4 rejects

Every Kafka now runs 4.x, and a topic-metadata backup taken on Kafka
3.8 or 3.9 can record message.format.version,
message.downconversion.enable or message.timestamp.difference.max.ms,
which Kafka 4 removed, or a segment.bytes below 1 MiB, the minimum
Kafka 4 raised it to from 14 bytes. A 4.x broker rejects each of them,
so the restore stopped at the first one, leaving that topic
half-configured and every later topic unrestored, and a rerun failed
on the same line.

The restore now skips the removed keys and raises a smaller
segment.bytes to the minimum, each with a warning, and applies the
rest. segment.bytes is read the way Kafka reads it: trimmed, with an
optional sign, leading zeros decimal.

Assisted-by: LLM
Signed-off-by: Aleksei Sviridkin <f@lex.la>
This commit is contained in:
Aleksei Sviridkin committed 2026-11-17 12:22:56 +03:00
1 parent 0729a6f691
commit a48a2f2599
2 files changed
+110 -1

No files matched your search

+88 -1
View File
@@ -106,7 +106,19 @@ if [ "\$mode" = describe ]; then
[ -n "\${CFG_FAIL:-}" ] && exit 3
cat "$STATE/cfg.\$name" 2>/dev/null || true; exit 0
fi
if [ "\$mode" = alter ]; then echo "\$name \$add" >> "$STATE/configs_applied"; exit 0; fi
if [ "\$mode" = alter ]; then
# Topic configs a Kafka 4 broker no longer knows.
case "\${add%%=*}" in
message.downconversion.enable|message.format.version|message.timestamp.difference.max.ms)
echo "InvalidConfigurationException: Unknown topic config name: \${add%%=*}" >&2; exit 1 ;;
esac
# Kafka 4 raised the segment.bytes floor to 1 MiB.
case "\$add" in
segment.bytes=*)
[ "\${add#*=}" -ge 1048576 ] || { echo "InvalidConfigurationException: Invalid value \${add#*=} for configuration segment.bytes: Value must be at least 1048576" >&2; exit 1; } ;;
esac
echo "\$name \$add" >> "$STATE/configs_applied"; exit 0
fi
exit 0
STUB
@@ -243,6 +255,81 @@ write_backup_object() {
grep -qxF "orders cleanup.policy=[compact,delete]" "$STATE/configs_applied"
}
@test "restore of a Kafka 3.x backup skips the topic configs Kafka 4 removed and restores the rest" {
init_stubs
{
printf 'T\torders\t3\t1\n'
printf 'C\torders\tmessage.format.version\t3.0-IV1\n'
printf 'C\torders\tmessage.downconversion.enable\ttrue\n'
printf 'C\torders\tmessage.timestamp.difference.max.ms\t60000\n'
printf 'C\torders\tretention.ms\t86400000\n'
printf 'T\tpayments\t2\t1\n'
printf 'C\tpayments\tcleanup.policy\tcompact\n'
} > "$STATE/s3_object"
: > "$STATE/topics"
out=$(MODE=restore S3_ENDPOINT="https://s3.example.org" bash "$SCRIPT" 2>&1)
grep -qxF "orders retention.ms=86400000" "$STATE/configs_applied"
grep -qxF "create payments 2" "$STATE/actions"
grep -qxF "payments cleanup.policy=compact" "$STATE/configs_applied"
for k in message.format.version message.downconversion.enable message.timestamp.difference.max.ms; do
printf '%s\n' "$out" | grep -qF "orders: skipping $k"
done
}
@test "restore of a Kafka 3.x backup raises segment.bytes below the Kafka 4 floor and restores the rest" {
init_stubs
{
printf 'T\torders\t3\t1\n'
printf 'C\torders\tretention.ms\t86400000\n'
printf 'C\torders\tsegment.bytes\t524288\n'
printf 'T\tpayments\t2\t1\n'
printf 'C\tpayments\tsegment.bytes\t1048576\n'
printf 'T\tpadded\t1\t1\n'
printf 'C\tpadded\tsegment.bytes\t 524288 \n'
printf 'T\tsigned\t1\t1\n'
printf 'C\tsigned\tsegment.bytes\t+524288\n'
printf 'T\tctrl\t1\t1\n'
printf 'C\tctrl\tsegment.bytes\t\013524288\n'
printf 'T\tzeros\t1\t1\n'
printf 'C\tzeros\tsegment.bytes\t0524288\n'
printf 'T\tlarge\t1\t1\n'
printf 'C\tlarge\tsegment.bytes\t02000000\n'
printf 'T\tnegative\t1\t1\n'
printf 'C\tnegative\tsegment.bytes\t-2000000\n'
} > "$STATE/s3_object"
: > "$STATE/topics"
out=$(MODE=restore S3_ENDPOINT="https://s3.example.org" bash "$SCRIPT" 2>&1)
grep -qxF "orders retention.ms=86400000" "$STATE/configs_applied"
grep -qxF "orders segment.bytes=1048576" "$STATE/configs_applied"
grep -qxF "create payments 2" "$STATE/actions"
grep -qxF "payments segment.bytes=1048576" "$STATE/configs_applied"
printf '%s\n' "$out" | grep -qF "orders: raising segment.bytes from 524288 to 1048576"
# Kafka trims the value and reads it with Integer.parseInt, which takes a sign.
grep -qxF "padded segment.bytes=1048576" "$STATE/configs_applied"
grep -qxF "signed segment.bytes=1048576" "$STATE/configs_applied"
# A tab is a field separator in the backup, so a control character pads instead.
grep -qxF "ctrl segment.bytes=1048576" "$STATE/configs_applied"
grep -qxF "zeros segment.bytes=1048576" "$STATE/configs_applied"
grep -qxF "large segment.bytes=02000000" "$STATE/configs_applied"
grep -qxF "negative segment.bytes=1048576" "$STATE/configs_applied"
if printf '%s\n' "$out" | grep -qF "payments: raising"; then echo "warned about a value at the floor" >&2; return 1; fi
}
# Integer.parseInt rejects it, so the value reaches Kafka as it is and Kafka refuses it.
@test "restore passes a segment.bytes Kafka cannot parse as an integer through unchanged" {
init_stubs
{
printf 'T\texp\t1\t1\n'
printf 'C\texp\tsegment.bytes\t1e3\n'
} > "$STATE/s3_object"
: > "$STATE/topics"
rc=0
out=$(MODE=restore S3_ENDPOINT="https://s3.example.org" bash "$SCRIPT" 2>&1) || rc=$?
[ "$rc" -ne 0 ]
printf '%s\n' "$out" | grep -qF "Invalid value 1e3 for configuration segment.bytes"
if printf '%s\n' "$out" | grep -qF "raising"; then echo "rewrote a value Kafka cannot parse" >&2; return 1; fi
}
@test "restore fails loudly on a replication-factor mismatch" {
init_stubs
printf 'T\torders\t3\t2\n' > "$STATE/s3_object" # backup wants RF 2
@@ -5,6 +5,9 @@ set -euo pipefail
# kafka-topics.sh / kafka-configs.sh; the Job never sets it.
BIN="${BIN:-/opt/kafka/bin}"
TAB=$(printf '\t')
# Kafka 4 rejects a smaller topic segment.bytes; Kafka 3.x accepted down to 14.
SEGMENT_BYTES_MIN=1048576
KAFKA_INTEGER=$'^[\001- ]*([+-]?)0*([0-9]+)[\001- ]*$'
# Overridable for the same reason as BIN: hack/kafka-backup-script.bats points it
# at a per-test path so runs cannot read back a previous test's records. The Job
# never sets it.
@@ -197,6 +200,25 @@ else
;;
C)
t=$a; k=$b; v=$c
# A backup taken on Kafka 3.x can carry topic configs Kafka 4.2/4.3
# reject, which would stop the restore halfway. The same limits are in
# packages/apps/kafka/templates/topics.yaml,
# packages/core/platform/templates/_helpers.tpl and
# packages/core/platform/images/migrations/migrations/61.
case "${k}" in
message.downconversion.enable|message.format.version|message.timestamp.difference.max.ms)
echo " config ${t}: skipping ${k}, removed in Kafka 4" >&2
continue
;;
segment.bytes)
# Kafka trims characters up to U+0020 and reads the rest with
# Integer.parseInt, which allows a sign and leading zeros.
if [[ "${v}" =~ ${KAFKA_INTEGER} ]] && [ "${BASH_REMATCH[1]#+}${BASH_REMATCH[2]}" -lt "${SEGMENT_BYTES_MIN}" ]; then
echo " config ${t}: raising segment.bytes from ${BASH_REMATCH[1]#+}${BASH_REMATCH[2]} to ${SEGMENT_BYTES_MIN}, the Kafka 4 minimum" >&2
v=${SEGMENT_BYTES_MIN}
fi
;;
esac
# Bracket-group only when the value contains a comma, so kafka-configs
# does not split it into bogus key=val tokens.
case "${v}" in