A newer version of Hazelcast Platform is available.

View latest

Overriding Configuration

6.0-SNAPSHOT 5.5 5.4 5.3 5.2 5.1 5.0

You can override your clusters' configurations without having to modify the XML or YAML configuration files. Hazelcast makes this possible using the system properties or environment variables.

For example, if you just want to override cluster-name, you would need to craft a declarative configuration as follows:

  • XML

  • YAML

<hazelcast>
    <cluster-name name="dev"/>
</hazelcast>
hazelcast:
  cluster-name: dev

Instead of the above, you can achieve the same purpose using the following on the command line:

  • Using Environment Variable

  • Using System Property

export HZ_CLUSTERNAME=dev
java -Dhz.cluster-name=value

Recognized and unrecognized configuration entries will be logged when Hazelcast starts.

When overriding configuration provided in a custom file, remember to overwrite all the configuration sections at once; if you don’t, remaining entries are set to their default values.

The above mechanism exists mostly for the sake of trivial environment specific configuration changes, and should not be treated as a replacement for complex XML/YAML configuration files.

Conversion Rules

All entries need to mirror YAML configuration structure which differs slightly from XML’s.

In order to make Hazelcast recognize environment variables as valid configuration entries, they need to obey the following rules:

  • Each configuration entry needs to start with HZ_ or HZCLIENT_.

  • A new configuration level should be introduced with an underscore (_).

  • Dashes (-) should be removed.

  • Variable names should be in upper case.

Assume that you want to have the following configuration for your cluster, represented as YAML:

hazelcast:
  cluster-name: dev
  network:
    port:
      auto-increment: true
      port-count: 100
      port: 5701
    join:
      auto-detection:
        enabled: true

If you want to use the environment variables, the above would be represented as a set of the following environment variables:

HZ_CLUSTERNAME=dev
HZ_NETWORK_PORT_AUTOINCREMENT=true
HZ_NETWORK_PORT_PORTCOUNT=100
HZ_NETWORK_PORT_PORT=5701
HZ_NETWORK_JOIN_AUTODETECTION_ENABLED=true

In order to make Hazelcast recognize system properties as valid configuration entries, they need to obey the following rules:

  • Each configuration entry needs to start with hz. or hz-client..

  • A new configuration level should be introduced with a dot (.).

  • Variable names should be in lower case.

If you want to use the environment variables, the above YAML configuration would be represented as a set of the following system properties:

hz.cluster-name=dev
hz.network.port.auto-increment=true
hz.network.port.port-count=100
hz.network.port.port=5701
hz.network.join.auto-detection.enabled=true
Keep in mind that it’s not possible to override configuration entries using YAML sequences.
lifebuoy

Help and support