How to configure Elasticsearch node roles

Configuring node roles keeps responsibilities explicit and predictable in a growing Elasticsearch cluster, improving stability and resource usage. Separating master elections, data storage, and ingest processing helps avoid bottlenecks and reduces the risk of overloaded nodes affecting availability.

A node advertises its capabilities at startup based on the node.roles setting in /etc/elasticsearch/elasticsearch.yml. The cluster uses these advertised roles to decide where shards may be allocated, which nodes can participate in master elections, and which nodes can run features such as ingest pipelines, transforms, and machine learning.

Role changes apply only after a node restart and can trigger shard relocation or task rebalancing. Removing roles without keeping sufficient master-eligible nodes for quorum, or sufficient data-capable nodes to hold shards, can make the cluster unstable or unable to allocate data. Clusters with TLS and authentication enabled require authenticated API requests (and, when applicable, a trusted CA) to query role information.

1. Record the current role flags advertised by cluster nodes.

   $ curl -s "http://localhost:9200/_cat/nodes?v&h=name,roles"
   name roles
   es-1 cdfhilm
   es-2 dim
   es-3 hm

   Clusters secured with TLS/authentication commonly require https:// endpoints and credentials for API access.

2. Edit /etc/elasticsearch/elasticsearch.yml to define the node.roles list for the node.

   node.roles: [ master, data, ingest ]

   Common role sets include node.roles: [ master ] for a dedicated master-eligible node, node.roles: [ ingest ] for an ingest-only node, and node.roles: [ ] for a coordinating-only node.

   Removing data roles from a node that previously stored shards can trigger shard relocation and may prevent startup until leftover shard data is removed (for example via elasticsearch-node repurpose) or relocated off the node.

3. Restart the Elasticsearch service to apply role changes.

   $ sudo systemctl restart elasticsearch

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

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

   $ sudo systemctl status elasticsearch --no-pager
   ● elasticsearch.service - Elasticsearch
        Loaded: loaded (/lib/systemd/system/elasticsearch.service; enabled; vendor preset: enabled)
        Active: active (running) since Mon 2026-01-02 09:14:22 UTC; 8s ago
          Docs: https://www.elastic.co
      Main PID: 2174 (java)
         Tasks: 83 (limit: 4670)
        Memory: 1.6G
           CPU: 6.912s
   ##### snipped #####

5. Confirm the node reports the intended roles through the node info API.

   $ curl -s "http://localhost:9200/_nodes/_local?filter_path=nodes.*.name,nodes.*.roles&pretty"
   {
     "nodes" : {
       "mR3k2GqkQv2q9mZ8o1a3bA" : {
         "name" : "es-2",
         "roles" : [ "master", "data", "ingest" ]
       }
     }
   }

   The _cat/nodes roles column is a condensed flag string; the node info API returns explicit role names.

6. Check cluster health for relocations after the role change.

   $ curl -s "http://localhost:9200/_cluster/health?pretty"
   {
     "cluster_name" : "es-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
   }