This is a prerelease version.

View latest

Updating or Reloading Dynamic Configuration in REST

6.0-SNAPSHOT 5.5 5.4 5.3 5.2 5.1 5.0
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 info, see Enterprise REST API

You can use the /config/update and /config/reload REST endpoints to add dynamic configuration for some supported features at runtime:

  • /config/update: Send a configuration file in the request parameter.

  • /config/reload: Edit an existing configuration file that a member has already loaded and then reload it.

Changes are broadcast to the entire cluster. If you reload the configuration, you only need to edit one member’s configuration to affect the whole cluster.

You cannot send configuration changes through lite members.

Before you Begin

The REST API and the CLUSTER_WRITE endpoint group must be enabled on your cluster. See Community Edition REST API.

You can add new configuration only for some features. See Supported Dynamic Configuration Changes.

Dynamic configuration changes are not persisted by default. See Dynamic Configuration Persistence.

Editing and Reloading a Configuration File

  1. Make your changes to the file that stores your member’s configuration. For example, you may want to configure a new map with a backup count.

    Keep all existing configuration the same. You can only add new configuration blocks. To see what you can add see Supported Dynamic Configuration Changes

    • XML

    • YAML

    <hazelcast>
    <map name="new-map">
      <backup-count>
        2
      </backup-count>
    </map>
</hazelcast>
    hazelcast:
  map:
    new-map:
      backup-count: 2

  2. Send a POST request to the /config/reload endpoint of a cluster member.

    • If your cluster has security enabled, send the cluster password in the request.

      curl -X POST -H "Content-Type: text/plain" --data-urlencode "<cluster-name>" --data-urlencode "<cluster-password>" http://localhost:5701/hazelcast/rest/config/reload

    • If your cluster does not have security enabled, send the password as an empty string.

      curl -X POST -H "Content-Type: text/plain" --data-urlencode "<cluster-name>" --data-urlencode "" http://localhost:5701/hazelcast/rest/config/reload

The member sends back a response.

Updating Configuration

To update a member’s configuration, without editing the configuration file, use the /config/update endpoint.

This endpoint takes a URL encoded string of either YAML or XML as parameter. You only need to pass the new configuration blocks that you want to add with the hazelcast root. All existing configuration settings remain unchanged. However, you can include existing configuration blocks as well. The member will just ignore them.

If you are using the XML file format, make sure to provide the xmlns attribute: <hazelcast xmlns="http://www.hazelcast.com/schema/config"></hazelcast> instead of <hazelcast></hazelcast>.

For example, when a member has configuration for map-1 and map-2 in its configuration file, you can pass in a new configuration block for map-3 in the following ways:

  • The hazelcast root and the new map-3 configuration block.

  • The hazelcast root, map-1 and the new map-3 configuration block.

  • The hazelcast root, map-2 and the new map-3 configuration block.

  • The hazelcast root, map-1, map-2 and the new map-3 configuration block.

The outcome of these dynamic configuration changes is the same: A new configuration block for a map called map-3.

The configuration string must be URL encoded.

If your cluster has security enabled, send the cluster password in the request.

curl -X POST -H "Content-Type: text/plain" --data-urlencode "<cluster-name>" --data-urlencode "<cluster-password>" --data-urlencode "
hazelcast:
  map:
    map-3:
      backup-count: 2
" http://localhost:5701/hazelcast/rest/config/update

If your cluster does not have security enabled, send the password as an empty string.

curl -X POST -H "Content-Type: text/plain" --data-urlencode "<cluster-name>" --data-urlencode "" --data-urlencode "
hazelcast:
  map:
    map-3:
      backup-count: 2
" http://localhost:5701/hazelcast/rest/config/update

The member sends back a response.

Handling Partial Propagation

When you submit dynamic configuration changes to a member, they are propagated across all cluster members as well as those that may join the cluster later. If a failure occurs, such as timeouts, network partitions, or IO failures, you need to try adding the dynamic configuration changes again, dynamic changes are idempotent.

Request Response

When a member receives a dynamic configuration request, it checks if the configuration already exists and propagates any new configuration across the following:

  • Other members in the cluster.

  • Members that may join the cluster later.

You should see the new configuration in the response’s addedConfigs field:

{"status":"success","message":"Configuration Update successfully finished.","result":{"addedConfigs":[{"sectionName":"map","configName":"new-map"}],"ignoredConfigs":[]}}

The REST endpoints are idempotent. If you add a dynamic configuration for a block that already exists, the member will ignore the request and return the change you requested in the ignoredConfigs field.

Example ignored response
{"status":"success","message":"Configuration Update successfully finished.","result":{"addedConfigs":[],"ignoredConfigs":[{"sectionName":"map","configName":"existing-map"}]}}
lifebuoy

Help and support