§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.

§Build changes

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 sbt.version in project/build.properties.

§Main changes

§Remoting Artery

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:

1. Set property akka.remote.artery.enabled to false. Further, any configuration under akka.remote that 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: akka-remote/reference.conf
2. Add Netty dependency as explained in Akka Remoting docs:

libraryDependencies += "io.netty" % "netty" % "3.10.6.Final"

§Shard Coordination

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.

Switching from persistence to 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:

• Akka Persistence Cassandra Migrations to 0.101
• Akka Persistence Cassandra Migrations to 0.80

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 Behavior’s.

§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.

§Split Brain Resolver

If you are subscriber of the Lightbend Platform and use the Akka Split Brain Resolver, when you update to Lagom 1.6.4 you can opt out of the commercial implementation and use the Open Source Akka Split Brain Resolver. The migration has two steps:

1. remove the dependency:

// before
"com.lightbend.akka" %% "akka-split-brain-resolver" % "1.1.14"
// after
// The OSS SBR implementation is part of "akka-cluster" so you don't need to add a new dependency

1. update your settings to use the new implementation:

## Before:
akka.cluster.downing-provider-class = "com.lightbend.akka.sbr.SplitBrainResolverProvider"
## After:
akka.cluster.downing-provider-class = "akka.cluster.sbr.SplitBrainResolverProvider"

Note that a rolling upgrade where some nodes use the commercial SBR and other nodes use the OSS SBR is possible as long as all nodes use the same configuration values (active-strategy, stable-after,…)

§Cluster shutdown migrating from Lagom 1.5

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 PATCH 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.0 to 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.

§Minor changes

§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)