How to configure master-eligible nodes in Elasticsearch

Master-eligible nodes keep cluster coordination stable by handling elections and publishing cluster state, so separating this role reduces the chance of coordination problems during heavy indexing, shard recovery, or query spikes.

Elasticsearch assigns master eligibility through node.roles in /etc/elasticsearch/elasticsearch.yml. Nodes with the master role participate in elections and cluster-state publishing, while other roles (such as data and ingest) handle indexing and search workloads.

Dedicated master-eligible nodes are commonly deployed as a small odd-sized set (3 or 5) to preserve quorum during failures. Changing roles on an existing node can trigger shard relocation when data roles are removed, and role changes require a restart to take effect. HTTP API verification commands may require https and authentication when security is enabled, and client traffic is typically directed to data or coordinating nodes instead of dedicated masters.

1. List node names with current role letters from the cluster.

   $ curl -s "http://localhost:9200/_cat/nodes?v"
   ip         heap.percent ram.percent cpu load_1m load_5m load_15m node.role master name
   192.0.2.11           19          67  11    0.29    0.34     0.39 cdfhilmrstw -      es-data-1
   192.0.2.12           23          71  14    0.41    0.38     0.36 cdfhilmrstw *      es-data-2
   192.0.2.13           12          55   6    0.18    0.20     0.22 cdfhilmrstw -      es-master-1

   The node.role column uses letters such as m for master-eligible nodes.

2. Set node.roles to only master in /etc/elasticsearch/elasticsearch.yml on a dedicated master-eligible node.

   node.roles: [ master ]

   Setting node.roles overrides the default role set for the node.

3. Restart Elasticsearch on the node to apply the role change.

   $ sudo systemctl restart elasticsearch

   Restarting temporarily removes the node from the cluster, and repurposing a former data node can trigger shard relocation until rebalancing completes.

   Related: How to manage the Elasticsearch service with systemctl in Linux

4. Confirm the Elasticsearch service is active after the restart.

   $ sudo systemctl status elasticsearch --no-pager -l
   ● elasticsearch.service - Elasticsearch
        Loaded: loaded (/lib/systemd/system/elasticsearch.service; enabled; vendor preset: enabled)
        Active: active (running) since Fri 2026-01-02 09:41:12 UTC; 8s ago
          Docs: https://www.elastic.co
      Main PID: 2387 (java)
         Tasks: 96 (limit: 19135)
        Memory: 2.1G
           CPU: 12.345s
        CGroup: /system.slice/elasticsearch.service
                ├─2387 /usr/share/elasticsearch/jdk/bin/java ##### snipped #####

5. Verify the node reports only the master role through the Nodes API.

   $ curl -s "http://localhost:9200/_nodes/es-master-1?filter_path=nodes.*.roles&pretty"
   {
     "nodes" : {
       "gZrM2gXvQjS8Kp0wTQxHvw" : {
         "roles" : [ "master" ]
       }
     }
   }

   Secured clusters commonly require an https endpoint, a trusted CA certificate, and credentials or an API key for curl.

6. Verify the current master node from the cluster.

   $ curl -s "http://localhost:9200/_cat/master?v"
   id                     host       ip         node
   gZrM2gXvQjS8Kp0wTQxHvw 192.0.2.13 192.0.2.13 es-master-1

7. Check cluster health after the role change.

   $ curl -s "http://localhost:9200/_cluster/health?pretty"
   {
     "cluster_name" : "search-cluster",
     "status" : "green",
     "timed_out" : false,
     "number_of_nodes" : 3,
     "number_of_data_nodes" : 2,
     "active_primary_shards" : 24,
     "active_shards" : 48,
     "relocating_shards" : 0,
     "initializing_shards" : 0,
     "unassigned_shards" : 0,
     "delayed_unassigned_shards" : 0,
     "number_of_pending_tasks" : 0,
     "number_of_in_flight_fetch" : 0,
     "task_max_waiting_in_queue_millis" : 0,
     "active_shards_percent_as_number" : 100.0
   }