Repository navigation
docs: list configuration changes in the 1.x to 2.x migration guide - #3513
Merged
Merged
Conversation
pjfanning
added a commit
that referenced
this pull request
Sep 7, 2026
Motivation: Review on #3515 preferred an explicit keyword over -1 as a magic number for unlimited. Among the configuration listed in #3513, the Jackson read constraints max-document-length and max-token-count document -1 as meaning unlimited but only accept numbers. Modification: JacksonObjectMapperProvider in serialization-jackson and serialization-jackson3 reads "unlimited" as -1 for read.max-document-length and read.max-token-count, and the reference.conf defaults are written as `unlimited`. A negative number such as -1 is still accepted. Result: `max-document-length = unlimited` and `max-token-count = unlimited` work; the effective defaults are unchanged. Tests: - sbt "serialization-jackson/testOnly org.apache.pekko.serialization.jackson.*" - 129 passed - sbt "serialization-jackson3/testOnly org.apache.pekko.serialization.jackson3.*" - 127 passed - sbt "serialization-jackson/scalafmtCheckAll" "serialization-jackson3/scalafmtCheckAll" - clean References: Refs #3513, Refs #3515
pjfanning
force-pushed
the
migration-guide-2x-config-changes
branch
3 times, most recently
from
October 8, 2026 12:53
d33d805 to
52b992a
Compare
pjfanning
force-pushed
the
migration-guide-2x-config-changes
branch
from
October 8, 2026 13:05
52b992a to
7788747
Compare
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
pjfanning
force-pushed
the
migration-guide-2x-config-changes
branch
from
October 8, 2026 13:05
7788747 to
cfab267
Compare
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
pjfanning
marked this pull request as ready for review
October 8, 2026 14:52
This was referenced Oct 8, 2026
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 apache#2734, not apache#2755 - add PR links for the removed settings (apache#1969, apache#3026, apache#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
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Motivation
The 1.x to 2.x migration guide did not mention the
reference.confchanges between the 1.7.x and main branches, so users had no single place to review new settings and changed defaults when upgrading. The rolling update docs also said nothing about upgrading a cluster from 1.x to 2.x.Modification
Add a "Configuration Changes in Pekko 2.x" section to
migration-guide-1.x-2.x.md, based on diffing allsrc/main/resources/reference.conffiles between the1.7.xandmainbranches. It covers:minimum-runnable,propagate-harmless-quarantine-events,tcp-magic, the Artery frequency sketch, persistence plugin dispatchers, the Jacksonmax-document-length/max-token-countdefaults)ca-cert-filenow trusts every certificate in the file)@reflinks to the default configuration reference and links to the PRs that introduced each settingSettings that were also backported to Pekko 1.x releases since 1.6.0 (
minimum-runnable,tcp-magic,serialization-max-nesting-depth,pekko.serialization.max-decompressed-sizeand the Jacksoncompression.max-decompressed-size) are kept in the list and note the Pekko version they first appeared in.The section also has a "Serialization bindings" part covering the binding changes that matter for rolling updates and rollbacks:
ByteString2(wire compatible), thetyped-shardingserializer's new Sharded Daemon Process messages (not readable by 1.x) and the newFilteredPayloadserializer, id 34 (not readable by 1.x). Theminimum-runnableentry explains that-1only changes behavior on JDK 25 and later.Also describe rolling updates from 1.x to 2.x:
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 the cluster to the latest 1.7.x first, then to 2.xadditional/rolling-updates.md: correct the TCP magic header section. It said 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 their connections from 2.x nodes are rejected. A direct upgrade needstcp-magic = ["AKKA", "PEKK"]on the 2.x nodes until all nodes run 2.x.Result
Users migrating from Pekko 1.x to 2.x can review the configuration changes in one place, and know how to do a rolling update from 1.x to 2.x.
Tests
References
None - sourced from diffing the
reference.conffiles between the1.7.xandmainbranches, and between thev1.5.0,v1.6.0,v1.7.0andv1.7.1tags to find settings backported to 1.x