github.com/ncodes/nomad@v0.5.7-0.20170403112158-97adf4a74fb3/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`.
    48  
    49  - `auth` `(string: "")` - Specifies the HTTP Basic Authentication information to
    50    use for access to the Consul Agent, given in the format `username:password`.
    51  
    52  - `auto_advertise` `(bool: true)` - Specifies if Nomad should advertise its
    53    services in Consul. The services are named according to `server_service_name`
    54    and `client_service_name`. Nomad servers and clients advertise their
    55    respective services, each tagged appropriately with either `http` or `rpc`
    56    tag. Nomad servers also advertise a `serf` tagged service.
    57  
    58  - `ca_file` `(string: "")` - Specifies an optional path to the CA certificate
    59    used for Consul communication. This defaults to the system bundle if
    60    unspecified.
    61  
    62  - `cert_file` `(string: "")` - Specifies the path to the certificate used for
    63    Consul communication. If this is set then you need to also set `key_file`.
    64  
    65  - `checks_use_advertise` `(bool: false)` - Specifies if Consul heath checks
    66    should bind to the advertise address. By default, this is the bind address.
    67  
    68  - `client_auto_join` `(bool: true)` - Specifies if the Nomad clients should
    69    automatically discover servers in the same region by searching for the Consul
    70    service name defined in the `server_service_name` option. The search occurs if
    71    the client is not registered with any servers or it is unable to heartbeat to
    72    the leader of the region, in which case it may be partitioned and searches for
    73    other servers.
    74  
    75  - `client_service_name` `(string: "nomad-client")` - Specifies the name of the
    76    service in Consul for the Nomad clients.
    77  
    78  - `key_file` `(string: "")` - Specifies the path to the private key used for
    79    Consul communication. If this is set then you need to also set `cert_file`.
    80  
    81  - `server_service_name` `(string: "nomad")` - Specifies the name of the service
    82    in Consul for the Nomad servers.
    83  
    84  - `server_auto_join` `(bool: true)` - Specifies if the Nomad servers should
    85    automatically discover and join other Nomad servers by searching for the
    86    Consul service name defined in the `server_service_name` option. This search
    87    only happens if the server does not have a leader.
    88  
    89  - `ssl` `(bool: false)` - Specifies if the transport scheme should use HTTPS to
    90    communicate with the Consul agent.
    91  
    92  - `token` `(string: "")` - Specifies the token used to provide a per-request ACL
    93    token. This option overrides the Consul Agent's default token.
    94  
    95  - `verify_ssl` `(bool: true)`- Specifies if SSL peer verification should be used
    96    when communicating to the Consul API client over HTTPS
    97  
    98  
    99  If the local Consul agent is configured and accessible by the Nomad agents, the
   100  Nomad cluster will [automatically bootstrap][bootstrap] provided
   101  `server_auto_join`, `client_auto_join`, and `auto_advertise` are all enabled
   102  (which is the default).
   103  
   104  ## `consul` Examples
   105  
   106  ### Default
   107  
   108  This example shows the default Consul integration:
   109  
   110  ```hcl
   111  ```
   112  
   113  That is not a mistake - it is intentionally empty. If a local Consul agent is
   114  running at the default address, Nomad will automatically connect and use the
   115  default values listed above.
   116  
   117  ### Custom Address and Port
   118  
   119  This example shows pointing the Nomad agent at a different Consul address. Note
   120  that you should **never** point directly at a Consul server; always point to a
   121  local client. In this example, the Consul server is bound and listening on the
   122  node's private IP address instead of localhost, so we use that:
   123  
   124  ```hcl
   125  consul {
   126    address = "10.0.2.4:8500"
   127  }
   128  ```
   129  
   130  ### Custom SSL
   131  
   132  This example shows configuring custom SSL certificates to communicate with
   133  the Consul agent. The Consul agent should be configured to accept certificates
   134  similarly, but that is not discussed here:
   135  
   136  ```hcl
   137  consul {
   138    ssl       = true
   139    ca_file   = "/var/ssl/bundle/ca.bundle"
   140    cert_file = "/etc/ssl/consul.crrt"
   141    key_file  = "/etc/ssl/consul.key"
   142  }
   143  ```
   144  
   145  [consul]: https://www.consul.io/ "Consul by HashiCorp"
   146  [bootstrap]: /guides/cluster/automatic.html "Automatic Bootstrapping"