github.com/smintz/nomad@v0.8.3/website/source/docs/agent/configuration/consul.html.md (about)

     1  ---
     2  layout: "docs"
     3  page_title: "consul Stanza - Agent Configuration"
     4  sidebar_current: "docs-agent-configuration-consul"
     5  description: |-
     6    The "consul" stanza configures the Nomad agent's communication with
     7    Consul for service discovery and key-value integration. When
     8    configured, tasks can register themselves with Consul, and the Nomad cluster
     9    can automatically bootstrap itself.
    10  ---
    11  
    12  # `consul` Stanza
    13  
    14  <table class="table table-bordered table-striped">
    15    <tr>
    16      <th width="120">Placement</th>
    17      <td>
    18        <code>**consul**</code>
    19      </td>
    20    </tr>
    21  </table>
    22  
    23  
    24  The `consul` stanza configures the Nomad agent's communication with
    25  [Consul][consul] for service discovery and key-value integration. When
    26  configured, tasks can register themselves with Consul, and the Nomad cluster can
    27  [automatically bootstrap][bootstrap] itself.
    28  
    29  ```hcl
    30  consul {
    31    address = "127.0.0.1:8500"
    32    auth    = "admin:password"
    33    token   = "abcd1234"
    34  }
    35  ```
    36  
    37  A default `consul` stanza is automatically merged with all Nomad agent
    38  configurations. These sane defaults automatically enable Consul integration if
    39  Consul is detected on the system. This allows for seamless bootstrapping of the
    40  cluster with zero configuration. To put it another way: if you have a Consul
    41  agent running on the same host as the Nomad agent with the default
    42  configuration, Nomad will automatically connect and configure with Consul.
    43  
    44  ## `consul` Parameters
    45  
    46  - `address` `(string: "127.0.0.1:8500")` - Specifies the address to the local
    47    Consul agent, given in the format `host:port`. Supports Unix sockets with the
    48    format: `unix:///tmp/consul/consul.sock`
    49  
    50  - `auth` `(string: "")` - Specifies the HTTP Basic Authentication information to
    51    use for access to the Consul Agent, given in the format `username:password`.
    52  
    53  - `auto_advertise` `(bool: true)` - Specifies if Nomad should advertise its
    54    services in Consul. The services are named according to `server_service_name`
    55    and `client_service_name`. Nomad servers and clients advertise their
    56    respective services, each tagged appropriately with either `http` or `rpc`
    57    tag. Nomad servers also advertise a `serf` tagged service.
    58  
    59  - `ca_file` `(string: "")` - Specifies an optional path to the CA certificate
    60    used for Consul communication. This defaults to the system bundle if
    61    unspecified.
    62  
    63  - `cert_file` `(string: "")` - Specifies the path to the certificate used for
    64    Consul communication. If this is set then you need to also set `key_file`.
    65  
    66  - `checks_use_advertise` `(bool: false)` - Specifies if Consul health checks
    67    should bind to the advertise address. By default, this is the bind address.
    68  
    69  - `client_auto_join` `(bool: true)` - Specifies if the Nomad clients should
    70    automatically discover servers in the same region by searching for the Consul
    71    service name defined in the `server_service_name` option. The search occurs if
    72    the client is not registered with any servers or it is unable to heartbeat to
    73    the leader of the region, in which case it may be partitioned and searches for
    74    other servers.
    75  
    76  - `client_service_name` `(string: "nomad-client")` - Specifies the name of the
    77    service in Consul for the Nomad clients.
    78  
    79  - `client_http_check_name` `(string: "Nomad Client HTTP Check")` - Specifies the
    80    HTTP health check name in Consul for the Nomad clients.
    81  
    82  - `key_file` `(string: "")` - Specifies the path to the private key used for
    83    Consul communication. If this is set then you need to also set `cert_file`.
    84  
    85  - `server_service_name` `(string: "nomad")` - Specifies the name of the service
    86    in Consul for the Nomad servers.
    87  
    88  - `server_http_check_name` `(string: "Nomad Server HTTP Check")` - Specifies the
    89    HTTP health check name in Consul for the Nomad servers.
    90  
    91  -  `server_serf_check_name` `(string: "Nomad Server Serf Check")` - Specifies
    92    the Serf health check name in Consul for the Nomad servers.
    93  
    94  -  `server_rpc_check_name` `(string: "Nomad Server RPC Check")` - Specifies
    95    the RPC health check name in Consul for the Nomad servers.
    96  
    97  - `server_auto_join` `(bool: true)` - Specifies if the Nomad servers should
    98    automatically discover and join other Nomad servers by searching for the
    99    Consul service name defined in the `server_service_name` option. This search
   100    only happens if the server does not have a leader.
   101  
   102  - `ssl` `(bool: false)` - Specifies if the transport scheme should use HTTPS to
   103    communicate with the Consul agent.
   104  
   105  - `token` `(string: "")` - Specifies the token used to provide a per-request ACL
   106    token. This option overrides the Consul Agent's default token.
   107  
   108  - `verify_ssl` `(bool: true)`- Specifies if SSL peer verification should be used
   109    when communicating to the Consul API client over HTTPS
   110  
   111  
   112  If the local Consul agent is configured and accessible by the Nomad agents, the
   113  Nomad cluster will [automatically bootstrap][bootstrap] provided
   114  `server_auto_join`, `client_auto_join`, and `auto_advertise` are all enabled
   115  (which is the default).
   116  
   117  ## `consul` Examples
   118  
   119  ### Default
   120  
   121  This example shows the default Consul integration:
   122  
   123  ```hcl
   124  consul {
   125    address             = "127.0.0.1:8500"
   126    server_service_name = "nomad"
   127    client_service_name = "nomad-client"
   128    auto_advertise      = true
   129    server_auto_join    = true
   130    client_auto_join    = true
   131  }
   132  ```
   133  
   134  ### Custom Address and Port
   135  
   136  This example shows pointing the Nomad agent at a different Consul address. Note
   137  that you should **never** point directly at a Consul server; always point to a
   138  local client. In this example, the Consul server is bound and listening on the
   139  node's private IP address instead of localhost, so we use that:
   140  
   141  ```hcl
   142  consul {
   143    address = "10.0.2.4:8500"
   144  }
   145  ```
   146  
   147  ### Custom SSL
   148  
   149  This example shows configuring custom SSL certificates to communicate with
   150  the Consul agent. The Consul agent should be configured to accept certificates
   151  similarly, but that is not discussed here:
   152  
   153  ```hcl
   154  consul {
   155    ssl       = true
   156    ca_file   = "/var/ssl/bundle/ca.bundle"
   157    cert_file = "/etc/ssl/consul.crt"
   158    key_file  = "/etc/ssl/consul.key"
   159  }
   160  ```
   161  
   162  [consul]: https://www.consul.io/ "Consul by HashiCorp"
   163  [bootstrap]: /guides/cluster/automatic.html "Automatic Bootstrapping"