Migrating Hazelcast IMDG 3.x to Platform 5: Why There Is No Rolling Upgrade

The constraint that defines the project

Hazelcast's migration documentation states that because breaking changes were made to both the client and the cluster member protocols, it is not possible to perform any in-place or rolling upgrade from a running IMDG 3.12.x cluster to Platform 5.0.

Everything else about this migration follows from that sentence. A 3.x member cannot join a 5.x cluster. A 3.x client cannot talk to a 5.x member. There is no mixed-version window in which the grid stays up while nodes are replaced one at a time — which is precisely the mechanism most teams were counting on.

Why that is a bigger problem for a data grid than for most software

For a stateless service, “no rolling upgrade” means a maintenance window. For an in-memory data grid it means something more awkward, because the state is the service:

• The data lives in memory. Stop the 3.x cluster and, unless persistence or a backing store is configured, the contents are gone.
• Clients and members must move together. Every application embedding a 3.x client has to be rebuilt against the 5.x client and deployed in step with the new cluster.
• Session state is usually the payload. For many estates the grid holds HTTP sessions. Losing it logs every user out at once.

What changed between 3.x and 5.x

• Protocols. Both the cluster member protocol and the client protocol changed after 3.x. Hazelcast's documentation names this as the reason no in-place or rolling upgrade is possible.
• Package and API restructuring. Hazelcast's migration notes list many of these — predicate classes such as PagingPredicate and PartitionPredicate converted to interfaces with implementations moved to impl packages, PredicateBuilder and EntryObject likewise, merge policies relocated under com.hazelcast.spi.merge. Application code that imports these will not compile unchanged.
• Platform consolidation. In 5.0, IMDG and the Jet stream-processing engine were merged into a single Hazelcast Platform distribution. Dependencies and artifact coordinates change accordingly.
• Serialization. The format your objects are stored in matters as soon as data has to cross versions, which in this migration it must.

The migration patterns that work

1. Parallel cluster, reload from source of truth

If the grid is a cache in front of a database, this is the clean answer. Build the 5.x cluster alongside, point the rebuilt applications at it, and let it warm from the backing store. The cost is a cold cache and the load spike on the database that comes with it — size for that spike, because it arrives all at once.

2. Parallel cluster, dual-write during transition

Applications write to both grids for a period, read from the old one, then flip reads. It keeps the new grid warm, at the cost of application changes you will later remove and a consistency window you must reason about.

3. Export and import through a neutral format

For grids that are the system of record for something, data has to be extracted from 3.x and loaded into 5.x through a format both sides understand. Hazelcast offers migration tooling for moving data between versions; check its edition and version requirements against what you run, since several of the capabilities that make this easier sit on the commercial side.

4. Accept session loss, deliberately

For session state specifically, the honest cheapest option is often a scheduled cutover where users re-authenticate. It is unglamorous and it removes an enormous amount of migration complexity. It should be a decision the business makes knowingly, not an accident.

What to establish before choosing

1. Is the grid a cache or a system of record? This one answer eliminates half the options.
2. Which data structures and features are in use? Maps only, or also queues, topics, executors, entry processors, WAN replication?
3. How are objects serialized? Java serialization, IdentifiedDataSerializable, Portable, or a custom serializer.
4. How many applications embed the client, and can they all be released in step?
5. Community or Enterprise edition? Hazelcast is open core. WAN replication, persistence and rolling-upgrade tooling are commercial features, and their absence narrows your migration options.

A note on risk while you plan

Grid members exchange serialized Java objects and trust one another by cluster membership. That makes deserialization advisories in this class of product remote code execution rather than information disclosure, and it makes a flat network — member ports reachable beyond the cluster subnet — the single most common serious finding. Whatever your migration timeline, check that today:

# Member ports should not be reachable from outside the cluster subnet
nmap -p 5701-5703 hazelcast-member.internal

Where OSSeva fits

We ship patched IMDG 3.x and 4.x builds with matched client and member artifacts, so the serialization format and protocols your applications depend on stay fixed while the migration is designed. Because we also cover GemFire, Geode and Ignite, the assessment compares staying within Hazelcast against moving to a different grid on the features you actually use — which, for a migration this disruptive, is a question worth asking once.

Related

• Hazelcast extended support
• GemFire and Apache Geode · Apache Ignite