§Lagom 1.6 Migration Guide
This guide explains how to migrate from Lagom 1.5 to Lagom 1.6. If you are upgrading from an earlier version, be sure to review previous migration guides.
Lagom 1.6 updates to the latest major versions of Play (2.8), Akka (2.6) and Akka HTTP (10.1). We have highlighted the changes that are relevant to most Lagom users, but you may need to change code in your services that uses Play APIs directly. You’ll also need to update any Play services in your Lagom project repositories to be compatible with Play 2.8. Please refer to the Play 2.8 migration guide, Akka Migration Guide 2.5.x to 2.6.x and the Akka HTTP 10.1.x release announcements for more details.
For a detailed list of version upgrades of other libraries Lagom builds on such as for Slick, Kafka and others, refer to the release notes.
§Migrating from Lagom 1.5
To migrate from Lagom 1.5 we recommend first migrating to latest version of Lagom 1.5 before upgrading to Lagom 1.6. Refer to the release notes for details upgrading to latest version of Lagom 1.5.
The version of Lagom can be updated by editing the
project/plugins.sbt file, and updating the version of the Lagom sbt plugin. For example:
addSbtPlugin("com.lightbend.lagom" % "lagom-sbt-plugin" % "1.6.0")
Lagom 1.6 requires sbt 1.3.2 or later, upgrade your version by updating the
Lagom 1.6.0 builds on Akka 2.6.0 that uses a new Akka Remote implementation called Artery. Artery is enabled by default in Lagom and replaces the previous Akka Remote protocol (aka. Akka Remote Classic). If you are using Lagom in a clustered setup, you will need to shutdown all nodes before updating, unless you choose to disable Artery.
To use classic remoting instead of Artery, you need to:
- Set property
false. Further, any configuration under
akka.remotethat is specific to classic remoting needs to be moved to
akka.remote.classic. To see which configuration options are specific to classic search for them in:
- Add Netty dependency as explained in Akka Remoting docs:
libraryDependencies += "io.netty" % "netty" % "3.10.6.Final"
In Lagom 1.4 and 1.5 users could use the
akka.cluster.sharding.store-state-mode configuration key to switch from the default
persistence-based shard coordination to the
ddata-based coordination. As of Lagom 1.6
ddata is the new default.
ddata, such as if your cluster relies of Lagom’s default configuration, will require a full cluster shutdown. Therefore, if you want to avoid the full service shutdown when migrating to Lagom 1.6 you need to explicitly opt-back to
persistence, as such:
# Opt-back to Lagom 1.5's 'persistence' instead of Lagom 1.6's default of 'ddata'. akka.cluster.sharding.state-store-mode = persistence
§Akka Persistence Cassandra Update
The Akka Persistence Cassandra plugin is updated to version 0.101. This version requires two schema migrations before you upgrade to Lagom 1.6.0. For more information on how to migrate, consult the following documentations:
Note that although it’s technically possible to run the migrations while running your application we advise against it.
§Akka Persistence Typed
With the new support for Akka Persistence Typed you may migrate your Persistent Entities to Akka Persistence Typed
§Upgrading a production system
As usual, before upgrading to Lagom 1.6.0, make sure you are using the latest version on the 1.5.x series.
During a rolling upgrade your Projections may experience a degraded behavior. The service will self-heal when the rolling upgrade completes. Some internal messages taking care of the distribution of the worker instances of your projection have changed. As a consequence, your old nodes won’t be able to gossip with the new ones but as soon as the rolling upgrade completes, all nodes will be on the same version of your service the projection will operate normally.
Lagom 1.6.0 has a few new default settings that will prevent you to run a rolling upgrade. In case you prefer to run a rolling upgrade, you will need to opt-out from each of these new defaults as explained below.
This is a summary of changes in Lagom 1.6 that would require a full cluster shutdown rather than a rolling upgrade:
- The change in Akka Remote default implementation.
- The change in default Shard Coordination strategy.
- The change in Cassandra plugin version. Only impacts Lagom applications using Cassandra.
Finally, if you migrate your Persistent Entities as Akka Persistence Typed
Behavior’s you will also need a cluster shutdown for the upgrade.
§A note on Rolling Updates and Versions
Sometimes patch versions of Akka Cluster introduce changes that make certain pairs of versions incompatible. As a consequence, sometimes it is necessary to upgrade in multiple steps if downtime is not possible. See, for example, the following note in the Akka Docs on Rolling Updates and Versions:
This means that a rolling update will have to go through at least one of 2.6.2, 2.6.3 or 2.6.4 when upgrading to 2.6.5 or higher or else cluster nodes will not be able to communicate during the rolling update.
What this means for Lagom is that directly upgrading from
1.6.3, for example, is not possible in a rolling upgrade. Instead, you should first migrate to
1.6.2 deploy the upgraded version and then upgrade to
1.6.3. Following is a table of safe migrations (versions that can coexist safely during a rolling upgrade):
Note: Lagom doesn’t use
jackson-cbor serializer internally, but if you have
jackson-cbor in your
serialization-bindings you need to know about JacksonCborSerializer issue in Akka, and a rolling upgrade will have to go through
1.6.3 when upgrading to
1.6.3 or higher.
§JSON Compression threshold
When creating a serializer with
JsonSerializer.compressed[T] compression will only kick in when the serialized representation is biger than a threshold. The default value for
lagom.serialization.json.compress-larger-than has been increased from 1024 bytes to 32 Kilobytes. (See #1983)