A newer version of Hazelcast Platform is available.

View latest

Helm Upgrade Guide

6.0-SNAPSHOT 5.5 5.4 5.3 5.2 5.1 5.0

Before upgrading, review the Hazelcast Compatibility Guarantees.

Due to a bug in the Helm Project, the helm upgrade command does not allow modifications to the spec.volumeClaimTemplates property in stateful sets. This results in some limitations for persistence in Hazelcast Management Center and any hotRestart/persistence using volumeClaimTemplates internally. The following sections provide some methods of addressing these limitations.

Note Although we have tested common scenarios without hotRestart (persistence) and the Management Center persistence feature enabled, we cannot test every upgrade scenario. If you encounter issues, please contact Support.

We recommend that you disable Management Center before you upgrade, and re-enable it after the upgrade. To do this, complete the following steps:

  1. Export the values from your existing installation:

    helm get values <release-name> > values.yaml
    bash

  2. Disable Management Center:

    helm upgrade <release-name> hazelcast/hazelcast-enterprise -f values.yaml --version <installed-version> --set mancenter.enabled=false
    bash

  3. Delete the persistent volume of the disabled Management Center:

    kubectl get pvc -o name | grep "mancenter" | xargs -n 1 kubectl delete
    bash

  4. Upgrade your installation, and re-enable Management Center, as described in the Upgrade Hazelcast section below.

Upgrade Hazelcast

The following sections cover scenarios for upgrading Hazelcast with persistence/hotRestart enabled.

Hazelcast Version 4.x to 5.x

You can use rolling upgrades when moving from version 4.2 to version 5.0. For further information on rolling upgrades, see the Hazelcast’s Compatibility Guarantees topic.

Note If upgrading from a Helm Chart of version 3.10 or earlier, Helm Chart upgrade is not supported. For information on other ways to upgrade, see the Alternative Solutions section below.
Warning You should set hazelcast.yaml.hazelcast.hot-restart-persistence.cluster-data-recovery-policy field to PARTIAL_RECOVERY_MOST_COMPLETE to avoid any problems.

If you are using version 3.11, we recommend upgrading to 5.3.9 as follows:

helm get values > values.yaml
helm upgrade hz hazelcast/hazelcast-enterprise --version 5.3.9 -f values.yaml
bash

Hazelcast Version 5.x to 5.x

Hazelcast rolling upgrade and chart upgrade can be used from version 5.4.7 to 5.9.2. However in version 5.8.0, hot-restart-persistence was renamed to persistence. To upgrade from version 5.8.0, complete the following steps:

  1. Export the values from the existing installation:

    helm get values <release-name> > values.yaml
    bash

  2. Modify existing values:

    • Optionally, replace hot-restart-persistence with persistence in your Hazelcast configuration. For further information on configuring persistence, see the Configuring Persistence topic.

      Note This step is optional, as the previous configuration is still supported in later Hazelcast versions.

    • Replace the hotRestart field in the values.yaml file with persistence. An example of the required change is provided in the version kubernetes:helm-hazelcast-enterprise-chart.adoc#5-8-0 section of the the Notable Changes in Helm Chart topic.

  3. Upgrade using your updated values:

    helm upgrade hz hazelcast/hazelcast-enterprise --version 5.8.0 -f values.yaml
    bash
Note If you are upgrading from a version that is not mentioned above, use an alternative method.

Alternative Solutions

The following alternative methods can be used:

Persistence-based

Warning This solution does not support rolling upgrades.

To use the persistence-based solution, complete the following steps:

  1. Export the values from your existing installation:

    helm get values <release-name> > values.yaml
    bash

  2. Uninstall existing cluster:

    helm uninstall <release-name>
    bash

  3. Install a cluster with the same name as the previous cluster but using a later Helm Chart version:

    Warning To attach volumes correctly, you must use the same cluster name and size. 
    helm install <release-name> --version <newer-version> -f values.yaml
    bash

Retain Helm Chart Version

This solution does support rolling upgrades, but does not allow you to benefit from the improvements in later Helm Chart versions.

For example to upgrade Hazelcast version 5.0.0, which was deployed to a cluster using Helm Chart version 5.2.0, to version is 5.3.6, you would complete the following steps:

  1. Upgrade Hazelcast to version 5.1.1 without upgrading the Helm Chart version:

    Note As mentioned above, you must upgrade each minor version, so we must upgrade Hazelcast multiple times as shown in the next steps. 
    helm upgrade --reuse-values hz hazelcast/hazelcast-enterprise --set image.tag=5.1.1 --version 5.2.0
    bash

  2. Upgrade Hazelcast to version 5.2.1 without upgrading the Helm Chart version:

    helm upgrade --reuse-values hz hazelcast/hazelcast-enterprise --set image.tag=5.2.1 --version 5.2.0
    bash

  3. Upgrade Hazelcast to version 5.3.6 without upgrading the Helm Chart version:

    helm upgrade --reuse-values hz hazelcast/hazelcast-enterprise --set image.tag=5.3.6 --version 5.2.0
    bash
lifebuoy

Help and support