github.com/smintz/nomad@v0.8.3/website/source/docs/agent/configuration/client.html.md (about) 1 --- 2 layout: "docs" 3 page_title: "client Stanza - Agent Configuration" 4 sidebar_current: "docs-agent-configuration-client" 5 description: |- 6 The "client" stanza configures the Nomad agent to accept jobs as assigned by 7 the Nomad server, join the cluster, and specify driver-specific configuration. 8 --- 9 10 # `client` Stanza 11 12 <table class="table table-bordered table-striped"> 13 <tr> 14 <th width="120">Placement</th> 15 <td> 16 <code>**client**</code> 17 </td> 18 </tr> 19 </table> 20 21 The `client` stanza configures the Nomad agent to accept jobs as assigned by 22 the Nomad server, join the cluster, and specify driver-specific configuration. 23 24 ```hcl 25 client { 26 enabled = true 27 servers = ["1.2.3.4:4647", "5.6.7.8:4647"] 28 } 29 ``` 30 31 ## `client` Parameters 32 33 - `alloc_dir` `(string: "[data_dir]/alloc")` - Specifies the directory to use 34 for allocation data. By default, this is the top-level 35 [data_dir](/docs/agent/configuration/index.html#data_dir) suffixed with 36 "alloc", like `"/opt/nomad/alloc"`. This must be an absolute path 37 38 - `chroot_env` <code>([ChrootEnv](#chroot_env-parameters): nil)</code> - 39 Specifies a key-value mapping that defines the chroot environment for jobs 40 using the Exec and Java drivers. 41 42 - `enabled` `(bool: false)` - Specifies if client mode is enabled. All other 43 client configuration options depend on this value. 44 45 - `max_kill_timeout` `(string: "30s")` - Specifies the maximum amount of time a 46 job is allowed to wait to exit. Individual jobs may customize their own kill 47 timeout, but it may not exceed this value. 48 49 - `meta` `(map[string]string: nil)` - Specifies a key-value map that annotates 50 with user-defined metadata. 51 52 - `network_interface` `(string: varied)` - Specifies the name of the interface 53 to force network fingerprinting on. When run in dev mode, this defaults to the 54 loopback interface. When not in dev mode, the interface attached to the 55 default route is used. All IP addresses except those scoped local for IPV6 on 56 the chosen interface are fingerprinted. The scheduler chooses from those IP 57 addresses when allocating ports for tasks. 58 59 - `network_speed` `(int: 0)` - Specifies an override for the network link speed. 60 This value, if set, overrides any detected or defaulted link speed. Most 61 clients can determine their speed automatically, and thus in most cases this 62 should be left unset. 63 64 - `cpu_total_compute` `(int: 0)` - Specifies an override for the total CPU 65 compute. This value should be set to `# Cores * Core MHz`. For example, a 66 quad-core running at 2 GHz would have a total compute of 8000 (4 * 2000). Most 67 clients can determine their total CPU compute automatically, and thus in most 68 cases this should be left unset. 69 70 - `memory_total_mb` `(int:0)` - Specifies an override for the total memory. If set, 71 this value overrides any detected memory. 72 73 - `node_class` `(string: "")` - Specifies an arbitrary string used to logically 74 group client nodes by user-defined class. This can be used during job 75 placement as a filter. 76 77 - `options` <code>([Options](#options-parameters): nil)</code> - Specifies a 78 key-value mapping of internal configuration for clients, such as for driver 79 configuration. 80 81 - `reserved` <code>([Reserved](#reserved-parameters): nil)</code> - Specifies 82 that Nomad should reserve a portion of the node's resources from receiving 83 tasks. This can be used to target a certain capacity usage for the node. For 84 example, 20% of the node's CPU could be reserved to target a CPU utilization 85 of 80%. 86 87 - `servers` `(array<string>: [])` - Specifies an array of addresses to the Nomad 88 servers this client should join. This list is used to register the client with 89 the server nodes and advertise the available resources so that the agent can 90 receive work. This may be specified as an IP address or DNS, with or without 91 the port. If the port is omitted, the default port of `4647` is used. 92 93 - `state_dir` `(string: "[data_dir]/client")` - Specifies the directory to use 94 to store client state. By default, this is - the top-level 95 [data_dir](/docs/agent/configuration/index.html#data_dir) suffixed with 96 "client", like `"/opt/nomad/client"`. This must be an absolute path. 97 98 - `gc_interval` `(string: "1m")` - Specifies the interval at which Nomad 99 attempts to garbage collect terminal allocation directories. 100 101 - `gc_disk_usage_threshold` `(float: 80)` - Specifies the disk usage percent which 102 Nomad tries to maintain by garbage collecting terminal allocations. 103 104 - `gc_inode_usage_threshold` `(float: 70)` - Specifies the inode usage percent 105 which Nomad tries to maintain by garbage collecting terminal allocations. 106 107 - `gc_max_allocs` `(int: 50)` - Specifies the maximum number of allocations 108 which a client will track before triggering a garbage collection of terminal 109 allocations. This will *not* limit the number of allocations a node can run at 110 a time, however after `gc_max_allocs` every new allocation will cause terminal 111 allocations to be GC'd. 112 113 - `gc_parallel_destroys` `(int: 2)` - Specifies the maximum number of 114 parallel destroys allowed by the garbage collector. This value should be 115 relatively low to avoid high resource usage during garbage collections. 116 117 - `no_host_uuid` `(bool: true)` - By default a random node UUID will be 118 generated, but setting this to `false` will use the system's UUID. Before 119 Nomad 0.6 the default was to use the system UUID. 120 121 ### `chroot_env` Parameters 122 123 Drivers based on [isolated fork/exec](/docs/drivers/exec.html) implement file 124 system isolation using chroot on Linux. The `chroot_env` map allows the chroot 125 environment to be configured using source paths on the host operating system. 126 The mapping format is: 127 128 ```text 129 source_path -> dest_path 130 ``` 131 132 The following example specifies a chroot which contains just enough to run the 133 `ls` utility: 134 135 ```hcl 136 client { 137 chroot_env { 138 "/bin/ls" = "/bin/ls" 139 "/etc/ld.so.cache" = "/etc/ld.so.cache" 140 "/etc/ld.so.conf" = "/etc/ld.so.conf" 141 "/etc/ld.so.conf.d" = "/etc/ld.so.conf.d" 142 "/lib" = "/lib" 143 "/lib64" = "/lib64" 144 } 145 } 146 ``` 147 148 When `chroot_env` is unspecified, the `exec` driver will use a default chroot 149 environment with the most commonly used parts of the operating system. Please 150 see the [Nomad `exec` driver documentation](/docs/drivers/exec.html#chroot) for 151 the full list. 152 153 ### `options` Parameters 154 155 The following is not an exhaustive list of options for only the Nomad 156 client. To find the options supported by each individual Nomad driver, please 157 see the [drivers documentation](/docs/drivers/index.html). 158 159 - `"driver.whitelist"` `(string: "")` - Specifies a comma-separated list of 160 whitelisted drivers . If specified, drivers not in the whitelist will be 161 disabled. If the whitelist is empty, all drivers are fingerprinted and enabled 162 where applicable. 163 164 ```hcl 165 client { 166 options = { 167 "driver.whitelist" = "docker,qemu" 168 } 169 } 170 ``` 171 172 - `"driver.blacklist"` `(string: "")` - Specifies a comma-separated list of 173 blacklisted drivers . If specified, drivers in the blacklist will be 174 disabled. 175 176 ```hcl 177 client { 178 options = { 179 "driver.blacklist" = "docker,qemu" 180 } 181 } 182 ``` 183 184 - `"env.blacklist"` `(string: see below)` - Specifies a comma-separated list of 185 environment variable keys not to pass to these tasks. Nomad passes the host 186 environment variables to `exec`, `raw_exec` and `java` tasks. If specified, 187 the defaults are overridden. If a value is provided, **all** defaults are 188 overridden (they are not merged). 189 190 ```hcl 191 client { 192 options = { 193 "env.blacklist" = "MY_CUSTOM_ENVVAR" 194 } 195 } 196 ``` 197 198 The default list is: 199 200 ```text 201 CONSUL_TOKEN 202 VAULT_TOKEN 203 AWS_ACCESS_KEY_ID 204 AWS_SECRET_ACCESS_KEY 205 AWS_SESSION_TOKEN 206 GOOGLE_APPLICATION_CREDENTIALS 207 ``` 208 209 - `"user.blacklist"` `(string: see below)` - Specifies a comma-separated 210 blacklist of usernames for which a task is not allowed to run. This only 211 applies if the driver is included in `"user.checked_drivers"`. If a value is 212 provided, **all** defaults are overridden (they are not merged). 213 214 ```hcl 215 client { 216 options = { 217 "user.blacklist" = "root,ubuntu" 218 } 219 } 220 ``` 221 222 The default list is: 223 224 ```text 225 root 226 Administrator 227 ``` 228 229 - `"user.checked_drivers"` `(string: see below)` - Specifies a comma-separated 230 list of drivers for which to enforce the `"user.blacklist"`. For drivers using 231 containers, this enforcement is usually unnecessary. If a value is provided, 232 **all** defaults are overridden (they are not merged). 233 234 ```hcl 235 client { 236 options = { 237 "user.checked_drivers" = "exec,raw_exec" 238 } 239 } 240 ``` 241 242 The default list is: 243 244 ```text 245 exec 246 qemu 247 java 248 ``` 249 250 - `"fingerprint.whitelist"` `(string: "")` - Specifies a comma-separated list of 251 whitelisted fingerprinters. If specified, any fingerprinters not in the 252 whitelist will be disabled. If the whitelist is empty, all fingerprinters are 253 used. 254 255 ```hcl 256 client { 257 options = { 258 "fingerprint.whitelist" = "network" 259 } 260 } 261 ``` 262 263 - `"fingerprint.blacklist"` `(string: "")` - Specifies a comma-separated list of 264 blacklisted fingerprinters. If specified, any fingerprinters in the blacklist 265 will be disabled. 266 267 ```hcl 268 client { 269 options = { 270 "fingerprint.blacklist" = "network" 271 } 272 } 273 ``` 274 275 - `"fingerprint.network.disallow_link_local"` `(string: "false")` - Specifies 276 whether the network fingerprinter should ignore link-local addresses in the 277 case that no globally routable address is found. The fingerprinter will always 278 prefer globally routable addresses. 279 280 ```hcl 281 client { 282 options = { 283 "fingerprint.network.disallow_link_local" = "true" 284 } 285 } 286 ``` 287 288 ### `reserved` Parameters 289 290 - `cpu` `(int: 0)` - Specifies the amount of CPU to reserve, in MHz. 291 292 - `memory` `(int: 0)` - Specifies the amount of memory to reserve, in MB. 293 294 - `disk` `(int: 0)` - Specifies the amount of disk to reserve, in MB. 295 296 - `reserved_ports` `(string: "")` - Specifies a comma-separated list of ports to 297 reserve on all fingerprinted network devices. Ranges can be specified by using 298 a hyphen separated the two inclusive ends. 299 300 ## `client` Examples 301 302 ### Common Setup 303 304 This example shows the most basic configuration for a Nomad client joined to a 305 cluster. 306 307 ```hcl 308 client { 309 enabled = true 310 servers = ["1.2.3.4:4647", "5.6.7.8:4647"] 311 } 312 ``` 313 314 ### Reserved Resources 315 316 This example shows a sample configuration for reserving resources to the client. 317 This is useful if you want to allocate only a portion of the client's resources 318 to jobs. 319 320 ```hcl 321 client { 322 enabled = true 323 324 reserved { 325 cpu = 500 326 memory = 512 327 disk = 1024 328 reserved_ports = "22,80,8500-8600" 329 } 330 } 331 ``` 332 333 ### Custom Metadata, Network Speed, and Node Class 334 335 This example shows a client configuration which customizes the metadata, network 336 speed, and node class. 337 338 ```hcl 339 client { 340 enabled = true 341 network_speed = 500 342 node_class = "prod" 343 344 meta { 345 "owner" = "ops" 346 } 347 } 348 ```