Upgrading from IMDG 4.x
This guide covers the most important changes that affect users of IMDG 4.x who want to upgrade to Hazelcast.
This guide is not an overview of the new features in Hazelcast Platform. This release includes other enhancements that don’t need any special attention during an upgrade.
Before you Upgrade
If you are using IMDG Enterprise version 4.x, you can migrate your data to a Hazelcast Platform cluster. See Migrating Data from IMDG 3.12.x.
Merge of Hazelcast and Jet
The open source and Enterprise code and documentation of former Hazelcast IMDG and Jet have been merged as Hazelcast, as version 5.0. The following sections elaborate the changes performed for this merge.
Version Compatibility
You can find the rules for compatibility in this section.
Semantic Versioning
Hazelcast uses semantic versioning:
-
MAJOR version when you make incompatible API changes
-
MINOR version when you add functionality in a backwards-compatible manner
-
PATCH version when you make backwards-compatible issue fixes.
Compatibility with Former IMDG Versions
Hazelcast Platform is fully API-compatible with former Hazelcast IMDG 4.x versions with the exception of a few breaking changes.
To migrate data from an IMDG 4.x cluster to 5.0, you need to either persist them to disk or do rolling upgrade; see Persistence and Rolling Upgrades for more information.
It is not possible to upgrade a running IMDG 3.12.x cluster to Platform 5.x using rolling upgrades or persistence. You can use the migration tool for this purpose to migrate your 3.12.x data to 5.x; see Migrating Data from IMDG 3.12.x for details.
Compatibility with Client Versions
All the 4.x.y versions of Hazelcast Java, .NET, C++. Python and Node.js clients are compatible with Hazelcast Platform. The Hazelcast Go client 1.0.0 version is compatible with Hazelcast Platform.
However, the 3.12.x versions of Hazelcast clients is not compatible with Hazelcast Platform. See Client Migration.
Compatibility with Management Center Versions
We recommend you run the latest Management Center version for the minor release of the Platform. For example, if you use Platform version 5.1.7, use the latest version of Management Center in its 5.1.x series.
API Compatibility
-
Types and methods annotated with
@EvolvingApionly provide PATCH level compatibility guarantee. These are typically new features where the API is subject to further changes. -
Classes in
implandinternalpackages do not provide any compatibility guarantees between versions and are not meant for public use.
Licenses
-
You are able to use your current Hazelcast Enterprise/Enterprise HD licenses when moving to Hazelcast Platform without any license upgrade.
-
If you have a Hazelcast Enterprise or Enterprise HD license, you will be able to discover and use Hazelcast’s Jet features (both the open source and Enterprise ones) when you move to Hazelcast Platform.
-
Hazelcast Platform does not offer the former Pro Edition for Hazelcast. Existing Pro Edition customers' licenses will be renewed if requested.
-
All the features of Hazelcast Open Source edition are available in Hazelcast Platform.
Merge of SQL Modules
The former Hazelcast product had hazelcast-sql, hazelcast-sql-core and
hazelcast-jet-sql Maven modules in its distribution. These have been merged into
a single hazelcast-sql module as a part of the Hazelcast Platform distribution.
Changes in Distribution Packaging
Former Hazelcast IMDG product had hazelcast and hazelcast-all modules
for the core distribution and the distribution with all extensions, respectively.
The hazelcast-all module has been removed after the merge of former IMDG product.
|
Hazelcast Platform provides, like the former Jet product, slim and full packagings.
The slim one includes only the following:
-
Hazelcast runtime
-
Default configuration files (not example ones)
-
Scripts
The full one includes the following:
-
Hazelcast and its modules contained in the former
hazelcast-all-
AWS discovery plugin
-
Kubernetes discovery plugin
-
GCP discovery plugin
-
Azure discovery plugin
-
Hazelcast Hibernate
-
Hazelcast Spring
-
SQL
-
-
Jet extensions
-
Management center
Script Files
With the merge of former IMDG and Jet products, there have been changes made to the scripts provided in the distributions.
See the following table for the before/after script distributions:
| IMDG 4.x | Hazelcast Platform |
|---|---|
— — — — — — — |
— — — — — — — — — — |
Configuration Files
With the merge of former IMDG and Jet products, there have been changes made to the configuration files provided in the distributions.
See the following table for the before/after configuration distributions:
| IMDG 4.x | Hazelcast Platform |
|---|---|
— — — — — — — |
— — — — — —
— — — — — — — |
Configuration
With the merge of former Hazelcast IMDG and Jet products into Hazelcast Platform, there have been changes in the configuration mechanism as described in the below subsections.
Merge of Declarative Configurations
The former Hazelcast and Jet declarative configuration files have been merged into a single Hazelcast XML/YAML file. Basically, the Jet configuration elements have been added to the IMDG’s XML/YAML files. See the Jet engine related configuration elements in the unified file here
Introduction of YAML Configuration Validator
Hazelcast Platform checks and validates your YAML configurations during a cluster startup. According to this validation:
-
the top-level
hazelcastobject must exist -
client and member YAML configurations must be separate, not in the same file
-
there must be no case insensitive enum values.
While upgrading to Hazelcast Platform, if a YAML configuration violates any of the above,
the cluster will not start. You need to either edit and update your YAML configuration files
accordingly or disable the validation by setting the hazelcast.config.schema.validation.enabled property to false.
