Migrating a Spring Boot service to Halyx

Moving a service from a cloud's SDK, Spring Cloud AWS, Spring Cloud Azure or Spring Cloud GCP onto Halyx is mostly mechanical: each template, client, listener and property has a Halyx equivalent. The parts that need care are somewhere else:

• data the old code already wrote
• formats other services read
• the weeks a rollout runs old and new versions side by side
• tests that pass for the wrong reason

This page covers the method, the mappings, and those pitfalls, all found in trial migrations.

The migration skill#

The halyx-ai-migrate skill runs this method with an AI coding assistant, and halyx-ai-review checks the result for what still ties it to one cloud. See AI skills for installing and running them. Without an assistant, this page is the same method by hand.

How a migration runs#

1. Inventory, read only. Every cloud SDK use, Spring Cloud template, listener, property and config import, each with its Halyx equivalent and a risk:

   • none: a direct mapping
   • behaviour: works, but differently
   • data: existing data must stay readable
   • no equivalent: stays on the native client

   It also covers what others depend on: cache entries and counters read elsewhere, Kafka record formats, and events whose rules and consumers sit outside the service.

2. Plan, then stop for approval. The plan sets out:

   • the inventory
   • what stays out of scope
   • whether Halyx reads the existing data as it is stored
   • how old and new instances work together during the rollout
   • the order of the steps
   • the target halyx.* properties, with every key checked against the service's own bean names

3. One area per change, each built and tested before the next:

   1. dependencies
   2. configuration and secrets
   3. object storage
   4. documents
   5. messaging
   6. events
   7. streams
   8. caches
   9. SQL

   The existing tests keep passing, and memory-provider tests are added.

4. Optionally, the cloud as a Spring profile, with a local profile on the memory provider, as in the portable microservice.

5. A report: what changed, what behaves differently, and what was left on native clients. Also the follow-ups, such as IAM grants and data migrations.

What maps to what#

Logins come from each cloud's default chain: IAM roles and EKS Pod Identity, managed identities and Entra Workload ID, Application Default Credentials and Workload Identity. The hand-written IAM code goes: token signers, credential providers and client beans. Errors map to Halyx's exceptions (NotFoundException, PreconditionFailedException and the rest), not SDK exceptions. Halyx has no equivalent for some services, such as Kinesis, Spanner, Cosmos DB's change feed, Event Grid basic topics and Datastore. Those stay on the native SDK, behind one class each.

Existing data and shared state#

No store keeps a decimal's scale (3.50 reads back as 3.5), so format amounts explicitly. Counters keep no expiry unless increment(key, delta, ttl) sets one; default-ttl doesn't apply to them.

Rollout: old and new instances side by side#

A rolling deploy runs both versions at once. Everything they share has to work both ways until the last old instance stops.

Events on EventBridge. Old instances publish the plain detail. Halyx publishes CloudEvents, so the old detail ends up under detail.data; Source and DetailType are unchanged. Change the rules before deploying:

{ "source": ["acme.loyalty"], "detail-type": ["TierChanged"],
  "$or": [ { "detail": { "tier": ["GOLD"] } }, { "detail": { "data": { "tier": ["GOLD"] } } } ] }

Halyx consumers read both formats: a plain event is decoded with detail as the data. A consumer outside the service that reads detail.tier keeps today's envelope with two rules:

• Old events: "detail": { "specversion": [ { "exists": false } ] }, delivered as they are.
• CloudEvents: { "exists": true }, through an input transformer that rebuilds the old shape from $.detail.data.*.

One transformer for both formats doesn't work: on old events its paths are missing, and the result isn't valid JSON. Remove the old halves after the rollout.

Event Grid namespaces and Eventarc Advanced carry CloudEvents on both sides already. Keep the type, source, subject and data, and subscribers see no change.

Counters, rate limits and locks share keys through namespace: "". Kafka keeps its topics, formats and groups. @Cacheable entries aren't shared between the versions; each version fills its own.

While both libraries are present#

The old library stays until its last use is gone, and the two get in each other's way:

• SDK versions. The Spring Cloud BOMs pin older SDKs than Halyx needs:

  • AWS SDK 2.31 against Halyx's 2.55
  • azure-sdk-bom 1.2.33 against 1.3.8
  • Google Cloud libraries-bom 26.83.0 against 26.90.0

  Import the SDK's BOM at Halyx's version first.

• Auto-configuration. A provider module brings its cloud's SDK clients, and the old library's auto-configuration switches on for each one it finds, even for services the code never used. With Spring Cloud GCP, startup failed:

  • for Firestore, Pub/Sub, Storage, Secret Manager and Parameter Manager
  • and for Cloud SQL, through the connector Halyx needs

  Turn those off (spring.cloud.gcp.<service>.enabled: false) until Spring Cloud GCP is removed.

• Test-scoped SDK artifacts. Re-declaring, say, software.amazon.awssdk:sqs with <scope>test</scope> for the tests' own clients makes halyx-aws's SQS client test-only. Every test passes; the packaged service fails at startup with NoClassDefFoundError. Let the tests use the clients the provider module brings, and check mvn dependency:list -DincludeScope=runtime.

• Bean names. Every halyx.* key is a bean name. A class Bookings and halyx.databases.bookings clash, and startup fails, naming both.

• Azure identities. Halyx's default chain takes a user-assigned identity's client id from AZURE_CLIENT_ID. Spring Cloud Azure's credential.client-id therefore moves into the deployment's environment. Workload ID on AKS sets it already.

• JDK cache codec. Like Spring's default serializer, it reads any class unless trusted-packages is set. Set it.

Testing a migration#

Trials#

Six Spring Cloud services were migrated step by step: two per cloud, between them using every kind of service Halyx covers.

In each, the original tests passed with their assertions unchanged. The exceptions were the event checks that had read a mocked SDK client: they now read the Halyx bus and check the same values. The data the old library had written read correctly through Halyx.

The second trial on each cloud then ran on a throwaway cluster, logging in with the platform's workload identity. It was driven over HTTP, and the test machine checked what subscribers outside the service receive:

The trials found one Halyx bug, now fixed: next to another Spring Data module, both claimed every repository. They also made two startup errors clearer: halyx.databases and halyx.spring-kafka on the memory provider now say what to use instead.