Strategy for gradual Akka → Pekko migration with shared library and rollback capability?

[travissarles]

We're planning a gradual migration from Akka to Pekko and would appreciate guidance on the best approach.

Our setup:

• Multiple Scala 2.13 applications running as Docker images with Java 17 on Kubernetes
• A shared internal library that currently depends on Akka and Akka Streams
• All apps consume this common library

Our goals:

• Migrate to Pekko one application at a time in production
• Maintain easy rollback capability (ideally by building both an Akka and a Pekko version of each app)
• Avoid transitive dependency conflicts between Akka and Pekko artifacts

What we've considered:

• Using macros to switch imports between akka.* and org.apache.pekko.*
• However, we suspect there might be a simpler or cleaner approach

Our concerns:

• Managing transitive dependencies when both Akka and Pekko artifacts could end up on the classpath
• Security implications of whatever switching mechanism we adopt

Has anyone implemented a similar incremental migration strategy? What patterns or tooling would you recommend for maintaining parallel Akka/Pekko builds during a transition period? Thanks in advance!

[He-Pin]

If you don't depend on clustering, the migration is very easy with a package change then.

[mdedetrich]

If you use sbt as a build tool, you could use an sbt plugin like https://github.com/fkz/scala-rewrite-imports which will rewrite imports into another import.

It also shouldn't be too hard to do the same with the various .conf files.

[travissarles]

Since the akka and pekko libs use different package names, you can have both on the classpath at the same time. You will probably need to copy paste all the classes that you have that import akka classes and create new classes that use pekko instead.

You should read the Pekko release notes and migration guides. https://pekko.apache.org/docs/pekko/current/migration/migration-guide-akka-1.0.x.html is a starting point.

I'm more concerned about conflicting transitive dependencies.

[travissarles]

If you use sbt as a build tool, you could use an sbt plugin like https://github.com/fkz/scala-rewrite-imports which will rewrite imports into another import.

It also shouldn't be too hard to do the same with the various .conf files.

I wasn't aware of this plugin, thanks!

[mdedetrich]

I'm more concerned about conflicting transitive dependencies.

The Pekko 1.0.x series is strictly a fork of Akka 2.6 without any changes to dependencies, only package names/conf paths and any related changes are done. This was a deliberate decision to make migration smoother.

If you are talking about transitive dependencies further down the chain (i.e. you have library that depends on Akka 2.6 but it isn't compiled against Pekko 1.0.x that isn't a satellite Pekko project) then you have to have to either fork it and make a version built against Pekko 1.0.x or if its an internal library then cross build it, scala-rewrite-imports should help here as well along with the use of sbt subprojects.

[travissarles]

I'm more concerned about conflicting transitive dependencies.

The Pekko 1.0.x series is strictly a fork of Akka 2.6 without any changes to dependencies, only package names/conf paths and any related changes are done. This was a deliberate decision to make migration smoother.

If you are talking about transitive dependencies further down the chain (i.e. you have library that depends on Akka 2.6 but it isn't compiled against Pekko 1.0.x that isn't a satellite Pekko project) then you have to have to either fork it and make a version built against Pekko 1.0.x or if its an internal library then cross build it, scala-rewrite-imports should help here as well along with the use of sbt subprojects.

We're on Akka 2.10. We'll see which of these is the most straightforward.

[regiskuckaertz]

hi @travissarles I just went through this myself with ~20 services in a monorepo with loads of shared sbt projects between them as well as roughly the same number of internal libraries hosted in another repo. the method i used was what my sensei would call "brutal duplication for total domination" 😤😁🐲

otherwise known as the bottom up approach. in a nutshell:

• start with the internal libraries. we knew that both would not be on the same classpath, so we just duplicated each library that had akka dependencies, updated the import statements, updated any akka-specific config, and published the artifacts under a different name. therefore both versions had the same package structure.
• for the shared sbt projects, also duplicated, replaced the akka dependencies as well as internal lib dependencies, updated the import statements and akka-specific config

all the leaves and shared branches of the dependency graph being duplicated, we were in a position to migrate each application one at a time—no application had both akka and pekko dependencies. yes, it meant for a period of time we were careful in PR reviews to make sure changes were replicated in duplicate projects, but the migration took less than a week. since we tag our docker images with the commit sha, rollback would have been easy but never happened.

we experienced two minor difficulties:

• running hybrid akka/pekko clusters: did not work initially but the team here was super helpful with the investigation, even fixed some code in the cluster formation protocol (this hybrid feature is unique to pekko). in the process i even went into what my sensei would call "complete yolo mode of the end of the universe" and moved from classic remote, which we were still using, to artery.
• for better or worse, we use swagger annotations in our http apis. we had to update all of them to the v3 annotations. luckily, this an agent can easily do today with minimum oversight.

it's been four months since, no issues reported

[travissarles]

hi @travissarles I just went through this myself with ~20 services in a monorepo with loads of shared sbt projects between them as well as roughly the same number of internal libraries hosted in another repo. the method i used was what my sensei would call "brutal duplication for total domination" 😤😁🐲

otherwise known as the bottom up approach. in a nutshell:

• start with the internal libraries. we knew that both would not be on the same classpath, so we just duplicated each library that had akka dependencies, updated the import statements, updated any akka-specific config, and published the artifacts under a different name. therefore both versions had the same package structure.

• for the shared sbt projects, also duplicated, replaced the akka dependencies as well as internal lib dependencies, updated the import statements and akka-specific config

all the leaves and shared branches of the dependency graph being duplicated, we were in a position to migrate each application one at a time—no application had both akka and pekko dependencies. yes, it meant for a period of time we were careful in PR reviews to make sure changes were replicated in duplicate projects, but the migration took less than a week. since we tag our docker images with the commit sha, rollback would have been easy but never happened.

we experienced two minor difficulties:

• running hybrid akka/pekko clusters: did not work initially but the team here was super helpful with the investigation, even fixed some code in the cluster formation protocol (this hybrid feature is unique to pekko). in the process i even went into what my sensei would call "complete yolo mode of the end of the universe" and moved from classic remote, which we were still using, to artery.

• for better or worse, we use swagger annotations in our http apis. we had to update all of them to the v3 annotations. luckily, this an agent can easily do today with minimum oversight.

it's been four months since, no issues reported

Also an interesting approach. I think with our setup it would be difficult to manually keep changes in sync over a few months. If we did it in a week, like you did, that could work.

[He-Pin]

We have migrated to Pekko for some important scenarios. We mainly use Pekko streams and actors, such as live streaming, translation, proxying, and MCP server, and have not encountered any problems.

We are using pekko with Java and Java 21.

[travissarles]

That's encouraging to hear! We're also using Akka streams.