github.com/iqoqo/nomad@v0.11.3-0.20200911112621-d7021c74d101/website/pages/docs/configuration/consul.mdx

github.com/iqoqo/nomad@v0.11.3-0.20200911112621-d7021c74d101/website/pages/docs/configuration/consul.mdx (about)

1 ---
2 layout: docs
3 page_title: consul Stanza - Agent Configuration
4 sidebar_title: 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 <Placement groups={['consul']} />
15
16 The `consul` stanza configures the Nomad agent's communication with
17 [Consul][consul] for service discovery and key-value integration. When
18 configured, tasks can register themselves with Consul, and the Nomad cluster can
19 [automatically bootstrap][bootstrap] itself.
20
21 ```hcl
22 consul {
23 address = "127.0.0.1:8500"
24 auth = "admin:password"
25 token = "abcd1234"
26 }
27 ```
28
29 A default `consul` stanza is automatically merged with all Nomad agent
30 configurations. These sane defaults automatically enable Consul integration if
31 Consul is detected on the system. This allows for seamless bootstrapping of the
32 cluster with zero configuration. To put it another way: if you have a Consul
33 agent running on the same host as the Nomad agent with the default
34 configuration, Nomad will automatically connect and configure with Consul.
35
36 ~> An important requirement is that each Nomad agent talks to a unique Consul
37 agent. Nomad agents should be configured to talk to Consul agents and not
38 Consul servers. If you are observing flapping services, you may have
39 multiple Nomad agents talking to the same Consul agent. As such avoid
40 configuring Nomad to talk to Consul via DNS such as consul.service.consul
41
42 ## `consul` Parameters
43
44 - `address` `(string: "127.0.0.1:8500")` - Specifies the address to the local
45 Consul agent, given in the format `host:port`. Supports Unix sockets with the
46 format: `unix:///tmp/consul/consul.sock`. Will default to the
47 `CONSUL_HTTP_ADDR` environment variable if set.
48
49 - `allow_unauthenticated` `(bool: true)` - Specifies if users submitting jobs to
50 the Nomad server should be required to provide their own Consul token, proving
51 they have access to the service identity policies required by the Consul Connect
52 enabled services listed in the job. This option should be
53 disabled in an untrusted environment.
54
55 - `auth` `(string: "")` - Specifies the HTTP Basic Authentication information to
56 use for access to the Consul Agent, given in the format `username:password`.
57
58 - `auto_advertise` `(bool: true)` - Specifies if Nomad should advertise its
59 services in Consul. The services are named according to `server_service_name`
60 and `client_service_name`. Nomad servers and clients advertise their
61 respective services, each tagged appropriately with either `http` or `rpc`
62 tag. Nomad servers also advertise a `serf` tagged service.
63
64 - `ca_file` `(string: "")` - Specifies an optional path to the CA certificate
65 used for Consul communication. This defaults to the system bundle if
66 unspecified. Will default to the `CONSUL_CACERT` environment variable if set.
67
68 - `cert_file` `(string: "")` - Specifies the path to the certificate used for
69 Consul communication. If this is set then you need to also set `key_file`.
70
71 - `checks_use_advertise` `(bool: false)` - Specifies if Consul health checks
72 should bind to the advertise address. By default, this is the bind address.
73
74 - `client_auto_join` `(bool: true)` - Specifies if the Nomad clients should
75 automatically discover servers in the same region by searching for the Consul
76 service name defined in the `server_service_name` option. The search occurs if
77 the client is not registered with any servers or it is unable to heartbeat to
78 the leader of the region, in which case it may be partitioned and searches for
79 other servers.
80
81 - `client_service_name` `(string: "nomad-client")` - Specifies the name of the
82 service in Consul for the Nomad clients.
83
84 - `client_http_check_name` `(string: "Nomad Client HTTP Check")` - Specifies the
85 HTTP health check name in Consul for the Nomad clients.
86
87 - `key_file` `(string: "")` - Specifies the path to the private key used for
88 Consul communication. If this is set then you need to also set `cert_file`.
89
90 - `server_service_name` `(string: "nomad")` - Specifies the name of the service
91 in Consul for the Nomad servers.
92
93 - `server_http_check_name` `(string: "Nomad Server HTTP Check")` - Specifies the
94 HTTP health check name in Consul for the Nomad servers.
95
96 - `server_serf_check_name` `(string: "Nomad Server Serf Check")` - Specifies
97 the Serf health check name in Consul for the Nomad servers.
98
99 - `server_rpc_check_name` `(string: "Nomad Server RPC Check")` - Specifies
100 the RPC health check name in Consul for the Nomad servers.
101
102 - `server_auto_join` `(bool: true)` - Specifies if the Nomad servers should
103 automatically discover and join other Nomad servers by searching for the
104 Consul service name defined in the `server_service_name` option. This search
105 only happens if the server does not have a leader.
106
107 - `ssl` `(bool: false)` - Specifies if the transport scheme should use HTTPS to
108 communicate with the Consul agent. Will default to the `CONSUL_HTTP_SSL`
109 environment variable if set.
110
111 - `tags` `(array<string>: [])` - Specifies optional Consul tags to be
112 registered with the Nomad server and agent services.
113
114 - `token` `(string: "")` - Specifies the token used to provide a per-request ACL
115 token. This option overrides the Consul Agent's default token. If the token is
116 not set here or on the Consul agent, it will default to Consul's anonymous policy,
117 which may or may not allow writes.
118
119 - `verify_ssl` `(bool: true)`- Specifies if SSL peer verification should be used
120 when communicating to the Consul API client over HTTPS. Will default to the
121 `CONSUL_HTTP_SSL_VERIFY` environment variable if set.
122
123 If the local Consul agent is configured and accessible by the Nomad agents, the
124 Nomad cluster will [automatically bootstrap][bootstrap] provided
125 `server_auto_join`, `client_auto_join`, and `auto_advertise` are all enabled
126 (which is the default).
127
128 ## `consul` Examples
129
130 ### Default
131
132 This example shows the default Consul integration:
133
134 ```hcl
135 consul {
136 address = "127.0.0.1:8500"
137 server_service_name = "nomad"
138 client_service_name = "nomad-client"
139 auto_advertise = true
140 server_auto_join = true
141 client_auto_join = true
142 }
143 ```
144
145 ### Custom Address and Port
146
147 This example shows pointing the Nomad agent at a different Consul address. Note
148 that you should **never** point directly at a Consul server; always point to a
149 local client. In this example, the Consul server is bound and listening on the
150 node's private IP address instead of localhost, so we use that:
151
152 ```hcl
153 consul {
154 address = "10.0.2.4:8500"
155 }
156 ```
157
158 ### Custom SSL
159
160 This example shows configuring custom SSL certificates to communicate with
161 the Consul agent. The Consul agent should be configured to accept certificates
162 similarly, but that is not discussed here:
163
164 ```hcl
165 consul {
166 ssl = true
167 ca_file = "/var/ssl/bundle/ca.bundle"
168 cert_file = "/etc/ssl/consul.crt"
169 key_file = "/etc/ssl/consul.key"
170 }
171 ```
172
173 [consul]: https://www.consul.io/ 'Consul by HashiCorp'
174 [bootstrap]: https://learn.hashicorp.com/nomad/operating-nomad/clustering 'Automatic Bootstrapping'