How to set the Elasticsearch cluster name

A distinctive Elasticsearch cluster name prevents nodes from drifting into the wrong cluster and keeps environments like development, staging, and production cleanly separated. Clear naming also simplifies monitoring, alert routing, and log triage when multiple clusters share the same network.

Elasticsearch uses the cluster.name setting during discovery and node-to-node handshakes. Every node that should belong to the same cluster must advertise the same value in /etc/elasticsearch/elasticsearch.yml, and clients can confirm it from the REST API.

Changing cluster.name is a coordinated, cluster-wide operation because nodes with mismatched names will not join each other. Plan for interruption during the restart window and avoid applying the new name on only part of a running cluster.

1. Create a backup copy of the Elasticsearch configuration file.

   $ sudo cp -a /etc/elasticsearch/elasticsearch.yml /etc/elasticsearch/elasticsearch.yml.bak

2. Open the Elasticsearch configuration file in a text editor.

   $ sudo nano /etc/elasticsearch/elasticsearch.yml

3. Add or update the cluster.name setting.

   cluster.name: search-cluster

   Use an environment-specific value such as logs-prod to avoid accidental cross-environment joins.

4. Apply the same cluster.name value in /etc/elasticsearch/elasticsearch.yml on every node in the cluster.

   Nodes only form a cluster when cluster.name matches across all participating nodes.

5. Restart the Elasticsearch service on every node to apply the new setting.

   $ sudo systemctl restart elasticsearch

   A node restarted with a different cluster.name than the running cluster stays isolated until all nodes are updated.

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

6. Verify the cluster reports the new name.

   $ curl -sS --cacert /etc/elasticsearch/certs/http-ca.crt -u elastic "https://localhost:9200/_cluster/health?pretty&filter_path=cluster_name,status,number_of_nodes,number_of_data_nodes"
   Enter host password for user 'elastic':
   {
     "cluster_name" : "search-cluster",
     "status" : "green",
     "number_of_nodes" : 1,
     "number_of_data_nodes" : 1
   }

   If the HTTP endpoint requires TLS or authentication, switch to https and add the required curl options.