This is an automated email from the ASF dual-hosted git repository.
He-Pin pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/pekko.git
The following commit(s) were added to refs/heads/main by this push:
new c07a5476af docs: list configuration changes in the 1.x to 2.x
migration guide (#3513)
c07a5476af is described below
commit c07a5476af9ea0fb1fb3db6254c63232ab2b94a4
Author: PJ Fanning <[email protected]>
AuthorDate: Fri Oct 9 05:53:48 2026 +0100
docs: list configuration changes in the 1.x to 2.x migration guide (#3513)
* docs: list configuration changes in the 1.x to 2.x migration guide
Motivation:
The 1.x to 2.x migration guide did not mention the reference.conf
changes between the 1.7.x and main branches, so users had no single
place to review new settings and changed defaults.
Modification:
Add a Configuration Changes section to migration-guide-1.x-2.x.md
covering changed default values, changed behavior, removed settings
and new settings, grouped by module, with links to the originating PRs
and to the default configuration reference. Settings also backported
to 1.x note the Pekko version they first appeared in.
Result:
Users migrating from Pekko 1.x to 2.x can review the configuration
changes in one place.
Tests:
- Not run - docs only
References:
None - sourced from diffing reference.conf files between 1.7.x and main,
and between the v1.5.0, v1.6.0, v1.7.0 and v1.7.1 tags to find settings
backported to 1.x
* docs: describe rolling updates from Pekko 1.x to 2.x
Motivation:
The Rolling Updates and Versions page only covers patch-to-patch
updates and says nothing about upgrading a cluster from Pekko 1.x to
2.x. The TCP magic header section also says that a direct rolling
upgrade from Pekko 1.6.x or earlier to 2.x works with the defaults,
but 2.x sends "PEKK" on outbound connections
(ArteryTcpTransport/TcpFraming) and 1.6.x and earlier only accept
"AKKA", so connections from 2.x nodes to those nodes are rejected.
Modification:
- project/rolling-update.md: add an "Upgrading from Pekko 1.x to 2.x"
section that points to the migration guide and says to upgrade to
the latest 1.7.x first, then to 2.x
- additional/rolling-updates.md: correct the TCP magic header section;
a direct upgrade from 1.6.x or earlier needs
tcp-magic = ["AKKA", "PEKK"] on the 2.x nodes until all nodes run 2.x
Result:
Users planning a 1.x to 2.x rolling update know the path to follow.
Tests:
- Not run - docs only
References:
None - found during a review of the docs
* docs: correct and extend the 1.x to 2.x migration guide config changes
Motivation:
Review of the configuration changes section found a wrong PR link, an
imprecise description of the new minimum-runnable default, removed
settings without PR links, and no mention of serialization binding
changes that matter for rolling updates.
Modification:
- minimum-runnable: -1 only changes the effective value on JDK 25 and
later; on earlier JDKs it is 1
- sharded-daemon-process keep-alive settings come from #2734, not #2755
- add PR links for the removed settings (#1969, #3026, #2127)
- add a Serialization bindings section: ByteString2 is wire compatible
(no manifest), typed-sharding serializer now also handles new
Sharded Daemon Process messages that 1.x cannot read, and the new
FilteredPayload serializer (id 34) cannot be read by 1.x
Result:
The configuration changes section is accurate and covers the
serialization changes that affect rolling updates and rollbacks.
Tests:
- Not run - docs only
References:
None - checked against reference.conf, ShardingSerializer,
ByteStringSerializer and FilteredPayload on main and 1.7.x
---
.../src/main/paradox/additional/rolling-updates.md | 7 +-
.../paradox/migration/migration-guide-1.x-2.x.md | 165 +++++++++++++++++++++
docs/src/main/paradox/project/rolling-update.md | 17 ++-
3 files changed, 186 insertions(+), 3 deletions(-)
diff --git a/docs/src/main/paradox/additional/rolling-updates.md
b/docs/src/main/paradox/additional/rolling-updates.md
index 2cf4a643f6..77df7ebd68 100644
--- a/docs/src/main/paradox/additional/rolling-updates.md
+++ b/docs/src/main/paradox/additional/rolling-updates.md
@@ -159,8 +159,11 @@ The magic header has evolved across versions:
* Pekko 2.x (and above) sends `"PEKK"` by default but accepts both `"PEKK"`
and `"AKKA"`.
Because Pekko 1.7.x+ and 2.x accept both values by default, rolling upgrades
between these versions
-do not require changing the `tcp-magic` configuration. Upgrading from Pekko
1.6.x or earlier to 2.x
-directly is also supported since the 2.x default accepts `"AKKA"`.
+do not require changing the `tcp-magic` configuration.
+
+Pekko 1.6.x and earlier reject the `"PEKK"` header that Pekko 2.x sends by
default. Upgrade to Pekko 1.7.x
+first, or, if you upgrade from Pekko 1.6.x or earlier directly to 2.x, set
+`pekko.remote.artery.advanced.tcp-magic = ["AKKA", "PEKK"]` on the 2.x nodes
until all nodes run 2.x.
If you remove `"AKKA"` from the array, nodes running older versions will be
unable to connect.
diff --git a/docs/src/main/paradox/migration/migration-guide-1.x-2.x.md
b/docs/src/main/paradox/migration/migration-guide-1.x-2.x.md
index 30e70bc0e0..acdda63334 100644
--- a/docs/src/main/paradox/migration/migration-guide-1.x-2.x.md
+++ b/docs/src/main/paradox/migration/migration-guide-1.x-2.x.md
@@ -48,3 +48,168 @@ Java users should match on `ReceiveTimeout.class` instead.
(`pekko.remote.artery.advanced.tcp-magic`). See
@ref:[Changing TCP magic
header](../additional/rolling-updates.md#changing-tcp-magic-header) for what
this means for
rolling updates. ([PR3425](https://github.com/apache/pekko/pull/3425))
+
+## Configuration Changes in Pekko 2.x
+
+The `reference.conf` defaults have changed in a number of places. If you
override any of the settings
+below in your `application.conf`, or rely on their Pekko 1.x defaults, review
this list.
+
+Some of these settings were also backported to Pekko 1.x releases. Those
entries note the Pekko version
+in which the setting first appeared, so if you are already on that version or
later you may have seen
+them before.
+
+### Changed default values
+
+* `pekko.actor.default-dispatcher.fork-join-executor.minimum-runnable` changed
from `1` to `-1`.
+The setting first appeared in Pekko 1.7.0, with a default of `1`.
+The value `-1` selects a JDK-aware default: on JDK 25 and later the effective
value is
+`min(8, max(1, parallelism / 2))`, and on earlier JDKs it is `1`, so the
behavior only changes on
+JDK 25 and later. Set it explicitly to `1` to restore the Pekko 1.x behavior
on all JDKs.
+The internal dispatcher (`pekko.actor.internal-dispatcher.fork-join-executor`)
uses the same new default.
+([PR2890](https://github.com/apache/pekko/pull/2890))
+* `pekko.remote.artery.propagate-harmless-quarantine-events` changed from `on`
to `off`, so harmless
+quarantine events are no longer propagated by default.
([PR2430](https://github.com/apache/pekko/pull/2430))
+* `pekko.remote.artery.advanced.tcp-magic` changed from `["AKKA", "PEKK"]` to
`["PEKK", "AKKA"]`
+(see the TCP magic header note above). The setting first appeared in Pekko
1.7.0, with a default of
+`["AKKA", "PEKK"]`. ([PR3425](https://github.com/apache/pekko/pull/3425))
+* Artery compression heavy hitter detection is controlled by the new setting
+`pekko.remote.artery.advanced.compression.frequency-sketch-implementation`,
which defaults to
+`"fast-frequency-sketch"` (a smaller, aging sketch). Set it to
`"count-min-sketch"` to restore the
+Pekko 1.x implementation. ([PR3023](https://github.com/apache/pekko/pull/3023))
+* Persistence plugins no longer use the dedicated
`pekko.persistence.dispatchers` by default. The
+`plugin-dispatcher` and `replay-dispatcher` settings in the journal and
snapshot-store plugin
+fallbacks changed from
`pekko.persistence.dispatchers.default-plugin-dispatcher` /
+`pekko.persistence.dispatchers.default-replay-dispatcher` to
`pekko.actor.default-dispatcher`.
+The `pekko.persistence.dispatchers` definitions are deprecated; plugins that
need a custom
+dispatcher should define their own.
([PR2482](https://github.com/apache/pekko/pull/2482))
+* `pekko.serialization.jackson.read.max-document-length` and
+`pekko.serialization.jackson.read.max-token-count` changed from `-1` to
`unlimited`, a value they now
+accept. Negative numbers such as `-1` still mean unlimited, so the effective
limits are unchanged and
+existing overrides keep working. The same applies under
`pekko.serialization.jackson3`.
+([PR3522](https://github.com/apache/pekko/pull/3522))
+
+### Changed behavior
+
+* `pekko.remote.artery.ssl.rotating-keys-engine.ca-cert-file` may now bundle
more than one
+certificate (for example a root CA and its intermediates, or several roots
while a CA is being
+rotated); all of them are trusted. Pekko 1.x only loaded the first certificate
in the file. The
+setting and its default are unchanged. If your CA file contains certificates
you do not intend to
+trust, remove them before upgrading.
([PR3528](https://github.com/apache/pekko/pull/3528))
+
+### Removed configuration
+
+* `pekko.actor.typed.timeout` was removed along with the deprecated
`TypedActor` API.
+([PR1969](https://github.com/apache/pekko/pull/1969))
+* `pekko.cluster.sharding.passivate-idle-entity-after` was removed; use
+`pekko.cluster.sharding.passivation.default-idle-strategy.idle-entity.timeout`
instead.
+([PR3026](https://github.com/apache/pekko/pull/3026))
+* The `pekko.ssl-config` and top-level `ssl-config` sections were removed
along with the
+`ssl-config` library dependency.
([PR2127](https://github.com/apache/pekko/pull/2127))
+
+### New configuration
+
+The full `reference.conf` for each module, with descriptions of every setting,
is listed in the
+@ref:[default configuration reference](../general/configuration-reference.md).
+
+@ref:[pekko-actor](../general/configuration-reference.md#config-pekko-actor):
+
+*
`pekko.actor.default-dispatcher.fork-join-executor.virtual-thread-start-number`,
+`pekko.actor.default-dispatcher.thread-pool-executor.virtual-thread-start-number`
and
+`pekko.actor.default-dispatcher.virtual-thread-executor.virtual-thread-start-number`
control the
+starting id for virtual threads created by a dispatcher.
([PR2242](https://github.com/apache/pekko/pull/2242))
+* `pekko.actor.default-dispatcher.thread-pool-executor.virtualize` allows a
thread-pool-executor
+based dispatcher to run on virtual threads (JDK 21+). The same settings were
added to
+`pekko.actor.default-blocking-io-dispatcher.thread-pool-executor`.
+([PR2169](https://github.com/apache/pekko/pull/2169))
+* `pekko.scheduled-clock-interval` controls how frequently the clock used by
recency-based
+passivation strategies is updated.
([PR2766](https://github.com/apache/pekko/pull/2766))
+* The async DNS resolver actors now run on the DNS dispatcher via the new
deployment entries
+`pekko.actor.deployment."/IO-DNS/async-dns/*"` and (in
+@ref:[pekko-discovery](../general/configuration-reference.md#config-pekko-discovery))
+`pekko.actor.deployment."/SD-DNS/async-dns/*"`.
([PR2895](https://github.com/apache/pekko/pull/2895))
+* `pekko.actor.serialization-max-nesting-depth` (default `32`) bounds the
nesting depth when a
+serialized payload encloses another serialized payload. First appeared in
Pekko 1.7.1.
+([PR3500](https://github.com/apache/pekko/pull/3500))
+* `pekko.serialization.max-decompressed-size` (default `unlimited`) bounds the
size a gzipped payload
+may expand to when the cluster, cluster-metrics, cluster-sharding,
cluster-tools and distributed-data
+serializers decompress it. First appeared in Pekko 1.7.1.
+([PR3502](https://github.com/apache/pekko/pull/3502))
+
+@ref:[pekko-cluster-sharding-typed](../general/configuration-reference.md#config-cluster-sharding-typed),
+@ref:[pekko-cluster-sharding](../general/configuration-reference.md#config-cluster-sharding)
and
+@ref:[pekko-distributed-data](../general/configuration-reference.md#config-distributed-data):
+
+* `pekko.cluster.sharded-daemon-process.keep-alive-from-number-of-nodes` and
+`pekko.cluster.sharded-daemon-process.keep-alive-throttle-interval` tune
keep-alive pinging, which
+is now performed from a limited number of nodes instead of every node.
+([PR2734](https://github.com/apache/pekko/pull/2734))
+* `pekko.cluster.sharding.healthcheck.disabled-after` disables the sharding
health check after the
+configured duration post member-up.
([PR2785](https://github.com/apache/pekko/pull/2785))
+* `pekko.cluster.distributed-data.expire-keys-after-inactivity` configures
automatic expiry of
+inactive Distributed Data keys.
([PR2733](https://github.com/apache/pekko/pull/2733))
+
+@ref:[pekko-persistence](../general/configuration-reference.md#config-pekko-persistence),
+@ref:[pekko-persistence-typed](../general/configuration-reference.md#config-pekko-persistence-typed)
and
+@ref:[pekko-persistence-query](../general/configuration-reference.md#config-pekko-persistence-query):
+
+* `pekko.persistence.query.events-by-slice-firehose` is a new section
configuring the
+events-by-slice firehose query that fans out one shared journal query to many
consumers.
+([PR3277](https://github.com/apache/pekko/pull/3277))
+* `pekko.persistence.typed.event-writer.max-batch-size` and
+`pekko.persistence.typed.event-writer.ask-timeout` configure the event writer.
+([PR3432](https://github.com/apache/pekko/pull/3432))
+* `replay-batch-size` in the journal plugin fallback bounds the number of
replayed events queued in
+a recovering persistent actor's mailbox.
([PR3325](https://github.com/apache/pekko/pull/3325))
+* `only-one-snapshot` in the snapshot-store plugin fallback enables retention
optimizations for
+snapshot stores that only keep the latest snapshot.
([PR2767](https://github.com/apache/pekko/pull/2767))
+* `pekko.persistence.journal.inmem.delay-writes` can add an artificial write
delay in tests.
+([PR3432](https://github.com/apache/pekko/pull/3432))
+
+@ref:[pekko-remote
classic](../general/configuration-reference.md#config-pekko-remote) and
+@ref:[pekko-remote
Artery](../general/configuration-reference.md#config-pekko-remote-artery):
+
+* `pekko.remote.classic.passive-connection-buffer-size` bounds message
buffering during a passive
+connection handoff. ([PR3361](https://github.com/apache/pekko/pull/3361))
+* `pekko.remote.classic.netty.ssl.security.hostname-verification` enables TLS
hostname verification
+for classic remoting. ([PR3164](https://github.com/apache/pekko/pull/3164))
+* `pekko.remote.artery.advanced.shutdown-streams-timeout` bounds the graceful
drain of Artery
+streams during shutdown. ([PR3317](https://github.com/apache/pekko/pull/3317))
+* `pekko.remote.artery.ssl.rotating-keys-engine.keystore-password` sets the
password for the
+in-memory keystore used to wrap PEM-loaded keys; override it in production.
+([PR3397](https://github.com/apache/pekko/pull/3397))
+
+@ref:[pekko-serialization-jackson](../serialization-jackson.md):
+
+* `pekko.serialization.jackson.compression.max-decompressed-size` (default
`unlimited`) bounds the size
+of a payload after decompression. The same setting exists under
`pekko.serialization.jackson3`.
+First appeared in Pekko 1.7.1.
([PR3491](https://github.com/apache/pekko/pull/3491),
+[PR3515](https://github.com/apache/pekko/pull/3515))
+* The new `pekko-serialization-jackson3` module (based on Jackson 3) is
configured under
+`pekko.serialization.jackson3`, mirroring the `pekko.serialization.jackson`
settings.
+([PR2348](https://github.com/apache/pekko/pull/2348))
+
+@ref:[pekko-stream](../general/configuration-reference.md#config-pekko-stream):
+
+* `pekko.stream.materializer.stage-errors-default-log-level` controls the log
level used for
+stream stage errors. ([PR2805](https://github.com/apache/pekko/pull/2805))
+* `pekko.stream.materializer.stage-actor-drain-batch` bounds the number of
stage-actor messages
+drained per envelope for lazily materialized stage actors.
([PR3035](https://github.com/apache/pekko/pull/3035))
+* `pekko.stream.materializer.tls.engine` selects the stream TLS engine
implementation
+(`"legacy-actor"` or the opt-in `"graph-stage"`).
([PR2878](https://github.com/apache/pekko/pull/2878))
+
+### Serialization bindings
+
+These serialization changes matter if you do a rolling update from Pekko 1.x
to 2.x, or need to roll
+back:
+
+* `org.apache.pekko.util.ByteString$ByteString2`, a new `ByteString`
implementation, is bound to the
+existing `primitive-bytestring` serializer. That serializer writes no
manifest, so Pekko 1.x nodes read
+these messages as an ordinary `ByteString`.
([PR2924](https://github.com/apache/pekko/pull/2924))
+* The `typed-sharding` serializer is now bound to the internal
`ClusterShardingTypedSerializable` marker
+instead of `ShardingEnvelope`. `ShardingEnvelope` is serialized as before, but
the serializer also
+handles new Sharded Daemon Process messages (its state, and the commands for
getting and changing the
+number of processes) that Pekko 1.x nodes cannot deserialize.
([PR2755](https://github.com/apache/pekko/pull/2755))
+* The new `FilteredPayload` placeholder, which is stored in the journal in
place of a filtered event
+(for example with events-by-slice queries and projections), has a new
serializer with identifier `34`.
+Pekko 1.x cannot deserialize it, so do not run Pekko 1.x against a journal
once such events have been
+written. ([PR3275](https://github.com/apache/pekko/pull/3275))
diff --git a/docs/src/main/paradox/project/rolling-update.md
b/docs/src/main/paradox/project/rolling-update.md
index 36793dd81d..a68c7e5284 100644
--- a/docs/src/main/paradox/project/rolling-update.md
+++ b/docs/src/main/paradox/project/rolling-update.md
@@ -13,4 +13,19 @@ update completely before starting next update.
@ref:[Rolling update from classic remoting to
Artery](../additional/rolling-updates.md#migrating-from-classic-remoting-to-artery)
is not supported since the protocol
is completely different. It will require a full cluster shutdown and new
startup.
-@@@
\ No newline at end of file
+@@@
+
+## Upgrading from Pekko 1.x to 2.x
+
+Pekko 2.x is not binary compatible with Pekko 1.x, so all the Pekko modules
(and any libraries built on
+Pekko 1.x) must be upgraded together. Read the
+@ref:[migration guide](../migration/migration-guide-1.x-2.x.md) before
planning a rolling update, in
+particular the breaking changes and the configuration changes, and check how
they affect the messages
+exchanged between nodes, your persisted data and your configuration.
+
+For a rolling update of a cluster from Pekko 1.x to 2.x:
+
+* First upgrade the whole cluster to the latest Pekko 1.7.x release. Pekko 2.x
sends a different Artery
+ TCP magic header by default, which Pekko 1.6.x and earlier reject, see
+ @ref:[Changing TCP magic
header](../additional/rolling-updates.md#changing-tcp-magic-header).
+* Then roll out Pekko 2.x as a separate update.
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
