How to check Elasticsearch cluster formation

Checking cluster formation confirms that the expected Elasticsearch nodes have discovered each other, committed the same cluster UUID, and agreed on one elected master. Early validation prevents accidental writes into an isolated single-node cluster or a split cluster caused by bad discovery settings.

Self-managed Elasticsearch forms a cluster over the transport layer on port 9300. The discovery process uses discovery.seed_hosts to find master-eligible peers, the first bootstrap uses cluster.initial_master_nodes to commit the initial voting configuration, and the HTTP APIs on port 9200 expose whether the nodes joined the same cluster state.

Recent Elasticsearch releases commonly secure the HTTP layer with HTTPS and authentication, so the documented requests should follow the normal authenticated HTTPS path used by operators. The cluster.initial_master_nodes setting is only for brand-new clusters and should be removed after the cluster forms, while every discovery.seed_hosts entry must resolve to a reachable transport endpoint or formation can stall with master not discovered warnings.

1. Query cluster health and wait for the expected node count.

   $ curl -sS "http://localhost:9200/_cluster/health?wait_for_nodes=>=3&timeout=60s&filter_path=cluster_name,status,timed_out,number_of_nodes,number_of_data_nodes,active_primary_shards,active_shards,unassigned_shards&pretty"
   {
     "cluster_name" : "formation-lab",
     "status" : "green",
     "timed_out" : false,
     "number_of_nodes" : 3,
     "number_of_data_nodes" : 3,
     "active_primary_shards" : 0,
     "active_shards" : 0,
     "unassigned_shards" : 0
   }

   number_of_nodes and timed_out confirm formation more directly than the health color. The wait_for_nodes parameter accepts operators such as >=3, which is useful during bootstrap or automation.

   Secured clusters typically use https://host:9200// with a CA file and authentication, for example curl -u elastic "https://localhost:9200/..." or an API key header.</WRAP>

   Related: How to monitor Elasticsearch cluster health

   - Query the root endpoint on each node and confirm that every response shows the same cluster UUID. <code>$ for host in es01 es02 es03; do > curl -sS “http:${host}:9200/?filter_path=name,cluster_name,cluster_uuid&pretty”

   done

   {

   "name" : "es01",
   "cluster_name" : "formation-lab",
   "cluster_uuid" : "Nvqx8m75TBqQjSZmgsrF9w"

   } {

   "name" : "es02",
   "cluster_name" : "formation-lab",
   "cluster_uuid" : "Nvqx8m75TBqQjSZmgsrF9w"

   } {

   "name" : "es03",
   "cluster_name" : "formation-lab",
   "cluster_uuid" : "Nvqx8m75TBqQjSZmgsrF9w"

   }</code>

   Use each node's reachable HTTP name or IP. Matching cluster_uuid values across every node confirm that the nodes joined the same cluster, not separate bootstrapped islands.

   Different cluster_uuid values usually mean the nodes did not form one cluster. Recheck discovery.seed_hosts reachability and the one-time bootstrap configuration before indexing data.

   Related: How to set Elasticsearch discovery seed hosts

   1. List all joined nodes and confirm there is exactly one master marker.

      $ curl -sS "http://localhost:9200/_cat/nodes?v&s=name&h=ip,node.role,master,name"
      ip         node.role   master name
      192.0.2.40 cdfhilmrstw *      es01
      192.0.2.41 cdfhilmrstw -      es02
      192.0.2.42 cdfhilmrstw -      es03

      The master column must show one * and the rest - . The compact node.role string still includes m on master-eligible nodes.

   2. Identify the elected master node explicitly.

      $ curl -sS "http://localhost:9200/_cat/master?v&h=id,host,ip,node"
      id                     host       ip         node
      jK1qYIBqStW7dr0hDOCHiw 192.0.2.40 192.0.2.40 es01

      The _cat/master response is the quickest confirmation of which node currently owns cluster coordination.

      If the request returns 503 or the node field is empty, master election has not completed yet or the cluster is flapping.

      Related: How to identify the elected master node in Elasticsearch

   3. Check the master stability indicator on Elasticsearch 8.7 and later.

      $ curl -sS "http://localhost:9200/_health_report/master_is_stable?verbose=false&filter_path=cluster_name,indicators.master_is_stable.status,indicators.master_is_stable.symptom&pretty"
      {
        "cluster_name" : "formation-lab",
        "indicators" : {
          "master_is_stable" : {
            "status" : "green",
            "symptom" : "The cluster has a stable master node"
          }
        }
      }

      Use verbose=false when polling this endpoint repeatedly. A non-green result means the cluster formed recently or is still experiencing master changes that need investigation.

      Related: How to monitor Elasticsearch cluster health