Get Region Settings #

Returns the settings configured for the region.

Requests #

GET /_cluster/_region/<region_id>/settings

Path Parameters #

region_id
(Required, String) The UUID of the region you want to query. A special ID _local can be specified to query the state of the region that handles this request.

Query Parameters #

include_defaults
(Optional, Boolean) If true, returns all default region settings. Defaults to false.
flat_settings
(Optional, Boolean) If true, returns settings in flat format. Defaults to false.

Response #

The response carries three maps — defaults (present with include_defaults=true), persistent and transient. The effective value of a setting is transient > persistent > default.

Update Region Settings #

Updates the region’s settings at runtime.

Requests #

PUT /_cluster/_region/<region_id>/settings

Path Parameters #

region_id
(Required, String) The UUID of the region you want to update. A special ID _local can be specified to update the region that handles this request.

Query Parameters #

flat_settings
(Optional, Boolean) If true, returns settings in flat format. Defaults to false.

Request body #

The region settings you want to update:

{
  "persistent": {
    ...
  },
  "transient": {
    ...
  }
}

persistent
(Optional, Object) Values stored in the Raft-replicated region metadata — they survive restarts and replicate to every node in the region.
transient
(Optional, Object) Values kept in memory only — cleared on the next restart; they shadow persistent while present.

Unknown setting names and values of the wrong type are rejected. Keys whose category is static are rejected at runtime — set them in the yml’s region: section before start instead.

Dynamic settings apply without restart: the leader’s allocation service re-reads them on every pass.

Settings catalog #

Setting	Default	Category	Description
`cluster.routing.allocation.enable`	`1`	dynamic	`1` = allocate unassigned shards (e.g. replicas that lost their node), `0` = allocate nothing new.
`cluster.routing.rebalance.enable`	`1`	dynamic	`1` = relocate shards between nodes when per-node shard counts drift apart, `0` = never rebalance.
`cluster.routing.allocation.concurrent_tasks`	`2`	dynamic	Maximum number of concurrently in-flight allocation/relocation tasks across the region.
`cluster.routing.allocation.node_concurrent_recoveries`	`2`	dynamic	Maximum number of concurrent incoming allocation/relocation tasks per target node (paces the recovery traffic on a single node).
`cluster.routing.allocation.balance_threshold`	`1`	dynamic	Rebalance kicks in when (max node load − min node load) exceeds this number of shards.
`region.fault_detection.follower_check.interval`	`50`	static	Heartbeat interval between the leader and its followers, in milliseconds.
`region.fault_detection.follower_check.threshold`	`5000`	static	A follower whose last acknowledged heartbeat is older than this (milliseconds) is considered faulty and removed from the cluster.

Examples #

# pause all shard allocation and rebalancing, until the next restart
curl -X PUT http://127.0.0.1:28000/_cluster/_region/_local/settings \
  -H 'Content-Type: application/json' \
  -d '{"transient": {"cluster.routing.allocation.enable": 0, "cluster.routing.rebalance.enable": 0}}'

# make the rebalance-dampening persistent across restarts
curl -X PUT http://127.0.0.1:28000/_cluster/_region/_local/settings \
  -H 'Content-Type: application/json' \
  -d '{"persistent": {"cluster.routing.allocation.balance_threshold": 2}}'

The equivalent persistent values can also be provided in pizza.yml — but only for settings whose registry name starts with region. (currently the region.fault_detection.* pair; the shipped example config sets interval: 70). The cluster.routing.* settings are persistent via the API only — a cluster.routing block under the yml region: section is silently ignored:

region:
  name: pizza_region
  fault_detection:
    follower_check:
      interval: 70
      threshold: 5000