github.com/quite/nomad@v0.8.6/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  An important requirement is that each Nomad agent talks to a unique Consul
    45  agent. Nomad agents should be configured to talk to Consul agents and not
    46  Consul servers. If you are observing flapping services, you may have have
    47  multiple Nomad agents talking to the same Consul agent. As such avoid
    48  configuring Nomad to talk to Consul via DNS such as consul.service.consul
    49  
    50  ## `consul` Parameters
    51  
    52  - `address` `(string: "127.0.0.1:8500")` - Specifies the address to the local
    53    Consul agent, given in the format `host:port`. Supports Unix sockets with the
    54    format: `unix:///tmp/consul/consul.sock`
    55  
    56  - `auth` `(string: "")` - Specifies the HTTP Basic Authentication information to
    57    use for access to the Consul Agent, given in the format `username:password`.
    58  
    59  - `auto_advertise` `(bool: true)` - Specifies if Nomad should advertise its
    60    services in Consul. The services are named according to `server_service_name`
    61    and `client_service_name`. Nomad servers and clients advertise their
    62    respective services, each tagged appropriately with either `http` or `rpc`
    63    tag. Nomad servers also advertise a `serf` tagged service.
    64  
    65  - `ca_file` `(string: "")` - Specifies an optional path to the CA certificate
    66    used for Consul communication. This defaults to the system bundle if
    67    unspecified.
    68  
    69  - `cert_file` `(string: "")` - Specifies the path to the certificate used for
    70    Consul communication. If this is set then you need to also set `key_file`.
    71  
    72  - `checks_use_advertise` `(bool: false)` - Specifies if Consul health checks
    73    should bind to the advertise address. By default, this is the bind address.
    74  
    75  - `client_auto_join` `(bool: true)` - Specifies if the Nomad clients should
    76    automatically discover servers in the same region by searching for the Consul
    77    service name defined in the `server_service_name` option. The search occurs if
    78    the client is not registered with any servers or it is unable to heartbeat to
    79    the leader of the region, in which case it may be partitioned and searches for
    80    other servers.
    81  
    82  - `client_service_name` `(string: "nomad-client")` - Specifies the name of the
    83    service in Consul for the Nomad clients.
    84  
    85  - `client_http_check_name` `(string: "Nomad Client HTTP Check")` - Specifies the
    86    HTTP health check name in Consul for the Nomad clients.
    87  
    88  - `key_file` `(string: "")` - Specifies the path to the private key used for
    89    Consul communication. If this is set then you need to also set `cert_file`.
    90  
    91  - `server_service_name` `(string: "nomad")` - Specifies the name of the service
    92    in Consul for the Nomad servers.
    93  
    94  - `server_http_check_name` `(string: "Nomad Server HTTP Check")` - Specifies the
    95    HTTP health check name in Consul for the Nomad servers.
    96  
    97  -  `server_serf_check_name` `(string: "Nomad Server Serf Check")` - Specifies
    98    the Serf health check name in Consul for the Nomad servers.
    99  
   100  -  `server_rpc_check_name` `(string: "Nomad Server RPC Check")` - Specifies
   101    the RPC health check name in Consul for the Nomad servers.
   102  
   103  - `server_auto_join` `(bool: true)` - Specifies if the Nomad servers should
   104    automatically discover and join other Nomad servers by searching for the
   105    Consul service name defined in the `server_service_name` option. This search
   106    only happens if the server does not have a leader.
   107  
   108  - `ssl` `(bool: false)` - Specifies if the transport scheme should use HTTPS to
   109    communicate with the Consul agent.
   110  
   111  - `token` `(string: "")` - Specifies the token used to provide a per-request ACL
   112    token. This option overrides the Consul Agent's default token. If the token is 
   113    not set here or on the Consul agent, it will default to Consul's anonymous policy, 
   114    which may or may not allow writes.
   115  
   116  - `verify_ssl` `(bool: true)`- Specifies if SSL peer verification should be used
   117    when communicating to the Consul API client over HTTPS
   118  
   119  
   120  If the local Consul agent is configured and accessible by the Nomad agents, the
   121  Nomad cluster will [automatically bootstrap][bootstrap] provided
   122  `server_auto_join`, `client_auto_join`, and `auto_advertise` are all enabled
   123  (which is the default).
   124  
   125  ## `consul` Examples
   126  
   127  ### Default
   128  
   129  This example shows the default Consul integration:
   130  
   131  ```hcl
   132  consul {
   133    address             = "127.0.0.1:8500"
   134    server_service_name = "nomad"
   135    client_service_name = "nomad-client"
   136    auto_advertise      = true
   137    server_auto_join    = true
   138    client_auto_join    = true
   139  }
   140  ```
   141  
   142  ### Custom Address and Port
   143  
   144  This example shows pointing the Nomad agent at a different Consul address. Note
   145  that you should **never** point directly at a Consul server; always point to a
   146  local client. In this example, the Consul server is bound and listening on the
   147  node's private IP address instead of localhost, so we use that:
   148  
   149  ```hcl
   150  consul {
   151    address = "10.0.2.4:8500"
   152  }
   153  ```
   154  
   155  ### Custom SSL
   156  
   157  This example shows configuring custom SSL certificates to communicate with
   158  the Consul agent. The Consul agent should be configured to accept certificates
   159  similarly, but that is not discussed here:
   160  
   161  ```hcl
   162  consul {
   163    ssl       = true
   164    ca_file   = "/var/ssl/bundle/ca.bundle"
   165    cert_file = "/etc/ssl/consul.crt"
   166    key_file  = "/etc/ssl/consul.key"
   167  }
   168  ```
   169  
   170  [consul]: https://www.consul.io/ "Consul by HashiCorp"
   171  [bootstrap]: /guides/cluster/automatic.html "Automatic Bootstrapping"