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"