This is an automated email from the ASF dual-hosted git repository.
oscerd pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/camel.git
The following commit(s) were added to refs/heads/main by this push:
new 03e6d09f772d CAMEL-23584: docs - sync camel-kafka 4.18 / 4.14
upgrade-guide entries to main
03e6d09f772d is described below
commit 03e6d09f772d4b55a336047024cb55beb652a706
Author: Andrea Cosentino <[email protected]>
AuthorDate: Mon Jun 8 09:20:53 2026 +0200
CAMEL-23584: docs - sync camel-kafka 4.18 / 4.14 upgrade-guide entries to
main
Adds the "camel-kafka - potential breaking change" section to
camel-4x-upgrade-guide-4_18.adoc and camel-4x-upgrade-guide-4_14.adoc on
main,
matching the entry already present in camel-4x-upgrade-guide-4_21.adoc.
The camel-kafka header constant rename (CAMEL-23584) was backported to
camel-4.18.x (#23629) and camel-4.14.x (#23632); the maintenance-branch
backports omit the upgrade-guide change, so the version-specific guide
entries
for those release lines are recorded here on main (per the backport
upgrade-guide policy).
Tracker: CAMEL-23577
Closes #23637
---
.../ROOT/pages/camel-4x-upgrade-guide-4_14.adoc | 69 ++++++++++++++++++++++
.../ROOT/pages/camel-4x-upgrade-guide-4_18.adoc | 69 ++++++++++++++++++++++
2 files changed, 138 insertions(+)
diff --git
a/docs/user-manual/modules/ROOT/pages/camel-4x-upgrade-guide-4_14.adoc
b/docs/user-manual/modules/ROOT/pages/camel-4x-upgrade-guide-4_14.adoc
index 7fc2956a8d7f..5ae207b4d33d 100644
--- a/docs/user-manual/modules/ROOT/pages/camel-4x-upgrade-guide-4_14.adoc
+++ b/docs/user-manual/modules/ROOT/pages/camel-4x-upgrade-guide-4_14.adoc
@@ -633,3 +633,72 @@ between the transport `from` and the `dns:` `to`. Allowing
untrusted senders
to drive `DnsConstants.DNS_SERVER` (the recursive resolver target in
`dns:dig`) without such a mapping step is not the intended use of the
component.
+
+=== camel-kafka - potential breaking change
+
+The Exchange header constants in `KafkaConstants` used header values in the
+lowercase / dotted `kafka.*` namespace, outside the `Camel` namespace, and were
+therefore not filtered by the default `HeaderFilterStrategy` on upstream HTTP /
+REST consumers. They have been renamed to follow the Camel naming convention
+used across the rest of the component catalog. The Java field names are
+unchanged; only the header string values have changed:
+
+[options="header"]
+|===
+| Constant | Previous value | New value
+| `KafkaConstants.PARTITION_KEY` | `kafka.PARTITION_KEY` |
`CamelKafkaPartitionKey`
+| `KafkaConstants.PARTITION` | `kafka.PARTITION` | `CamelKafkaPartition`
+| `KafkaConstants.KEY` | `kafka.KEY` | `CamelKafkaKey`
+| `KafkaConstants.TOPIC` | `kafka.TOPIC` | `CamelKafkaTopic`
+| `KafkaConstants.OVERRIDE_TOPIC` | `kafka.OVERRIDE_TOPIC` |
`CamelKafkaOverrideTopic`
+| `KafkaConstants.OFFSET` | `kafka.OFFSET` | `CamelKafkaOffset`
+| `KafkaConstants.HEADERS` | `kafka.HEADERS` | `CamelKafkaHeaders`
+| `KafkaConstants.LAST_RECORD_BEFORE_COMMIT` |
`kafka.LAST_RECORD_BEFORE_COMMIT` | `CamelKafkaLastRecordBeforeCommit`
+| `KafkaConstants.LAST_POLL_RECORD` | `kafka.LAST_POLL_RECORD` |
`CamelKafkaLastPollRecord`
+| `KafkaConstants.TIMESTAMP` | `kafka.TIMESTAMP` | `CamelKafkaTimestamp`
+| `KafkaConstants.OVERRIDE_TIMESTAMP` | `kafka.OVERRIDE_TIMESTAMP` |
`CamelKafkaOverrideTimestamp`
+| `KafkaConstants.KAFKA_RECORD_META` | `kafka.RECORD_META` |
`CamelKafkaRecordMeta`
+|===
+
+`KafkaConstants.MANUAL_COMMIT` was already `Camel`-prefixed
+(`CamelKafkaManualCommit`) and is unchanged.
+
+Routes that reference the constants symbolically (for example
+`setHeader(KafkaConstants.OVERRIDE_TOPIC, ...)`) continue to work without
+changes. Routes that set or read the headers by their literal string values
+(for example `setHeader("kafka.OVERRIDE_TOPIC", ...)` or Simple expressions
such
+as `${headers[kafka.TOPIC]}`) must be updated to use the new values:
+
+[source,java]
+----
+// before
+from("platform-http:/api/events")
+ .setHeader("kafka.OVERRIDE_TOPIC", constant("events.topic"))
+ .to("kafka:default?brokers=localhost:9092");
+
+// after
+from("platform-http:/api/events")
+ .setHeader(KafkaConstants.OVERRIDE_TOPIC, constant("events.topic"))
+ .to("kafka:default?brokers=localhost:9092");
+----
+
+The generated Endpoint DSL header accessors on `KafkaEndpointBuilderFactory`
+keep their method names (`kafkaOverrideTopic()`, `kafkaTopic()`,
+`kafkaPartitionKey()`, ...); only the returned string value reflects the new
+`CamelKafka*` convention.
+
+==== Behaviour change: cross-transport propagation of kafka.* headers
+
+Because the renamed header values now begin with `Camel`, they are filtered by
+the standard transport `HeaderFilterStrategy` (`HttpHeaderFilterStrategy`,
+`JmsHeaderFilterStrategy`, etc.) when crossing a transport boundary, by design
+— `Camel*` headers are framework-internal and are not propagated over the wire.
+
+Routes that bridge an external transport (HTTP, JMS, ...) into a `kafka:`
+producer and let the sender choose the destination topic via the
+`kafka.OVERRIDE_TOPIC` header must therefore carry that value in a
+non-`Camel`-prefixed application header and map it to
+`KafkaConstants.OVERRIDE_TOPIC` in the route between the transport `from` and
+the `kafka:` `to`. Allowing untrusted senders to drive
+`KafkaConstants.OVERRIDE_TOPIC` (which redirects the producer's target topic)
+without such a mapping step is not the intended use of the component.
diff --git
a/docs/user-manual/modules/ROOT/pages/camel-4x-upgrade-guide-4_18.adoc
b/docs/user-manual/modules/ROOT/pages/camel-4x-upgrade-guide-4_18.adoc
index 9094e00eb0b5..0ffa575728cb 100644
--- a/docs/user-manual/modules/ROOT/pages/camel-4x-upgrade-guide-4_18.adoc
+++ b/docs/user-manual/modules/ROOT/pages/camel-4x-upgrade-guide-4_18.adoc
@@ -834,3 +834,72 @@ between the transport `from` and the `dns:` `to`. Allowing
untrusted senders
to drive `DnsConstants.DNS_SERVER` (the recursive resolver target in
`dns:dig`) without such a mapping step is not the intended use of the
component.
+
+=== camel-kafka - potential breaking change
+
+The Exchange header constants in `KafkaConstants` used header values in the
+lowercase / dotted `kafka.*` namespace, outside the `Camel` namespace, and were
+therefore not filtered by the default `HeaderFilterStrategy` on upstream HTTP /
+REST consumers. They have been renamed to follow the Camel naming convention
+used across the rest of the component catalog. The Java field names are
+unchanged; only the header string values have changed:
+
+[options="header"]
+|===
+| Constant | Previous value | New value
+| `KafkaConstants.PARTITION_KEY` | `kafka.PARTITION_KEY` |
`CamelKafkaPartitionKey`
+| `KafkaConstants.PARTITION` | `kafka.PARTITION` | `CamelKafkaPartition`
+| `KafkaConstants.KEY` | `kafka.KEY` | `CamelKafkaKey`
+| `KafkaConstants.TOPIC` | `kafka.TOPIC` | `CamelKafkaTopic`
+| `KafkaConstants.OVERRIDE_TOPIC` | `kafka.OVERRIDE_TOPIC` |
`CamelKafkaOverrideTopic`
+| `KafkaConstants.OFFSET` | `kafka.OFFSET` | `CamelKafkaOffset`
+| `KafkaConstants.HEADERS` | `kafka.HEADERS` | `CamelKafkaHeaders`
+| `KafkaConstants.LAST_RECORD_BEFORE_COMMIT` |
`kafka.LAST_RECORD_BEFORE_COMMIT` | `CamelKafkaLastRecordBeforeCommit`
+| `KafkaConstants.LAST_POLL_RECORD` | `kafka.LAST_POLL_RECORD` |
`CamelKafkaLastPollRecord`
+| `KafkaConstants.TIMESTAMP` | `kafka.TIMESTAMP` | `CamelKafkaTimestamp`
+| `KafkaConstants.OVERRIDE_TIMESTAMP` | `kafka.OVERRIDE_TIMESTAMP` |
`CamelKafkaOverrideTimestamp`
+| `KafkaConstants.KAFKA_RECORD_META` | `kafka.RECORD_META` |
`CamelKafkaRecordMeta`
+|===
+
+`KafkaConstants.MANUAL_COMMIT` was already `Camel`-prefixed
+(`CamelKafkaManualCommit`) and is unchanged.
+
+Routes that reference the constants symbolically (for example
+`setHeader(KafkaConstants.OVERRIDE_TOPIC, ...)`) continue to work without
+changes. Routes that set or read the headers by their literal string values
+(for example `setHeader("kafka.OVERRIDE_TOPIC", ...)` or Simple expressions
such
+as `${headers[kafka.TOPIC]}`) must be updated to use the new values:
+
+[source,java]
+----
+// before
+from("platform-http:/api/events")
+ .setHeader("kafka.OVERRIDE_TOPIC", constant("events.topic"))
+ .to("kafka:default?brokers=localhost:9092");
+
+// after
+from("platform-http:/api/events")
+ .setHeader(KafkaConstants.OVERRIDE_TOPIC, constant("events.topic"))
+ .to("kafka:default?brokers=localhost:9092");
+----
+
+The generated Endpoint DSL header accessors on `KafkaEndpointBuilderFactory`
+keep their method names (`kafkaOverrideTopic()`, `kafkaTopic()`,
+`kafkaPartitionKey()`, ...); only the returned string value reflects the new
+`CamelKafka*` convention.
+
+==== Behaviour change: cross-transport propagation of kafka.* headers
+
+Because the renamed header values now begin with `Camel`, they are filtered by
+the standard transport `HeaderFilterStrategy` (`HttpHeaderFilterStrategy`,
+`JmsHeaderFilterStrategy`, etc.) when crossing a transport boundary, by design
+— `Camel*` headers are framework-internal and are not propagated over the wire.
+
+Routes that bridge an external transport (HTTP, JMS, ...) into a `kafka:`
+producer and let the sender choose the destination topic via the
+`kafka.OVERRIDE_TOPIC` header must therefore carry that value in a
+non-`Camel`-prefixed application header and map it to
+`KafkaConstants.OVERRIDE_TOPIC` in the route between the transport `from` and
+the `kafka:` `to`. Allowing untrusted senders to drive
+`KafkaConstants.OVERRIDE_TOPIC` (which redirects the producer's target topic)
+without such a mapping step is not the intended use of the component.
