The cluster.name setting controls the logical name of an Elasticsearch cluster, and Elasticsearch uses it as a hard gate during node discovery: a node will only join a cluster whose name matches the value in its own elasticsearch.yml. The default value is elasticsearch. Change it on every node before first start in any environment beyond a laptop, because production clusters that keep the default are routinely confused with neighbours on the same network.
Definition
cluster.name is a static, node-level setting defined in elasticsearch.yml (or via the ES_JAVA_OPTS/environment variables). Every master-eligible and data node in the same cluster must use the exact same value; a single mismatched node will fail to join and log cluster name doesn't match during bootstrap. The setting is case-sensitive: Production and production are different clusters.
Default and Allowed Values
| Property | Value |
|---|---|
| Default | elasticsearch |
| Type | String, static (requires node restart to change) |
| Scope | Node-level (in elasticsearch.yml) |
| Valid characters | Alphanumerics, hyphens, underscores. Avoid spaces, dots, and shell metacharacters |
| Recommended length | 4-30 characters, descriptive |
How to Set It
In elasticsearch.yml, before the node starts for the first time:
# Identifies which cluster this node belongs to
cluster.name: prod-logs-eu-west-1
You can also pass it on the command line for tests:
bin/elasticsearch -E cluster.name=prod-logs-eu-west-1
Verify the running value via the cluster health API:
GET /_cluster/health
The response includes "cluster_name": "prod-logs-eu-west-1". The _cat/health endpoint surfaces the same value in column form.
Changing the Name on an Existing Cluster
Renaming a live cluster is not a hot operation. Elasticsearch persists the cluster name into the cluster state on disk; if you change the configured value on a running cluster, nodes will refuse to load the existing data path on restart and you risk a forced reformat of the data directory.
The supported path is:
- Take a snapshot of all relevant indices.
- Stop all nodes.
- Edit
cluster.nameon every node. - Wipe or relocate the data path so nodes bootstrap fresh.
- Restart nodes and restore from snapshot.
If your goal is just a friendlier display name, prefer leaving cluster.name alone and using monitoring metadata, index aliases, or a cluster-wide tag for human-facing identification.
Operational Impact
cluster.name participates in three places:
- Discovery: combined with
discovery.seed_hoststo filter which peers a node will form a quorum with. A mismatch is a silent partition - the node simply never appears in the cluster state. - Cross-cluster operations: cross-cluster search and cross-cluster replication reference clusters by name, so changing the name breaks any remote-cluster aliases that point at it.
- Monitoring and logs: Beats, Logstash, and Kibana use
cluster_nameas the primary key in monitoring indices. Renaming splits historical metrics from new ones.
Common Mistakes
- Leaving the default in production. Two clusters on the same broadcast domain both called
elasticsearchwill discover each other if seed hosts overlap, leading to nodes joining the wrong cluster on restart. - Inconsistent case across nodes.
Prodon one node andprodon another results in two single-node clusters instead of a quorum. - Embedding sensitive metadata. The name is sent in plaintext during ping. Do not encode customer identifiers or compliance tags in it.
- Renaming live. As above, this corrupts the persisted cluster state. Always snapshot first.
Frequently Asked Questions
Q: What is the default value of cluster.name in Elasticsearch?
A: The default cluster.name is elasticsearch. This default is safe for a single-node laptop install but never appropriate in production, because any other node on the network using the same default could attempt to join.
Q: Can I change cluster.name on a running Elasticsearch cluster?
A: No, not safely. The cluster name is persisted into the on-disk cluster state. Changing it on a running cluster requires stopping all nodes, taking a snapshot, wiping data paths, restarting with the new name, and restoring from snapshot.
Q: Is cluster.name case-sensitive?
A: Yes. MyCluster and mycluster are treated as different cluster names. All nodes must use byte-identical values or they will refuse to join each other.
Q: How does cluster.name interact with discovery.seed_hosts?
A: Discovery uses discovery.seed_hosts to find candidate peers, then filters those candidates by cluster.name. Both must match for a node to join. A correct seed host with a wrong cluster name results in a silent discovery failure.
Q: Should dev, staging, and production share a cluster.name?
A: No. Use distinct names per environment (logs-dev, logs-staging, logs-prod). Sharing names risks accidental cross-environment joins if seed hosts ever overlap, and it makes monitoring dashboards ambiguous.
Q: Where is the running cluster name visible?
A: It appears in GET / and GET /_cluster/health, in every node's startup logs, in Kibana's cluster picker, and as the cluster_name field in the monitoring indices that Beats and Metricbeat ship.
