github.com/taylorchu/nomad@v0.5.3-rc1.0.20170407200202-db11e7dd7b55/website/source/docs/job-specification/service.html.md (about) 1 --- 2 layout: "docs" 3 page_title: "service Stanza - Job Specification" 4 sidebar_current: "docs-job-specification-service" 5 description: |- 6 The "service" stanza instructs Nomad to register the task as a service using 7 the service discovery integration. 8 --- 9 10 # `service` Stanza 11 12 <table class="table table-bordered table-striped"> 13 <tr> 14 <th width="120">Placement</th> 15 <td> 16 <code>job -> group -> task -> **service**</code> 17 </td> 18 </tr> 19 </table> 20 21 The `service` stanza instructs Nomad to register the task as a service using the 22 service discovery integration. This section of the documentation will discuss the 23 configuration, but please also read the 24 [Nomad service discovery documentation][service-discovery] for more detailed 25 information about the integration. 26 27 ```hcl 28 job "docs" { 29 group "example" { 30 task "server" { 31 service { 32 tags = ["leader", "mysql"] 33 34 port = "db" 35 36 check { 37 type = "tcp" 38 port = "db" 39 interval = "10s" 40 timeout = "2s" 41 } 42 43 check { 44 type = "script" 45 name = "check_table" 46 command = "/usr/local/bin/check_mysql_table_status" 47 args = ["--verbose"] 48 interval = "60s" 49 timeout = "5s" 50 } 51 } 52 } 53 } 54 } 55 ``` 56 57 This section of the documentation only covers the job file options for 58 configuring service discovery. For more information on the setup and 59 configuration to integrate Nomad with service discovery, please see the 60 [Nomad service discovery documentation][service-discovery]. There are steps you 61 must take to configure Nomad. Simply adding this configuration to your job file 62 does not automatically enable service discovery. 63 64 ## `service` Parameters 65 66 - `check` <code>([Check](#check-parameters): nil)</code> - Specifies a health 67 check associated with the service. This can be specified multiple times to 68 define multiple checks for the service. At this time, Nomad supports the 69 `script`<sup><small>1</small></sup>, `http` and `tcp` checks. 70 71 - `name` `(string: "<job>-<group>-<task>")` - Specifies the name of this 72 service. If not supplied, this will default to the name of the job, group, and 73 task concatenated together with a dash, like `"docs-example-server"`. Each 74 service must have a unique name within the cluster. Names must adhere to 75 [RFC-1123 ยง2.1](https://tools.ietf.org/html/rfc1123#section-2) and are limited 76 to alphanumeric and hyphen characters (i.e. `[a-z0-9\-]`), and be less than 64 77 characters in length. 78 79 In addition to the standard [Nomad interpolation][interpolation], the 80 following keys are also available: 81 82 - `${JOB}` - the name of the job 83 - `${GROUP}` - the name of the group 84 - `${TASK}` - the name of the task 85 - `${BASE}` - shorthand for `${JOB}-${GROUP}-${TASK}` 86 87 - `port` `(string: <required>)` - Specifies the label of the port on which this 88 service is running. Note this is the _label_ of the port and not the port 89 number. The port label must match one defined in the [`network`][network] 90 stanza. 91 92 - `tags` `(array<string>: [])` - Specifies the list of tags to associate with 93 this service. If this is not supplied, no tags will be assigned to the service 94 when it is registered. 95 96 ### `check` Parameters 97 98 - `args` `(array<string>: [])` - Specifies additional arguments to the 99 `command`. This only applies to script-based health checks. 100 101 - `command` `(string: <varies>)` - Specifies the command to run for performing 102 the health check. The script must exit: 0 for passing, 1 for warning, or any 103 other value for a failing health check. This is required for script-based 104 health checks. 105 106 ~> **Caveat:** The command must be the path to the command on disk, and no 107 shell exists by default. That means operators like `||` or `&&` are not 108 available. Additionally, all arguments must be supplied via the `args` 109 parameter. The achieve the behavior of shell operators, specify the command 110 as a shell, like `/bin/bash` and then use `args` to run the check. 111 112 - `initial_status` `(string: <enum>)` - Specifies the originating status of the 113 service. Valid options are the empty string, `passing`, `warning`, and 114 `critical`. 115 116 - `interval` `(string: <required>)` - Specifies the frequency of the health checks 117 that Consul will perform. This is specified using a label suffix like "30s" 118 or "1h". This must be greater than or equal to "1s" 119 120 - `name` `(string: "service: <name> check")` - Specifies the name of the health 121 check. 122 123 - `path` `(string: <varies>)` - Specifies the path of the HTTP endpoint which 124 Consul will query to query the health of a service. Nomad will automatically 125 add the IP of the service and the port, so this is just the relative URL to 126 the health check endpoint. This is required for http-based health checks. 127 128 - `port` `(string: <required>)` - Specifies the label of the port on which the 129 check will be performed. Note this is the _label_ of the port and not the port 130 number. The port label must match one defined in the [`network`][network] 131 stanza. If a port value was declared on the `service`, this will inherit from 132 that value if not supplied. If supplied, this value takes precedence over the 133 `service.port` value. This is useful for services which operate on multiple 134 ports. 135 136 - `protocol` `(string: "http")` - Specifies the protocol for the http-based 137 health checks. Valid options are `http` and `https`. 138 139 - `timeout` `(string: <required>)` - Specifies how long Consul will wait for a 140 health check query to succeed. This is specified using a label suffix like 141 "30s" or "1h". This must be greater than or equal to "1s" 142 143 - `type` `(string: <required>)` - This indicates the check types supported by 144 Nomad. Valid options are `script`, `http`, and `tcp`. 145 146 147 ## `service` Examples 148 149 The following examples only show the `service` stanzas. Remember that the 150 `service` stanza is only valid in the placements listed above. 151 152 ### Basic Service 153 154 This example registers a service named "load-balancer" with no health checks. 155 156 ```hcl 157 service { 158 name = "load-balancer" 159 port = "lb" 160 } 161 ``` 162 163 This example must be accompanied by a [`network`][network] stanza which defines 164 a static or dynamic port labeled "lb". For example: 165 166 ```hcl 167 resources { 168 network { 169 mbits = 10 170 port "lb" {} 171 } 172 } 173 ``` 174 175 ### Check with Bash-isms 176 177 This example shows a common mistake and correct behavior for custom checks. 178 Suppose a health check like this: 179 180 ```shell 181 $ test -f /tmp/file.txt 182 ``` 183 184 In this example `test` is not actually a command (binary) on the system; it is a 185 built-in shell function to bash. Thus, the following **would not work**: 186 187 ```hcl 188 service { 189 check { 190 type = "script" 191 command = "test -f /tmp/file.txt" # THIS IS NOT CORRECT 192 } 193 } 194 ``` 195 196 Nomad will attempt to find an executable named `test` on your system, but it 197 does not exist. It is actually just a function of bash. Additionally, it is not 198 possible to specify the arguments in a single string. Here is the correct 199 solution: 200 201 ```hcl 202 service { 203 check { 204 type = "script" 205 command = "/bin/bash" 206 args = ["-c", "test -f /tmp/file.txt"] 207 } 208 } 209 ``` 210 211 The `command` is actually `/bin/bash`, since that is the actual process we are 212 running. The arguments to that command are the script itself, which each 213 argument provided as a value to the `args` array. 214 215 ### HTTP Health Check 216 217 This example shows a service with an HTTP health check. This will query the 218 service on the IP and port registered with Nomad at `/_healthz` every 5 seconds, 219 giving the service a maximum of 2 seconds to return a response. Any non-2xx code 220 is considered a failure. 221 222 ```hcl 223 service { 224 check { 225 type = "http" 226 port = "lb" 227 path = "/_healthz" 228 interval = "5s" 229 timeout = "2s" 230 } 231 } 232 ``` 233 234 ### Multiple Health Checks 235 236 This example shows a service with multiple health checks defined. All health 237 checks must be passing in order for the service to register as healthy. 238 239 ```hcl 240 service { 241 check { 242 type = "http" 243 port = "lb" 244 path = "/_healthz" 245 interval = "5s" 246 timeout = "2s" 247 } 248 249 check { 250 type = "http" 251 protocol = "https" 252 port = "lb" 253 path = "/_healthz" 254 interval = "5s" 255 timeout = "2s" 256 } 257 258 check { 259 type = "script" 260 command = "/usr/local/bin/pg-tools" 261 args = ["verify", "database" "prod", "up"] 262 interval = "5s" 263 timeout = "2s" 264 } 265 } 266 ``` 267 268 - - - 269 270 <sup><small>1</small></sup><small> Script checks are not supported for the 271 [qemu driver][qemu] since the Nomad client does not have access to the file 272 system of a task for that driver.</small> 273 274 [service-discovery]: /docs/service-discovery/index.html "Nomad Service Discovery" 275 [interpolation]: /docs/runtime/interpolation.html "Nomad Runtime Interpolation" 276 [network]: /docs/job-specification/network.html "Nomad network Job Specification" 277 [qemu]: /docs/drivers/qemu.html "Nomad qemu Driver"