From cfab267b1197500407902a0d99771d900ff44f66 Mon Sep 17 00:00:00 2001 From: PJ Fanning Date: Wed, 2 Sep 2026 17:57:38 +0100 Subject: [PATCH 1/3] 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 --- .../migration/migration-guide-1.x-2.x.md | 145 ++++++++++++++++++ 1 file changed, 145 insertions(+) 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..83c9dd019c 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,148 @@ 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 that maintains a minimum number of non-blocked worker +threads on newer JDKs. Set it explicitly to `1` to restore the Pekko 1.x behavior. +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. +* `pekko.cluster.sharding.passivate-idle-entity-after` was removed; use +`pekko.cluster.sharding.passivation.default-idle-strategy.idle-entity.timeout` instead. +* The `pekko.ssl-config` and top-level `ssl-config` sections were removed along with the +`ssl-config` library dependency. + +### 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. +([PR2755](https://github.com/apache/pekko/pull/2755)) +* `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)) From 4f8c4a35f440679898e688a46ea35ae640392401 Mon Sep 17 00:00:00 2001 From: PJ Fanning Date: Thu, 8 Oct 2026 15:50:56 +0100 Subject: [PATCH 2/3] 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 --- .../main/paradox/additional/rolling-updates.md | 7 +++++-- docs/src/main/paradox/project/rolling-update.md | 17 ++++++++++++++++- 2 files changed, 21 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/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. From 551f4b951ace0ae9286922d571fa1cb582f9fbc4 Mon Sep 17 00:00:00 2001 From: PJ Fanning Date: Thu, 8 Oct 2026 17:35:11 +0100 Subject: [PATCH 3/3] 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 --- .../migration/migration-guide-1.x-2.x.md | 28 ++++++++++++++++--- 1 file changed, 24 insertions(+), 4 deletions(-) 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 83c9dd019c..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 @@ -62,8 +62,9 @@ them before. * `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 that maintains a minimum number of non-blocked worker -threads on newer JDKs. Set it explicitly to `1` to restore the Pekko 1.x behavior. +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 @@ -98,10 +99,12 @@ trust, remove them before upgrading. ([PR3528](https://github.com/apache/pekko/p ### 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. +`ssl-config` library dependency. ([PR2127](https://github.com/apache/pekko/pull/2127)) ### New configuration @@ -139,7 +142,7 @@ serializers decompress it. First appeared in Pekko 1.7.1. * `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. -([PR2755](https://github.com/apache/pekko/pull/2755)) +([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 @@ -193,3 +196,20 @@ stream stage errors. ([PR2805](https://github.com/apache/pekko/pull/2805)) 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))