Migration Guide

Migrating to Kalix JVM SDKs version 1.5.0

The new Kalix JVM SDKs 1.5.0 brings in a few important updates that requires some changes on your build and eventually source code.

Removed deprecated APIs

Some deprecated APIs have been removed. If you were still using one those APIs, you will need to adapt your code accordingly. Before upgrading to 1.5.0, make sure you follow the instructions provided by the deprecation warnings and change your source code accordingly.

List of removed deprecated APIs:

  • KalixTestKit.getGrpcClientSettings method - deprecated since 0.8.1

  • EntityOptions.withPassivationStrategy method - deprecated since 1.1.4

  • EntityKey annotation - deprecated since 1.3.0

  • EntityType annotation - deprecated since 1.3.0

  • GenerateEntityKey annotation - deprecated since 1.3.0

  • KalixTestKit.getTopic method - deprecated since 1.3.4

Removed deprecated protobuf annotations

Some annotations has been deprecated for a while and are now removed/no longer supported:

  • (kalix.field).entity_key is replaced with (kalix.field).id

  • (kalix.method).entity.key_generator is replaced with (kalix.method).id_generator.algorithm

  • (kalix.codegen).entity_type is replaced with (kalix.codegen).type_id

Build upgrade

Kalix JVM SDK 1.5.0 ships with Akka 2.9.3.

The artifacts for Akka 2.9 series are only available in the Akka library repository and therefore, to upgrade your Kalix project to SDK v1.5.0, depending on the sdk flavor you are using, different changes might be required.

Maven

For Kalix services built with Java (both for code-first and protocol-first versions), we now provide a parent POM that you should use in your project. This parent POM includes the necessary configurations and plugins to build a Kalix project, simplifying the configuration of its pom.xml.

Your POM should only contain a reference to the parent POM along with the project’s specific properties and its dependencies. See example below:

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
                      http://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>

  <!-- Using kalix parent POM -->
  <parent>
    <groupId>io.kalix</groupId>
    <artifactId>kalix-java-sdk-protobuf-parent</artifactId>
    <version>1.5.0</version>
  </parent>

  <groupId>com.example</groupId>
  <artifactId>valueentity-counter</artifactId>
  <version>0.0.1</version>
  <packaging>jar</packaging>

  <name>first-service</name>
  <properties>
    <!-- For Docker setup see https://docs.kalix.io/projects/container-registries.html -->
    <kalixContainerRegistry>kcr.us-east-1.kalix.io</kalixContainerRegistry>
    <kalixOrganization>acme</kalixOrganization>
    <mainClass>com.example.Main</mainClass>
  </properties>

  <dependencies>
    <!-- Dependencies of your project -->
  </dependencies>
</project>
For Java code-first SDK, replace kalix-java-sdk-protobuf-parent by kalix-spring-boot-parent in the parent section.
sbt

The resolver must be added in two places. Once in the project/plugins.sbt and once in the build.sbt. In both cases, the snippet to add is as follows:

resolvers += "Akka library repository".at("https://repo.akka.io/maven")

In addition to adding a new resolver for the Akka artifacts, Scala users should also update the sbt-native-packager plugin. The old sbt-native-packager artifact has a transitive dependency that conflicts with Akka 2.9.

In project/plugins.sbt replace the sbt-native-packager line by:

addSbtPlugin("com.github.sbt" % "sbt-native-packager" % "1.9.16")

Note that you should update the full line as the group id also changed.

Building with JDK 21

As of Kalix SDK 1.5.0, you can use JDK 21 to build your project. Depending on the sdk you are using, you might need to update your build configuration.

Maven

With the use of the parent POM, the default version we target is already Java 21. To use a different version, you can override the java.version property in your project’s POM.

sbt

To use Java 21, the following must be change in your build.sbt file:

  • update scalaVersion to 2.13.13

  • dockerBaseImage must be set to docker.io/library/eclipse-temurin:21.0.2_13-jre-jammy

  • in scalacOptions, replace -target:11 by -release:21