github.com/hspak/nomad@v0.7.2-0.20180309000617-bc4ae22a39a5/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  - `key_file` `(string: "")` - Specifies the path to the private key used for
    80    Consul communication. If this is set then you need to also set `cert_file`.
    81  
    82  - `server_service_name` `(string: "nomad")` - Specifies the name of the service
    83    in Consul for the Nomad servers.
    84  
    85  - `server_auto_join` `(bool: true)` - Specifies if the Nomad servers should
    86    automatically discover and join other Nomad servers by searching for the
    87    Consul service name defined in the `server_service_name` option. This search
    88    only happens if the server does not have a leader.
    89  
    90  - `ssl` `(bool: false)` - Specifies if the transport scheme should use HTTPS to
    91    communicate with the Consul agent.
    92  
    93  - `token` `(string: "")` - Specifies the token used to provide a per-request ACL
    94    token. This option overrides the Consul Agent's default token.
    95  
    96  - `verify_ssl` `(bool: true)`- Specifies if SSL peer verification should be used
    97    when communicating to the Consul API client over HTTPS
    98  
    99  
   100  If the local Consul agent is configured and accessible by the Nomad agents, the
   101  Nomad cluster will [automatically bootstrap][bootstrap] provided
   102  `server_auto_join`, `client_auto_join`, and `auto_advertise` are all enabled
   103  (which is the default).
   104  
   105  ## `consul` Examples
   106  
   107  ### Default
   108  
   109  This example shows the default Consul integration:
   110  
   111  ```hcl
   112  consul {
   113    address             = "127.0.0.1:8500"
   114    server_service_name = "nomad"
   115    client_service_name = "nomad-client"
   116    auto_advertise      = true
   117    server_auto_join    = true
   118    client_auto_join    = true
   119  }
   120  ```
   121  
   122  ### Custom Address and Port
   123  
   124  This example shows pointing the Nomad agent at a different Consul address. Note
   125  that you should **never** point directly at a Consul server; always point to a
   126  local client. In this example, the Consul server is bound and listening on the
   127  node's private IP address instead of localhost, so we use that:
   128  
   129  ```hcl
   130  consul {
   131    address = "10.0.2.4:8500"
   132  }
   133  ```
   134  
   135  ### Custom SSL
   136  
   137  This example shows configuring custom SSL certificates to communicate with
   138  the Consul agent. The Consul agent should be configured to accept certificates
   139  similarly, but that is not discussed here:
   140  
   141  ```hcl
   142  consul {
   143    ssl       = true
   144    ca_file   = "/var/ssl/bundle/ca.bundle"
   145    cert_file = "/etc/ssl/consul.crt"
   146    key_file  = "/etc/ssl/consul.key"
   147  }
   148  ```
   149  
   150  [consul]: https://www.consul.io/ "Consul by HashiCorp"
   151  [bootstrap]: /guides/cluster/automatic.html "Automatic Bootstrapping"