YAML declarative configuration
You can declare cluster connections, the security provider, static hazelcast.mc.* settings, and other settings in a single YAML file that Management Center applies automatically on startup.
Beta feature. The YAML declarative configuration file format described on this page may change in a future release without notice.
Today, hz-mc conf and the UI are the two ways to configure Hazelcast cluster connections, local users, the security provider, sensitive-properties masking, and Prometheus scrape-endpoint authentication. Both are imperative: an operator runs a command or clicks through the UI, against an already-running (UI) or already-stopped (hz-mc conf) instance.
A YAML declarative configuration file gives you a third option: declare that same configuration once, as a file, and Management Center applies it automatically every time it starts. This fits cloud-native and GitOps deployments, where the whole identity of an instance should come from a mounted file or a checked-in manifest, and where secrets should be sourced from files (such as Docker or Kubernetes secret mounts) instead of passed as CLI arguments or environment variables.
hz-mc conf and the UI are completely unaffected by this feature and remain fully usable. The YAML file only touches whatever it declares; anything configured through hz-mc conf or the UI and not mentioned in the file is left alone.
What you can and can't declare
The YAML file covers the same persisted entities that hz-mc conf writes to Management Center's database:
| Key | Covers the same ground as |
|---|---|
clusters | Connect with hz-mc conf (both forms, see Cluster connections) |
sensitive | The set sensitive- task, see Hide sensitive configuration in the UI |
prometheus | Authenticate the scrape endpoint |
properties | Static hazelcast. settings, see Static settings. Not persisted, and not governed by apply. |
security | Security Providers (local, ldap, active, jaas, oidc, saml, dev) |
In addition, the properties key sets Management Center's static settings, such as ports, TLS, and LDAP SSL keystores, which you otherwise set with system properties and environment variables. See Static settings.
The file covers only one-time configuration writes. It cannot issue or revoke REST API auth tokens, or reset the security provider.
Point Management Center at a configuration file
Set the hazelcast.mc.config.file system property (or the HAZELCAST_MC_CONFIG_FILE environment variable) to the path of your YAML file before starting Management Center. See hazelcast.mc.config.file.
- Linux and Mac
- Windows
- Docker / Kubernetes
hz-mc start -Dhazelcast.mc.config.file=/path/to/mc-config.yaml
mc-start.cmd -Dhazelcast.mc.config.file=C:\path\to\mc-config.yaml
docker run -e HAZELCAST_MC_CONFIG_FILE=/config/mc-config.yaml \
-v /host/path/mc-config.yaml:/config/mc-config.yaml \
hazelcast/management-center
The file is applied entirely before Management Center opens its web server port. If anything in it is invalid, Management Center refuses to start and prints a clear error message — there's never a window where the server looks "up" with a half-applied configuration.
applyMode: how re-running the file behaves
By default, every entity the file declares must be absent, or Management Center refuses to start. Set applyMode: upsert to also allow updating entities that already exist, and to remove clusters, Prometheus authentication, sensitive-properties settings and local users that the file does not declare. This makes it safe to leave the same file pointed at hazelcast.mc.config.file across restarts. See Declarative configuration apply modes for the full explanation and mixed-configuration examples.
Static settings
The properties key sets static hazelcast.mc.* settings, such as the LDAP SSL keystore and its password, without passing -D options or JAVA_OPTS. In Kubernetes, this lets you mount the whole file, or the part of it that holds passwords, from a Secret instead of putting plain-text values in the StatefulSet's environment variables.
properties:
hazelcast.mc.ldap.ssl.keyStore: /run/secrets/ldap/keystore.jks
hazelcast.mc.ldap.ssl.keyStoreType: JKS
hazelcast.mc.ldap.ssl.keyStorePassword: changeit
Each key is the exact name of a system property, written with dots. The environment variable names, such as MC_LDAP_SSL_KEY_STORE, are not accepted as keys. Each value is a single scalar: a string, a number, or a boolean.
Unlike the other top-level keys of the file, properties is not written to Management Center's database. Management Center reads it at startup, and it takes effect only for that run. To change a setting, edit the file and restart Management Center. For the same reason, applyMode does not apply to this section.
Precedence
If you set the same property in more than one place, Management Center uses the value from the source nearest the top of this list:
- Command-line arguments.
- System properties (
-Doptions andJAVA_OPTS). - Environment variables.
- The
propertiessection of the declarative configuration file. application.propertiesdefaults.
The file therefore supplies defaults that an operator can still override for a single run (for example, with -D). When a value in the file is overridden, Management Center logs the property name and the source that overrides it at startup. It never logs a value, because values are often passwords.
Values
Management Center uses a value exactly as you write it. It does not convert unquoted values, so 0123 stays 0123 and is not read as a number, and a password such as 1e3 is not changed to 1000. Quote a value only when YAML syntax requires it, for example if it contains # or starts with *.
Values go through the variable replacers configured on the instance, the same as system properties and environment variables do. For example, you can use $ENC{...} values.
The file: convention is not available in properties. A value such as file:/run/secrets/password is used literally as that text. To keep a secret out of the file, use a variable replacer, or declare the file itself as a Kubernetes Secret.
Restrictions
Management Center rejects the file, and does not start, in these cases:
- A key is not the name of a Management Center system property. This catches typos that would otherwise be silently ignored.
- A key is
hazelcast.mc.config.file. This property locates the declarative configuration file, so you can only set it as a system property or environment variable. - A value is missing, a list, or a nested map, or a key is repeated.
properties:is present but has nothing after it.
The error message names the key, never the value. For example, if you misspell a key as hazelcast.mc.ldap.ssl.keystore, Management Center fails to start with this message:
Description:
Invalid declarative configuration file '/config/mc.yaml': properties contains unknown property 'hazelcast.mc.ldap.ssl.keystore'.
Action:
Fix the declarative configuration file referenced by 'hazelcast.mc.config.file' (or the HAZELCAST_MC_CONFIG_FILE environment variable) and restart Management Center.
Cluster connections
The clusters key mirrors hz-mc conf cluster add — see Connect with hz-mc conf. Each entry uses one of two mutually exclusive forms, resolved from which fields are present, the same way securityProvider resolves its provider type:
name+memberAddresses— the plain form.clientConfigFile— a path to a Hazelcast client configuration file (XML or YAML), needed for TLS or other advanced client settings. The cluster's name comes from the file itself (its owncluster-name), not from a field in the YAML.
clusters:
- name: prod-cluster
memberAddresses:
- "10.0.0.1:5701"
- "10.0.0.2:5701"
enabled: true
- clientConfigFile: "/etc/mc/tls-cluster-client-config.xml"
| Field | Description |
|---|---|
name | Cluster name. Required with member; must be omitted with client. |
member | List of one or more member addresses. Required with name; must be omitted with client. |
enabled | Whether Management Center tries to connect on startup. Default: true. |
client | Path to a Hazelcast client configuration file (XML or YAML). Mutually exclusive with name/member. A relative path is resolved against Management Center's own working directory at startup, not against the declarative configuration file's location — use an absolute path to avoid ambiguity. See the UI or hz- for help creating one, including TLS setup. |
Two clusters entries sharing the same name (whichever form resolves it) in the same file are always rejected. A clientConfigFile whose parsed configuration doesn't use ALL_MEMBERS routing mode is rejected too, the same way the UI upload and hz-mc conf cluster add --client-config already reject it.
Sensitive properties
The sensitiveProperties key mirrors hz-mc conf set sensitive-properties, see Hide sensitive configuration in the UI.
sensitiveProperties:
hidden:
- "some.system.property"
maskedConfigXPaths:
- "//password"
| Field | Description |
|---|---|
hidden | Member properties to hide in the member properties view. |
masked | XPath expressions in the member configuration to mask. |
Omitting one of these two keys leaves the corresponding setting untouched under applyMode: upsert — see Declarative configuration apply modes.
Prometheus scrape-endpoint authentication
The prometheusAuth key mirrors hz-mc conf set prometheus-auth, see Authenticate the scrape endpoint.
prometheusAuth:
username: prometheus
password: "file:/run/secrets/prometheus-password"
Security provider
The securityProvider key mirrors hz-mc conf <provider> configure, see Security Providers. Exactly one of ldap, activeDirectory, jaas, oidc, saml, local, or devMode may be present — there's no separate type field; which provider you're declaring is resolved from which block you write.
If a different security provider type is already active (however it got there — the UI, hz-mc conf, or a previous declarative run) than the one declared, the whole file is always rejected: run hz-mc conf security reset first, then restart with the file. The one exception is Dev Mode: since it isn't a deliberately-configured provider, a file may declare any other provider type — including local — while Dev Mode is active, with no reset needed first. See Switch to a new security provider and Declarative configuration apply modes.
Local
Mirrors Local security provider. Unlike the other providers, the local block holds no connection config, only the users to provision once the provider is active. The block must declare at least one user with the admin role, or Management Center refuses to start. role is one of readonly, readwrite, metricsonly, or admin.
securityProvider:
local:
users:
- username: admin
role: admin
password: "file:/run/secrets/admin-password"
Two users entries sharing the same username in the same file are always rejected. Under applyMode: upsert, Management Center deletes local users that are not listed, admins included. Passwords must meet the same complexity rules as creating a user in the UI or with hz-mc conf.
LDAP
Mirrors LDAP.
securityProvider:
ldap:
url: "ldaps://ldap.example.com"
username: "cn=admin,dc=example,dc=com"
password: "file:/run/secrets/ldap-bind-password"
userDn: "ou=users,dc=example,dc=com"
groupDn: "ou=groups,dc=example,dc=com"
userSearchFilter: "(uid={0})"
groupSearchFilter: "(member={0})"
startTls: false
nestedGroupSearch: false
# Optional - omit entirely to skip keystore setup.
keystore:
create: false
path: "/path/to/keystore.jceks"
password: "file:/run/secrets/keystore-password"
type: JCEKS
roles:
adminGroups: "mc-admins"
readWriteGroups: "mc-writers"
readOnlyGroups: "mc-readers"
metricsOnlyGroups: "mc-metrics"
The optional keystore block mirrors LDAP password encryption. Set create: true to have Management Center create and manage a new keystore at path, or create: false to use an existing one (optionally with type and provider).
Active Directory
Mirrors Active Directory.
securityProvider:
activeDirectory:
url: "ldap://ad.example.com"
domain: "example.com"
userSearchFilter: "(sAMAccountName={0})"
nestedGroupSearch: false
roles:
adminGroups: "mc-admins"
readWriteGroups: "mc-writers"
readOnlyGroups: "mc-readers"
metricsOnlyGroups: "mc-metrics"
JAAS
Mirrors JAAS.
securityProvider:
jaas:
loginModuleClass: "com.example.MyLoginModule"
roles:
adminGroups: "mc-admins"
readWriteGroups: "mc-writers"
readOnlyGroups: "mc-readers"
metricsOnlyGroups: "mc-metrics"
OpenID Connect
Mirrors OpenID Connect.
securityProvider:
oidc:
clientId: "mc-client"
clientSecret: "file:/run/secrets/oidc-client-secret"
authorizationEndpoint: "https://idp.example.com/authorize"
userInfoEndpoint: "https://idp.example.com/userinfo"
tokenEndpoint: "https://idp.example.com/token"
jwkSetEndpoint: "https://idp.example.com/jwks"
issuer: "https://idp.example.com"
redirectUrl: "https://mc.example.com/oidc/auth"
# Optional - defaults shown.
scope: "openid"
userIdClaimName: "sub"
groupsClaimName: "groups"
jwsAlgorithm: "RS256"
userInfoRequestHttpMethod: "GET"
sendClientInfoInTokenRequest: false
roles:
adminGroups: "mc-admins"
readWriteGroups: "mc-writers"
readOnlyGroups: "mc-readers"
metricsOnlyGroups: "mc-metrics"
SAML
Mirrors SAML.
securityProvider:
saml:
relyingPartyId: "mc"
postBackUrl: "https://mc.example.com/saml/sso"
groupAttribute: "memberOf"
idpMetadata: "https://idp.example.com/metadata"
# Optional - default shown.
groupNameSeparator: ";"
roles:
adminGroups: "mc-admins"
readWriteGroups: "mc-writers"
readOnlyGroups: "mc-readers"
metricsOnlyGroups: "mc-metrics"
Dev Mode
Mirrors Dev mode. Dev Mode needs no configuration of its own, so its block is an empty marker — its mere presence activates it.
securityProvider:
devMode: {}
A bare devMode: with nothing after it parses as YAML null, which is indistinguishable from omitting the key entirely — the empty braces ({}) are required, not optional decoration.
Secrets: the file: convention
Any secret field (securityProvider.local.users[].password, securityProvider.ldap.password, securityProvider.ldap.keystore.password, securityProvider.oidc.clientSecret, prometheusAuth.password) accepts a file:<path> value, which is resolved to the trimmed contents of that file at load time — the recommended way to supply secrets, for example from a Docker or Kubernetes secret mount. A literal value is also accepted.
prometheusAuth:
username: prometheus
password: "file:/run/secrets/prometheus-password"
This is a separate mechanism from variable replacers (e.g. $ENC{…}): it works regardless of which, if any, ConfigReplacer is configured on the instance, and only applies to the declarative configuration file.
A full example
# applyMode governs what happens when a declared entity already exists - see
# "Declarative configuration apply modes" in the docs. Defaults to createOnly when omitted.
# Under upsert, clusters, prometheusAuth, sensitiveProperties and local users not declared here are removed.
# applyMode: upsert
properties:
hazelcast.mc.ldap.ssl.keyStore: /run/secrets/ldap/keystore.jks
hazelcast.mc.ldap.ssl.keyStorePassword: changeit
clusters:
- name: prod-cluster
memberAddresses:
- "10.0.0.1:5701"
- "10.0.0.2:5701"
enabled: true
sensitiveProperties:
hidden:
- "some.system.property"
maskedConfigXPaths:
- "//password"
prometheusAuth:
username: prometheus
password: "file:/run/secrets/prometheus-password"
securityProvider:
ldap:
url: "ldaps://ldap.example.com"
username: "cn=admin,dc=example,dc=com"
password: "file:/run/secrets/ldap-bind-password"
userDn: "ou=users,dc=example,dc=com"
groupDn: "ou=groups,dc=example,dc=com"
userSearchFilter: "(uid={0})"
groupSearchFilter: "(member={0})"
startTls: false
nestedGroupSearch: false
roles:
adminGroups: "mc-admins"
readWriteGroups: "mc-writers"
readOnlyGroups: "mc-readers"
metricsOnlyGroups: "mc-metrics"
Validation and errors
Management Center validates the whole file before writing anything: property names, password strength and username format, XPath validity for masked-config properties, and whether declared entities already exist (governed by applyMode). The file is either entirely valid and applied in full, or nothing in it is applied — there's no partial application. Any failure aborts startup with a clear console message; Management Center never starts with a half-applied configuration.
Next steps
- Declarative configuration apply modes —
createOnlyversusupsert, including whatupsertremoves, with mixed-configuration examples. - Management Center Configuration Tool — the imperative alternative, and the tool this feature reuses under the hood.
- Switch to a new security provider — how to change the active security provider, including the Dev Mode exception.