github.com/smintz/nomad@v0.8.3/website/source/guides/cluster/automatic.html.md (about)

     1  ---
     2  layout: "guides"
     3  page_title: "Automatically Bootstrapping a Nomad Cluster"
     4  sidebar_current: "guides-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  data_dir = "/etc/nomad.d"
    42  
    43  server {
    44    enabled          = true
    45    bootstrap_expect = 3
    46  }
    47  ```
    48  
    49  This configuration would be saved to disk and then run:
    50  
    51  ```shell
    52  $ nomad agent -config=/etc/nomad.d/server.hcl
    53  ```
    54  
    55  A similar configuration is available for Nomad clients:
    56  
    57  ```hcl
    58  # /etc/nomad.d/client.hcl
    59  
    60  datacenter = "dc1"
    61  data_dir   = "/etc/nomad.d"
    62  
    63  client {
    64    enabled = true
    65  }
    66  ```
    67  
    68  The agent is started in a similar manner:
    69  
    70  ```shell
    71  $ nomad agent -config=/etc/nomad.d/client.hcl
    72  ```
    73  
    74  As you can see, the above configurations include no IP or DNS addresses between
    75  the clients and servers. This is because Nomad detected the existence of Consul
    76  and utilized service discovery to form the cluster.
    77  
    78  ## Internals
    79  
    80  ~> This section discusses the internals of the Consul and Nomad integration at a
    81  very high level. Reading is only recommended for those curious to the
    82  implementation.
    83  
    84  As discussed in the previous section, Nomad merges multiple configuration files
    85  together, so the `-config` may be specified more than once:
    86  
    87  ```shell
    88  $ nomad agent -config=base.hcl -config=server.hcl
    89  ```
    90  
    91  In addition to merging configuration on the command line, Nomad also maintains
    92  its own internal configurations (called "default configs") which include sane
    93  base defaults. One of those default configurations includes a "consul" block,
    94  which specifies sane defaults for connecting to and integrating with Consul. In
    95  essence, this configuration file resembles the following:
    96  
    97  ```hcl
    98  # You do not need to add this to your configuration file. This is an example
    99  # that is part of Nomad's internal default configuration for Consul integration.
   100  consul {
   101    # The address to the Consul agent.
   102    address = "127.0.0.1:8500"
   103  
   104    # The service name to register the server and client with Consul.
   105    server_service_name = "nomad"
   106    client_service_name = "nomad-client"
   107  
   108    # Enables automatically registering the services.
   109    auto_advertise = true
   110  
   111    # Enabling the server and client to bootstrap using Consul.
   112    server_auto_join = true
   113    client_auto_join = true
   114  }
   115  ```
   116  
   117  Please refer to the [Consul
   118  documentation](/docs/agent/configuration/consul.html) for the complete set of
   119  configuration options.