github.com/Aestek/consul@v1.2.4-0.20190309222502-b2c31e33971a/website/source/docs/guides/bootstrapping.html.md (about)

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