github.com/diptanu/nomad@v0.5.7-0.20170516172507-d72e86cbe3d9/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 heath 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  ```
   113  
   114  That is not a mistake - it is intentionally empty. If a local Consul agent is
   115  running at the default address, Nomad will automatically connect and use the
   116  default values listed above.
   117  
   118  ### Custom Address and Port
   119  
   120  This example shows pointing the Nomad agent at a different Consul address. Note
   121  that you should **never** point directly at a Consul server; always point to a
   122  local client. In this example, the Consul server is bound and listening on the
   123  node's private IP address instead of localhost, so we use that:
   124  
   125  ```hcl
   126  consul {
   127    address = "10.0.2.4:8500"
   128  }
   129  ```
   130  
   131  ### Custom SSL
   132  
   133  This example shows configuring custom SSL certificates to communicate with
   134  the Consul agent. The Consul agent should be configured to accept certificates
   135  similarly, but that is not discussed here:
   136  
   137  ```hcl
   138  consul {
   139    ssl       = true
   140    ca_file   = "/var/ssl/bundle/ca.bundle"
   141    cert_file = "/etc/ssl/consul.crrt"
   142    key_file  = "/etc/ssl/consul.key"
   143  }
   144  ```
   145  
   146  [consul]: https://www.consul.io/ "Consul by HashiCorp"
   147  [bootstrap]: /guides/cluster/automatic.html "Automatic Bootstrapping"