Bootstrapping a cluster
editBootstrapping a cluster
editStarting an Elasticsearch cluster for the very first time requires the initial set of 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. 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
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 of the node.
-
The node’s hostname if
node.name
is not set, becausenode.name
defaults to the node’s hostname. You must use either the fully-qualified hostname or the bare hostname depending on your system configuration. -
The IP address of the node’s transport
publish address, if it is not possible to use the
node.name
of the node. This is normally the IP address to whichnetwork.host
resolves but 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 thenode.name
of the node and there are multiple nodes sharing a single IP address.
After the cluster has formed, remove the cluster.initial_master_nodes
setting
from each node’s configuration. It should not be set for master-ineligible
nodes, master-eligible nodes joining an existing cluster, or nodes which are
restarting.
If you leave cluster.initial_master_nodes
in place once the cluster has
formed then there is a risk that a future misconfiguration may result in
bootstrapping a new cluster alongside your existing cluster. It may not be
possible to recover from this situation without losing data.
The simplest way to create a new cluster is for you to select one of your
master-eligible nodes that will bootstrap itself into a single-node cluster,
which all the other nodes will then join. This simple approach is not resilient
to failures until the other master-eligible nodes have joined the cluster. For
example, if you have a master-eligible node with node name
master-a
then configure it as follows (omitting
cluster.initial_master_nodes
from the configuration of all other nodes):
cluster.initial_master_nodes: master-a
For fault-tolerant cluster bootstrapping, use all the master-eligible nodes.
For instance, if your cluster has 3 master-eligible nodes with node
names master-a
, master-b
and master-c
then configure them all as
follows:
cluster.initial_master_nodes: - master-a - master-b - master-c
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. If cluster.initial_master_nodes
varies
across the nodes on which it is set then you may bootstrap multiple clusters.
It is usually not possible to recover from this situation without losing data.
Choosing a cluster name
editThe 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.
Auto-bootstrapping in development mode
editBy 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
section on cluster bootstrapping as
well as discovery.seed_hosts
or other relevant discovery settings.