docs /api-reference /configurations

Configurations API

CRUD for instance configuration definitions. Configurations live in the Master Hazelcast configurations map (loaded from ./configuration/*.json) and describe how an instance is built and run. These endpoints list, read, create or update, and delete them.

A configuration is the blueprint an instance is deployed from: which runtime to use, the start command, the template tree to install, the port range to allocate from, and how many instances to keep running. Configurations are keyed by their unique name and stored in the Master’s distributed configurations map.

warning

All configuration endpoints require a token with ALL permission.

The Configuration object

Field	Type	Description
`name`	string	Unique configuration name (path key).
`runtime`	string	Runtime provider key. Default `screen`.
`command`	string	Command that starts the instance process.
`static`	boolean	Whether the working directory persists between restarts. Default `false`.
`ramMB`	integer	RAM allocated in MB. Default `2048`.
`cpu`	integer	CPU units (100 = 1 core). Default `100`.
`instanceGroups`	string[]	Groups this configuration belongs to.
`nodes`	string[]	Node IDs allowed to host this configuration.
`hostAddress`	string	Host address clients connect to.
`availablePorts`	PortRange	The `min` and `max` ports Universe scans when allocating.
`minimumServiceCount`	integer	Minimum instances the enforcer maintains. Default `1`.
`environmentVariables`	object	Environment variables, supporting `%VARIABLE%` substitution.
`templateInstallationConfig`	object	Which templates to install (`allOf`, `allInGroups`, `oneOf`, `oneInGroups`) and the override flag.
`fileModifications`	string[]	Files scanned for `%VARIABLE%` replacement after install.
`properties`	object	Additional key→value pairs exposed as template variables.

List configurations

GET /api/configurations

Returns every stored configuration as a JSON array.

curl http://<master>:7000/api/configurations \
  -H "Authorization: Bearer YOUR_TOKEN"

[
  {
    "name": "lobby",
    "runtime": "screen",
    "command": "java -Xmx2048M -jar server.jar",
    "static": false,
    "ramMB": 2048,
    "cpu": 100,
    "instanceGroups": ["lobby"],
    "nodes": ["node-1"],
    "hostAddress": "127.0.0.1",
    "availablePorts": { "min": 25565, "max": 25570 },
    "minimumServiceCount": 1,
    "environmentVariables": { "UNIVERSE_INSTANCE_ID": "%INSTANCE_ID%" },
    "templateInstallationConfig": {
      "allOf": [{ "name": "base", "group": "server", "storage": "local", "priority": 0 }],
      "allInGroups": [],
      "oneOf": [],
      "oneInGroups": [],
      "onTemplatePasteOverridePresentFiles": false
    },
    "fileModifications": ["server.properties"],
    "properties": {}
  }
]

Get a configuration

GET /api/configurations/{name}

Returns a single configuration by name.

Parameter	In	Description
`name`	path	The configuration name. Required.

curl http://<master>:7000/api/configurations/lobby \
  -H "Authorization: Bearer YOUR_TOKEN"

note

A name that does not exist returns 404 Not Found.

Create or update a configuration

PUT /api/configurations/{name}

Creates the configuration if the name is new, or replaces it if it already exists. The request body is a full Configuration object. On success the endpoint returns 204 No Content with no body.

curl -X PUT http://<master>:7000/api/configurations/lobby \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d @lobby.json

{
  "name": "lobby",
  "runtime": "screen",
  "command": "java -Xmx2048M -jar server.jar",
  "static": false,
  "ramMB": 2048,
  "cpu": 100,
  "instanceGroups": ["lobby"],
  "nodes": ["node-1"],
  "hostAddress": "127.0.0.1",
  "availablePorts": { "min": 25565, "max": 25570 },
  "minimumServiceCount": 1,
  "environmentVariables": {},
  "templateInstallationConfig": {
    "allOf": [{ "name": "base", "group": "server", "storage": "local", "priority": 0 }],
    "allInGroups": [],
    "oneOf": [],
    "oneInGroups": [],
    "onTemplatePasteOverridePresentFiles": false
  },
  "fileModifications": ["server.properties"],
  "properties": {}
}

✦

tip

The name in the path is the authoritative key. Keep the name field in the body in sync with the path segment to avoid confusion when listing.

Delete a configuration

DELETE /api/configurations/{name}

Removes the configuration from the cluster. Returns 204 No Content. Existing instances already deployed from the configuration are not affected by deletion.

curl -X DELETE http://<master>:7000/api/configurations/lobby \
  -H "Authorization: Bearer YOUR_TOKEN"

Instances API

Deploy instances from these configurations and control their lifecycle.

Templates API

Manage the template trees referenced by templateInstallationConfig.

API overview

Base URL, response conventions, and status codes.

The Configuration object

List configurations

Get a configuration

Create or update a configuration

Delete a configuration

Related