github.com/maier/nomad@v0.4.1-0.20161110003312-a9e3d0b8549d/website/source/docs/cluster/automatic.html.md (about)

     1  ---
     2  layout: "docs"
     3  page_title: "Automatically Bootstrapping a Nomad Cluster"
     4  sidebar_current: "docs-cluster-automatic"
     5  description: |-
     6    Learn how to automatically bootstrap a Nomad cluster using Consul. By having
     7    a Consul agent installed on each host, Nomad can automatically discover other
     8    clients and servers to bootstrap the cluster without operator involvement.
     9  ---
    10  
    11  # Automatic Bootstrapping
    12  
    13  To automatically bootstrap a Nomad cluster, we must leverage another HashiCorp
    14  open source tool, [Consul](https://www.consul.io/). Bootstrapping Nomad is
    15  easiest against an existing Consul cluster. The Nomad servers and clients
    16  will become informed of each other's existence when the Consul agent is
    17  installed and configured on each host. As an added benefit, integrating Consul
    18  with Nomad provides service and health check registration for applications which
    19  later run under Nomad.
    20  
    21  Consul models infrastructures as datacenters and multiple Consul datacenters can
    22  be connected over the WAN so that clients can discover nodes in other
    23  datacenters. Since Nomad regions can encapsulate many datacenters, we recommend
    24  running a Consul cluster in every Nomad datacenter and connecting them over the
    25  WAN. Please refer to the Consul guide for both
    26  [bootstrapping](https://www.consul.io/docs/guides/bootstrapping.html) a single
    27  datacenter and [connecting multiple Consul clusters over the
    28  WAN](https://www.consul.io/docs/guides/datacenters.html).
    29  
    30  If a Consul agent is installed on the host prior to Nomad starting, the Nomad
    31  agent will register with Consul and discover other nodes.
    32  
    33  For servers, we must inform the cluster how many servers we expect to have. This
    34  is required to form the initial quorum, since Nomad is unaware of how many peers
    35  to expect. For example, to form a region with three Nomad servers, you would use
    36  the following Nomad configuration file:
    37  
    38  ```hcl
    39  # /etc/nomad.d/server.hcl
    40  
    41  server {
    42    enabled          = true
    43    bootstrap_expect = 3
    44  }
    45  ```
    46  
    47  This configuration would be saved to disk and then run:
    48  
    49  ```shell
    50  $ nomad agent -config=/etc/nomad.d/server.hcl
    51  ```
    52  
    53  A similar configuration is available for Nomad clients:
    54  
    55  ```hcl
    56  # /etc/nomad.d/client.hcl
    57  
    58  datacenter = "dc1"
    59  
    60  client {
    61    enabled = true
    62  }
    63  ```
    64  
    65  The agent is started in a similar manner:
    66  
    67  ```shell
    68  $ nomad agent -config=/etc/nomad.d/client.hcl
    69  ```
    70  
    71  As you can see, the above configurations include no IP or DNS addresses between
    72  the clients and servers. This is because Nomad detected the existence of Consul
    73  and utilized service discovery to form the cluster.
    74  
    75  ## Internals
    76  
    77  ~> This section discusses the internals of the Consul and Nomad integration at a
    78  very high level. Reading is only recommended for those curious to the
    79  implementation.
    80  
    81  As discussed in the previous section, Nomad merges multiple configuration files
    82  together, so the `-config` may be specified more than once:
    83  
    84  ```shell
    85  $ nomad agent -config=base.hcl -config=server.hcl
    86  ```
    87  
    88  In addition to merging configuration on the command line, Nomad also maintains
    89  its own internal configurations (called "default configs") which include sane
    90  base defaults. One of those default configurations includes a "consul" block,
    91  which specifies sane defaults for connecting to and integrating with Consul. In
    92  essence, this configuration file resembles the following:
    93  
    94  ```hcl
    95  # You do not need to add this to your configuration file. This is an example
    96  # that is part of Nomad's internal default configuration for Consul integration.
    97  consul {
    98    # The address to the Consul agent.
    99    address = "127.0.0.1:8500"
   100  
   101    # The service name to register the server and client with Consul.
   102    server_service_name = "nomad"
   103    client_service_name = "nomad-client"
   104  
   105    # Enables automatically registering the services.
   106    auto_advertise = true
   107  
   108    # Enabling the server and client to bootstrap using Consul.
   109    server_auto_join = true
   110    client_auto_join = true
   111  }
   112  ```
   113  
   114  Please refer to the [Consul
   115  documentation](/docs/agent/configuration/consul.html) for the complete set of
   116  configuration options.