Upgrading from IMDG 4.x

6.0-SNAPSHOT 5.5 5.4 5.3 5.2 5.1 5.0

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.4.x, use the latest version of Management Center in its 5.4.x series.

API Compatibility

  • Types and methods annotated with @EvolvingApi only provide PATCH level compatibility guarantee. These are typically new features where the API is subject to further changes.

  • Classes in impl and internal packages do not provide any compatibility guarantees between versions and are not meant for public use.

User Code Deployment

The adding of Java classes to members using User Code Deployment was deprecated in Platform 5.4.

The User Code Namespaces feature, which extends User Code Deployment to allow you to redeploy your classes, is available for Enterprise users.

Hazelcast recommends that Enterprise users migrate their user code to use User Code Namespaces. For further information on migrating from User Code Deployment to User Code Namespaces, see the Migrate from User Code Deployment topic.

Open Source users can either upgrade to Enterprise Edition, or add their resources to the Hazelcast member class paths.

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

/bin

 — cluster.sh

 — cp-subsystem.sh

 — healthcheck.sh

 — start.bat

 — start.sh

 — stop-all.bat

 — stop-all.sh

/bin

 — common.sh

 — hz-cli

 — hz-start

 — hz-healthcheck

 — hazelcast-stop

 — hz-cluster-admin

 — hz-cluster-cp-admin

 — hz-start.bat

 — hz-stop.bat

 — hz-cli.bat

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

/bin

 — hazelcast-client-failover-full-example.xml

 — hazelcast-client-failover-full-example.yaml

 — hazelcast-client-full-example.xml

 — hazelcast-client-full-example.yaml

 — hazelcast-full-example.xml

 — hazelcast-full-example.yaml

 — hazelcast.xml

/config

 — hazelcast-client.yaml

 — hazelcast.yaml

 — jmx_agent_config.yaml

 — jvm-client.options

 — jvm.options

 — log4j2.properties

/config/examples

 — hazelcast-client-full-example.xml

 — hazelcast-client-full-example.yaml

 — hazelcast-client.yaml

 — hazelcast-full-example.xml

 — hazelcast-full-example.yaml

 — hazelcast-security-hardened.yaml

 — hazelcast.yaml

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 hazelcast object 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.

lifebuoy

Help and support