This is a prerelease version.

View latest

Configuring Dynamic Configuration

You can configure members to keep dynamic configuration changes in memory or persist them to a YAML or XML configuration file.

Glossary

Term Definition

root configuration file

XML or YAML configuration file that is used to configure a member at startup.

Production Checklist

Before you start configuring members to persist dynamic configuration changes, consider the following checklist:

  • Does your cluster have enough available disk space, especially if you want to create backups of the configuration file?

  • Does your cluster have read/write permissions for the configuration file? All members must have write permissions to the configuration file.

  • Is your cluster free of configuration conflicts? Hazelcast does not support persistence in clusters that have conflicting configuration files.

  • Are you using a root configuration file to start members? Dynamic configuration changes are persisted to the root configuration file, so you need to configure and start Hazelcast with that file.

Running clusters must be restarted before any configuration changes take effect.

Development Checklist

Before you start configuring members to persist dynamic configuration changes, consider the following checklist:

  • Do you start multiple members on a single device? Each member should have a unique root configuration file.

Kubernetes Checklist

If you use Kubernetes, do not configure persistence for dynamic configuration. Dynamic configuration changes are persisted to the root configuration file, not the ConfigMap.

Enabling Persistence

Enterprise Edition

By default, persistence for dynamic configuration changes is disabled on all clusters. To start persisting changes on disk, you must first enable the feature on the member.

To enable persistence for dynamic configuration changes, set the persistence-enabled option to `true.

  • XML

  • YAML

<hazelcast>
  <dynamic-configuration>
    <persistence-enabled>true</persistence-enabled>
  </dynamic-configuration>
</hazelcast>
hazelcast:
  dynamic-configuration:
    persistence-enabled: true

Creating Backups of the Configuration File

Enterprise Edition

By default, Hazelcast keeps 5 backups of the configuration file in the member’s startup directory.

To change the number of backups, configure the backup-count option. To change the directory in which to store the backups, configure the backup-dir option.

The filenames of backups are in the following format, which includes the date and time when they were created followed by the .backup extension: yyyy-MM-dd—​HH-mm-ss-SSS.backup. For example, 2022-01-31—​13-23-44-699.backup.

If the backup directory contains existing files with the .backup extension or if time is shifted while the member is running, the order of backups can be corrupted.
  • XML

  • YAML

<hazelcast>
  <dynamic-configuration>
    <persistence-enabled>true</persistence-enabled>
    <backup-dir>/data/dynamic/backups</backup-dir>
    <backup-count>7</backup-count>
  </dynamic-configuration>
</hazelcast>
hazelcast:
  dynamic-configuration:
    persistence-enabled: true
    backup-dir: /data/dynamic/backups
    backup-count: 7

Configuration Options

Use the following configuration options to configure dynamic configuration for a cluster.

Table 1. Configuration options for dynamic configuration
Option Description

dynamic-configuration

Root configuration

persistence-enabled Enterprise Edition

Whether changes made in dynamic configuration are persisted to a configuration file. Default: false.

backup-dir Enterprise Edition

Relative or absolute path to a directory in which to store backups of the configuration file. Each new backup will be created inside this directory. Default: A new directory called dynamic-configuration-backups is created in the member’s startup directory.

backup-count Enterprise Edition

Number of backups of the configuration file to keep. To disable backups, set this option to 0. Default: 5.

Full Example

  • XML

  • YAML

<hazelcast>
  <dynamic-configuration>
    <persistence-enabled>true</persistence-enabled>
    <backup-dir>/data/dynamic/backups</backup-dir>
    <backup-count>7</backup-count>
  </dynamic-configuration>
</hazelcast>
hazelcast:
  dynamic-configuration:
    persistence-enabled: true
    backup-dir: /data/dynamic/backups
    backup-count: 7