elasticsearch/docs/reference/modules/discovery/bootstrapping.asciidoc

[[modules-discovery-bootstrap-cluster]]
=== Bootstrapping a cluster

Starting an Elasticsearch cluster for the very first time requires the initial
set of <<master-node,master-eligible nodes>> to be explicitly defined on one or
more of the master-eligible nodes in the cluster. This is known as _cluster
bootstrapping_. This is only required the first time a cluster starts up: nodes
that have already joined a cluster store this information in their data folder
for use in a <<restart-upgrade,full cluster restart>>, and freshly-started nodes
that are joining a running cluster obtain this information from the cluster's
elected master.

The initial set of master-eligible nodes is defined in the
<<initial_master_nodes,`cluster.initial_master_nodes` setting>>. This should be
set to a list containing one of the following items for each master-eligible
node:

- The <<node-name,node name>> of the node.
- The node's hostname if `node.name` is not set, because `node.name` defaults
  to the node's hostname. You must use either the fully-qualified hostname or
  the bare hostname <<modules-discovery-bootstrap-cluster-fqdns,depending on
  your system configuration>>.
- The IP address of the node's <<modules-network-binding-publishing,transport
  publish address>>, if it is not possible to use the `node.name` of the node.
  This is normally the IP address to which
  <<common-network-settings,`network.host`>> resolves but
  <<advanced-network-settings,this can be overridden>>.
- The IP address and port of the node's publish address, in the form `IP:PORT`,
  if it is not possible to use the `node.name` of the node and there are
  multiple nodes sharing a single IP address.

When you start a master-eligible node, you can provide this setting on the
command line or in the `elasticsearch.yml` file. After the cluster has formed,
remove this setting from each node's configuration. It should not be set for
master-ineligible nodes, master-eligible nodes joining an existing cluster, or
when restarting one or more nodes.

It is technically sufficient to set `cluster.initial_master_nodes` on a single
master-eligible node in the cluster, and only to mention that single node in the
setting's value, but this provides no fault tolerance before the cluster has
fully formed. It is therefore better to bootstrap using at least three
master-eligible nodes, each with a `cluster.initial_master_nodes` setting
containing all three nodes.

WARNING: You must set `cluster.initial_master_nodes` to the same list of nodes
on each node on which it is set in order to be sure that only a single cluster
forms during bootstrapping and therefore to avoid the risk of data loss.

For a cluster with 3 master-eligible nodes (with <<node-name,node names>>
`master-a`, `master-b` and `master-c`) the configuration will look as follows:

[source,yaml]
--------------------------------------------------
cluster.initial_master_nodes:
  - master-a
  - master-b
  - master-c
--------------------------------------------------

Like all node settings, it is also possible to specify the initial set of master
nodes on the command-line that is used to start Elasticsearch:

[source,bash]
--------------------------------------------------
bin/elasticsearch -E cluster.initial_master_nodes=master-a,master-b,master-c
--------------------------------------------------

[[modules-discovery-bootstrap-cluster-fqdns]]
.Node name formats must match
****
The node names used in the
`cluster.initial_master_nodes` list must exactly match the `node.name`
properties of the nodes. By default the node name is set to the machine's
hostname which may or may not be fully-qualified depending on your system
configuration. If each node name is a fully-qualified domain name such as
`master-a.example.com` then you must use fully-qualified domain names in the
`cluster.initial_master_nodes` list too; conversely if your node names are bare
hostnames (without the `.example.com` suffix) then you must use bare hostnames
in the `cluster.initial_master_nodes` list. If you use a mix of fully-qualified
and bare hostnames, or there is some other mismatch between `node.name` and
`cluster.initial_master_nodes`, then the cluster will not form successfully and
you will see log messages like the following.

[source,text]
--------------------------------------------------
[master-a.example.com] master not discovered yet, this node has
not previously joined a bootstrapped (v7+) cluster, and this
node must discover master-eligible nodes [master-a, master-b] to
bootstrap a cluster: have discovered [{master-b.example.com}{...
--------------------------------------------------

This message shows the node names `master-a.example.com` and
`master-b.example.com` as well as the `cluster.initial_master_nodes` entries
`master-a` and `master-b`, and it is clear from this message that they do not
match exactly.

****

[[bootstrap-cluster-name]]
==== Choosing a cluster name

The <<cluster-name,`cluster.name`>> setting enables you to create multiple
clusters which are separated from each other. Nodes verify that they agree on
their cluster name when they first connect to each other, and Elasticsearch
will only form a cluster from nodes that all have the same cluster name. The
default value for the cluster name is `elasticsearch`, but it is recommended to
change this to reflect the logical name of the cluster.

[[bootstrap-auto-bootstrap]]
==== Auto-bootstrapping in development mode

By default each node will automatically bootstrap itself into a single-node
cluster the first time it starts. If any of the following settings are
configured then auto-bootstrapping will not take place:

* `discovery.seed_providers`
* `discovery.seed_hosts`
* `cluster.initial_master_nodes`

To add a new node into an existing cluster, configure `discovery.seed_hosts` or
other relevant discovery settings so that the new node can discover the
existing master-eligible nodes in the cluster. To bootstrap a new multi-node
cluster, configure `cluster.initial_master_nodes` as described in the
<<modules-discovery-bootstrap-cluster,section on cluster bootstrapping>> as
well as `discovery.seed_hosts` or other relevant discovery settings.

[[modules-discovery-bootstrap-cluster-joining]]
.Forming a single cluster
****
Once an {es} node has joined an existing cluster, or bootstrapped a new
cluster, it will not join a different cluster. {es} will not merge separate
clusters together after they have formed, even if you subsequently try and
configure all the nodes into a single cluster. This is because there is no way
to merge these separate clusters together without a risk of data loss. You can
tell that you have formed separate clusters by checking the cluster UUID
reported by `GET /` on each node.

If you intended to add a node into an existing cluster but instead bootstrapped
a separate single-node cluster then you must start again:

. Shut down the node.

. Completely wipe the node by deleting the contents of its <<data-path,data
folder>>.

. Configure `discovery.seed_hosts` or `discovery.seed_providers` and other
relevant discovery settings.

. Restart the node and verify that it joins the existing cluster rather than
forming its own one-node cluster.

If you intended to form a new multi-node cluster but instead bootstrapped a
collection of single-node clusters then you must start again:

. Shut down all the nodes.

. Completely wipe each node by deleting the contents of their <<data-path,data
folders>>.

. Configure `cluster.initial_master_nodes` as described above.

. Configure `discovery.seed_hosts` or `discovery.seed_providers` and other
relevant discovery settings.

. Restart all the nodes and verify that they have formed a single cluster.

****