Dynamic Configuration for Members

You can use dynamic configuration to add new configuration to members at runtime or update some supported configuration such as Enterprise Edition 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 Community Edition REST API

  The Community Edition REST API has been deprecated and will be removed as of Hazelcast version 7.0. An improved Enterprise version of this feature is available and actively being developed. For more information, see Enterprise REST API.

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

note

To use the REST endpoints you need an Enterprise Edition license.

Dynamic change	Programmatic API	Dedicated REST endpoint	Update and reload	SQL	Management Center	Supports Dynamic Configuration 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	N/A	Yes	Yes
Update a Hazelcast Enterprise Edition license	No	Yes	Yes	N/A	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
• DataConnection
• VectorCollection Enterprise EditionThis feature requires Hazelcast Enterprise, a licensed edition of the Hazelcast Platform.

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:

• Manual deployments
• Kubernetes

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.

   note

   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 (K8s), 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.

caution

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