github.com/outbrain/consul@v1.4.5/website/source/docs/install/bootstrapping.html.md (about)

     1  ---
     2  layout: "docs"
     3  page_title: "Bootstrapping a Datacenter"
     4  sidebar_current: "docs-install-bootstrapping"
     5  description: |-
     6    An agent can run in both client and server mode. Server nodes are responsible for running the consensus protocol and storing the cluster state. Before a Consul cluster can begin to service requests, a server node must be elected leader. Thus, the first nodes that are started are generally the server nodes. Bootstrapping is the process of joining these server nodes into a cluster.
     7  ---
     8  
     9  # Bootstrapping a Datacenter
    10  
    11  An agent can run in either client or server mode. Server nodes are responsible for running the
    12  [consensus protocol](/docs/internals/consensus.html) and storing the cluster state.
    13  The client nodes are mostly stateless and rely heavily on the server nodes.
    14  
    15  Before a Consul cluster can begin to service requests, 
    16  a server node must be elected leader. Bootstrapping is the process
    17  of joining these initial server nodes into a cluster. Read the 
    18  [architecture documentation](/docs/internals/architecture.html) to learn more about 
    19  the internals of Consul.
    20  
    21  It is recommended to have three or five total servers per datacenter. A single server deployment is _highly_ discouraged
    22  as data loss is inevitable in a failure scenario. Please refer to the
    23  [deployment table](/docs/internals/consensus.html#deployment-table) for more detail.
    24  
    25  ~> **Note**: In versions of Consul prior to 0.4, bootstrapping was a manual process. For details on using the `-bootstrap` flag directly, see the
    26  [manual bootstrapping guide](/docs/install/manual-bootstrap.html).
    27  Manual bootstrapping with `-bootstrap` is not recommended in 
    28  newer versions of Consul (0.5 and newer) as it is more error-prone. 
    29  Instead you should use automatic bootstrapping
    30  with [`-bootstrap-expect`](/docs/agent/options.html#_bootstrap_expect).
    31  
    32  ## Bootstrapping the Servers
    33  
    34  The recommended way to bootstrap the servers is to use the [`-bootstrap-expect`](/docs/agent/options.html#_bootstrap_expect)
    35  configuration option. This option informs Consul of the expected number of
    36  server nodes and automatically bootstraps when that many servers are available. To prevent
    37  inconsistencies and split-brain (clusters where multiple servers consider
    38  themselves leader) situations, you should either specify the same value for
    39  [`-bootstrap-expect`](/docs/agent/options.html#_bootstrap_expect)
    40  or specify no value at all on all the servers. Only servers that specify a value will attempt to bootstrap the cluster.
    41  
    42  Suppose we are starting a three server cluster. We can start `Node A`, `Node B`, and `Node C` with each
    43  providing the `-bootstrap-expect 3` flag. Once the nodes are started, you should see a warning message in the service output. 
    44  
    45  ```text
    46  [WARN] raft: EnableSingleNode disabled, and no known peers. Aborting election.
    47  ```
    48  
    49  The warning indicates that the nodes are expecting 2 peers but none are known yet. Below you will learn how to connect the servers so that one can be 
    50  elected leader.
    51  
    52  ## Creating the Cluster
    53  
    54  You can trigger leader election by joining the servers together, to create a cluster. You can either configure the nodes to join automatically or manually.
    55  
    56  ### Automatically Join the Servers
    57  
    58  There are multiple options for joining the servers. Choose the method which best suits your environment and specific use case.
    59  
    60  - Specify a list of servers with
    61    [-join](/docs/agent/options.html#_join) and
    62    [start_join](https://www.consul.io/docs/agent/options.html#start_join)
    63    options.
    64  - Specify a list of servers with [-retry-join](https://www.consul.io/docs/agent/options.html#_retry_join) option.
    65  - Use automatic joining by tag for supported cloud environments with the [-retry-join](https://www.consul.io/docs/agent/options.html#_retry_join) option.
    66  
    67  All three methods can be set in the agent configuration file or 
    68  the command line flag. 
    69  
    70  ### Manually Join the Servers
    71  
    72  To manually create a cluster, you should connect to one of the servers
    73  and run the `consul join` command.
    74  
    75  ```
    76  $ consul join <Node A Address> <Node B Address> <Node C Address>
    77  Successfully joined cluster by contacting 3 nodes.
    78  ```
    79  
    80  Since a join operation is symmetric, it does not matter which node initiates it. Once the join is successful, one of the nodes will output something like:
    81  
    82  ```
    83  [INFO] consul: adding server foo (Addr: 127.0.0.2:8300) (DC: dc1)
    84  [INFO] consul: adding server bar (Addr: 127.0.0.1:8300) (DC: dc1)
    85  [INFO] consul: Attempting bootstrap with nodes: [127.0.0.3:8300 127.0.0.2:8300 127.0.0.1:8300]
    86      ...
    87  [INFO] consul: cluster leadership acquired
    88  ```
    89  
    90  ### Verifying the Cluster and Connect the Clients
    91  
    92  As a sanity check, the [`consul info`](/docs/commands/info.html) command
    93  is a useful tool. It can be used to verify the `raft.num_peers` 
    94  and to view the latest log index under `raft.last_log_index`. When
    95  running [`consul info`](/docs/commands/info.html) on the followers, you
    96  should see `raft.last_log_index` converge to the same value once the
    97  leader begins replication. That value represents the last log entry that
    98  has been stored on disk.
    99  
   100  Now that the servers are all started and replicating to each other, you can 
   101  join the clients with the same join method you used for the servers. 
   102  Clients are much easier as they can join against any existing node. All nodes participate in a gossip
   103  protocol to perform basic discovery, so once joined to any member of the
   104  cluster, new clients will automatically find the servers and register
   105  themselves.
   106  
   107  -> **Note:** It is not strictly necessary to start the server nodes before the clients; however, most operations will fail until the servers are available.
   108  
   109  
   110