A newer version of Hazelcast Platform is available.

View latest

Dynamic Configuration for Members

6.0-SNAPSHOT 5.5 5.4 5.3 5.2 5.1 5.0

You can use dynamic configuration to add new configuration to members at runtime or update some supported configuration such as Enterprise license keys. This feature is useful if you want to configure a running cluster without having to restart the members.

Adding Dynamic Configuration

You can add dynamic configuration, using the following options:

  • Programmatic API (Java member or client)

  • SQL

  • Management Center

  • Update and reload REST endpoints

  • Dedicated REST endpoints such as /addWanConfig

    Deprecation Notice for the REST API

    The REST API has been deprecated and will be removed as of Hazelcast version 7.0. An improved version of this feature is under development.

These options support different dynamic configuration changes, and not all changes support persistence. See the following table for what’s available with each option.

To use the REST endpoints you need an Enterprise license.
Table 1. Supported dynamic configuration options
Dynamic change Programmatic API Dedicated REST endpoint Update and reload SQL Management Center Supports persistence

Add a new configuration block for a supported data structure

Yes

No

Yes

No

Yes

Yes

Add a new WAN configuration block

Yes

Yes

Yes

No

Yes

Yes

Update a Hazelcast Enterprise license

No

Yes

Yes

No

Yes

Yes

Add a new index to an existing map

Yes

No

No

Yes

Yes, using CREATE INDEX in the SQL browser

No

Supported Data Structures

Dynamic configuration is supported for the following data structures:

  • Map

  • Cache

  • Queue

  • List

  • Set

  • MultiMap

  • ReplicatedMap

  • Ringbuffer

  • Topic

  • ReliableTopic

  • Executor

  • DurableExecutor

  • ScheduledExecutor

  • CardinalityEstimator

  • PNCounter

  • FlakeIdGenerator

  • ExternalDataStore

Persisting Dynamic Configuration

By default, dynamic configuration changes are stored in-memory and are lost when a cluster restarts.

To persist changes, you must follow one of the following procedures:

Persistence is idempotent. If a member fails to write changes to a file, you can add the same dynamic configuration again. For example, the following scenario is valid:

  1. Start a cluster with 3 members.

  2. Try adding dynamic configuration for a new map.

  3. The 2nd member doesn’t have write permissions for the configuration file, so it doesn’t persist the changes.

  4. Give the 2nd member write permissions.

  5. Add the same map configuration again.

  6. This time, the map configuration is added successfully.

Persisting Changes in Manual Deployments

To persist changes, you must do the following:

  1. Configure the member, using a configuration file.

    If you use the Java member API, you need to use an API that sets the configurationFile field of the Config object such as Config.setConfigurationFile() or Config.loadFromFile().

  2. Enable and configure persistence for dynamic configuration.

  3. Add dynamic configuration, using an option that supports persistence.

Persisting Changes in Kubernetes

To persist changes in Kubernetes, you must do the following:

  1. Update the ConfigMap with any of the configuration options that are supported by the /config/reload or /config/update REST endpoints.

  2. Apply your ConfigMap changes to Kubernetes. For example, you can use kubectl replace configmap.

  3. Do one of the following:

    • Wait 2-3 minutes for the ConfigMap changes to be applied to your pods, then call the /config/reload endpoint.

    • Call the config/update REST endpoint to reflect the changes you made to the ConfigMap in Hazelcast.

Dynamic Configuration and User Customizations

Some dynamic configuration settings might reference user customizations, such as a MapLoader implementation that is referenced in a map’s configuration. User customizations can usually be configured using either of the following:

  • A class or factory class name, such as MapStoreConfig.setClassName, that allows Hazelcast members to instantiate the object.

  • An existing instance, such as, MapStoreConfig.setImplementation.

User Code Deployment has been deprecated and will be removed in the next major version. To continue deploying your user code after this time, Community Edition users can either upgrade to Enterprise Edition, or add their resources to the Hazelcast member class paths. Hazelcast recommends that Enterprise Edition users migrate their user code to use User Code Namespaces for all purposes other than Jet stream processing. For further information on migrating from User Code Deployment to User Code Namespaces, see Migrate from User Code Deployment.

When adding a new data structure configuration with user customizations, take the following considerations into account:

  • Classes are resolved lazily, so they should be either already on each member’s local classpath or resolvable using user code deployment or User Code Namespaces.

  • Instances (or similarly factory instances) have to be serializable. This is because the entire configuration needs to be sent over the network to all cluster members, and their classes have to be available on each member’s local classpath.

Limitations

Although you can configure members to apply the client permissions of a new member, you can’t use dynamic configuration to make changes to client permissions.

lifebuoy

Help and support