How to check Elasticsearch cluster formation

Cluster formation checks confirm that all expected Elasticsearch nodes have discovered each other, converged on a single cluster state, and elected a master-eligible node. Early validation reduces the risk of indexing data into an unintended single-node cluster or multiple isolated clusters caused by discovery misconfiguration.

Elasticsearch forms a cluster through node discovery and master election, then publishes a shared cluster state that includes the cluster UUID and the elected master node ID. The HTTP API exposes these formation signals through endpoints such as /_cluster/health, /_cat/nodes, /_cat/master, and filtered /_cluster/state responses.

TLS and authentication are commonly enabled on the HTTP layer in recent Elasticsearch versions, making https, --cacert, and credentials or API keys required for API calls. Health colors (green/yellow/red) indicate shard allocation, so joined node count and a single elected master are the primary indicators when confirming formation, and the HTTP endpoint should remain restricted to trusted networks.

1. Check cluster health to confirm cluster name, joined node count, and timeout state.

   $ curl -sS "http://localhost:9200/_cluster/health?pretty"
   {
     "cluster_name" : "search-cluster",
     "status" : "green",
     "timed_out" : false,
     "number_of_nodes" : 3,
     "number_of_data_nodes" : 3,
     "active_primary_shards" : 0,
     "active_shards" : 0,
     "unassigned_shards" : 0
   }

   Cluster formation is primarily shown by number_of_nodes and timed_out, while status reflects shard allocation.

   Package installs commonly provide the HTTP CA at /etc/elasticsearch/certs/http_ca.crt, while tar installs typically use ES_HOME/config/certs/http_ca.crt; plain-HTTP clusters can omit --cacert and --user.

   Passwords supplied as --user user:password may leak into shell history and process listings; prefer --user elastic to prompt for the password, and avoid --insecure (-k) unless diagnosing certificate problems.

2. Wait for an expected node count during cluster bring-up or automation.

   $ curl -sS "http://localhost:9200/_cluster/health?wait_for_nodes=3&timeout=60s&pretty"
   {
     "cluster_name" : "search-cluster",
     "status" : "green",
     "timed_out" : false,
     "number_of_nodes" : 3,
     "number_of_data_nodes" : 3
   }

   timed_out set to true indicates discovery did not reach the expected node count within the timeout.

3. List nodes in the cluster to review the master marker.

   $ curl -sS "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.40           62          69  25    4.26    2.64     2.00 cdfhilmrstw -      node-01
   192.0.2.41           35          69  17    4.26    2.64     2.00 cdfhilmrstw *      node-02
   192.0.2.42           49          69   6    4.26    2.64     2.00 cdfhilmrstw -      node-03

   A single * in the master column indicates the current master-eligible node, and node.role is a compact role list.

4. Identify the elected master node by node ID.

   $ curl -sS "http://localhost:9200/_cat/master?v"
   id                     host        ip         node
   aQOkC_DIRv-a37tZ0MupXA 192.0.2.41 192.0.2.41 node-02

   HTTP 503 responses containing master_not_discovered_exception indicate that master election has not completed.

5. Retrieve master node ID plus cluster UUID from cluster state.

   $ curl -sS "http://localhost:9200/_cluster/state/master_node,metadata?filter_path=master_node,metadata.cluster_uuid&pretty"
   {
     "master_node" : "aQOkC_DIRv-a37tZ0MupXA",
     "metadata" : {
       "cluster_uuid" : "LsHpAGoQTMGbRvDfTIuG_w"
     }
   }

   Run the same query against multiple node HTTP endpoints when troubleshooting, and verify that master_node and cluster_uuid match across all nodes.