github.com/dkerwin/nomad@v0.3.3-0.20160525181927-74554135514b/website/source/docs/jobspec/servicediscovery.html.md (about) 1 --- 2 layout: "docs" 3 page_title: "Service Discovery in Nomad" 4 sidebar_current: "docs-jobspec-service-discovery" 5 description: |- 6 Learn how to add service discovery to jobs 7 --- 8 9 # Service Discovery 10 11 Nomad schedules workloads of various types across a cluster of generic hosts. 12 Because of this, placement is not known in advance and you will need to use 13 service discovery to connect tasks to other services deployed across your 14 cluster. Nomad integrates with [Consul](https://www.consul.io) to provide service 15 discovery and monitoring. 16 17 Note that in order to use Consul with Nomad, you will need to configure and 18 install Consul on your nodes alongside Nomad, or schedule it as a system job. 19 Nomad does not currently run Consul for you. 20 21 ## Configuration 22 23 * `consul.address`: This is a Nomad client configuration which can be used to 24 override the default Consul Agent HTTP port that Nomad uses to connect to 25 Consul. The default for this is `127.0.0.1:8500`. 26 27 * `consul.token`: Token is used to provide a per-request ACL token.This options 28 overrides the agent's default token 29 30 * `consul.auth`: The auth information to use for http access to the Consul 31 Agent. 32 33 * `consul.ssl`: This boolean option sets the transport scheme to talk to the Consul 34 Agent as `https`. This option is unset by default and so the default transport 35 scheme for the consul api client is `http`. 36 37 * `consul.verifyssl`: This option enables SSL verification when the transport 38 scheme for the Consul API client is `https`. This is set to true by default. 39 40 * `consul.tls_ca_file`: The path to the CA certificate used for Consul communication. 41 Set accordingly to the 42 [ca_file](https://www.consul.io/docs/agent/options.html#ca_file) setting in 43 Consul. 44 45 * `consul.tls_cert_file`: The path to the certificate for Consul communication. Set 46 accordingly 47 [cert_file](https://www.consul.io/docs/agent/options.html#cert_file) in 48 Consul. 49 50 * `consul.tls_key_file`: The path to the private key for Consul communication. 51 Set accordingly to the 52 [key_file](https://www.consul.io/docs/agent/options.html#key_file) setting in 53 Consul. 54 55 ## Service Definition Syntax 56 57 The service block in a Task definition defines a service which Nomad will 58 register with Consul. Multiple service blocks are allowed in a Task definition, 59 which allow registering multiple services for a Task that exposes multiple 60 ports. 61 62 ### Example 63 64 A brief example of a service definition in a Task 65 66 ``` 67 group "database" { 68 task "mysql" { 69 driver = "docker" 70 service { 71 tags = ["master", "mysql"] 72 port = "db" 73 check { 74 type = "tcp" 75 interval = "10s" 76 timeout = "2s" 77 } 78 check { 79 type = "script" 80 name = "check_table" 81 command = "/usr/local/bin/check_mysql_table_status" 82 args = ["--verbose"] 83 interval = "60s" 84 timeout = "5s" 85 } 86 } 87 resources { 88 cpu = 500 89 memory = 1024 90 network { 91 mbits = 10 92 port "db" { 93 } 94 } 95 } 96 } 97 } 98 ``` 99 100 * `name`: Nomad automatically determines the name of a Task. By default the 101 name of a service is `$(job-name)-$(task-group)-$(task-name)`. Users can 102 explicitly name the service by specifying this option. If multiple services 103 are defined for a Task then only one task can have the default name, all 104 the services have to be explicitly named. Users can add the following to 105 the service names: `${JOB}`, `${TASKGROUP}`, `${TASK}`, `${BASE}`. Nomad 106 will replace them with the appropriate value of the Job, Task Group, and 107 Task names while registering the Job. `${BASE}` expands to 108 `${JOB}-${TASKGROUP}-${TASK}`. Names must be adhere to 109 [RFC-1123 ยง2.1](https://tools.ietf.org/html/rfc1123#section-2) and are 110 limited to alphanumeric and hyphen characters (i.e. `[a-z0-9\-]`), and be 111 less than 64 characters in length. 112 113 * `tags`: A list of tags associated with this Service. String interpolation is 114 supported in tags. 115 116 * `port`: `port` is optional and is used to associate the port with the service. 117 If specified, the port label must match one defined in the resources block. 118 This could be a label to either a dynamic or a static port. If an incorrect 119 port label is specified, Nomad doesn't register the IP:Port with Consul. 120 121 * `check`: A check block defines a health check associated with the service. 122 Multiple check blocks are allowed for a service. Nomad supports the `script`, 123 `http` and `tcp` Consul Checks. Script checks are not supported for the qemu 124 driver since the Nomad client doesn't have access to the file system of a 125 tasks using the Qemu driver. 126 127 ### Check Syntax 128 129 * `type`: This indicates the check types supported by Nomad. Valid options are 130 currently `script`, `http` and `tcp`. 131 132 * `name`: The name of the health check. 133 134 * `interval`: This indicates the frequency of the health checks that Consul will 135 perform. 136 137 * `timeout`: This indicates how long Consul will wait for a health check query 138 to succeed. 139 140 * `path`: The path of the http endpoint which Consul will query to query the 141 health of a service if the type of the check is `http`. Nomad will add the IP 142 of the service and the port, users are only required to add the relative URL 143 of the health check endpoint. 144 145 * `protocol`: This indicates the protocol for the http checks. Valid options 146 are `http` and `https`. We default it to `http` 147 148 * `command`: This is the command that the Nomad client runs for doing script based 149 health check. 150 151 * `args`: Additional arguments to the `command` for script based health checks. 152 153 ## Assumptions 154 155 * Consul 0.6.4 or later is needed for using the Script checks. 156 157 * Consul 0.6.0 or later is needed for using the TCP checks. 158 159 * The service discovery feature in Nomad depends on operators making sure that 160 the Nomad client can reach the Consul agent. 161 162 * Nomad assumes that it controls the life cycle of all the externally 163 discoverable services running on a host. 164 165 * Tasks running inside Nomad also need to reach out to the Consul agent if 166 they want to use any of the Consul APIs. Ex: A task running inside a docker 167 container in the bridge mode won't be able to talk to a Consul Agent running 168 on the loopback interface of the host since the container in the bridge mode 169 has it's own network interface and doesn't see interfaces on the global 170 network namespace of the host. There are a couple of ways to solve this, one 171 way is to run the container in the host networking mode, or make the Consul 172 agent listen on an interface in the network namespace of the container.