luxolus
/
open-nomad
2
0
Fork 0
Code Issues 1 Pull Requests Packages Releases Wiki Activity
open-nomad/website/pages/docs/configuration/client.mdx

472 lines
16 KiB
Plaintext
Raw Blame History

---
layout: docs
page_title: client Stanza - Agent Configuration
sidebar_title: client
description: |-
The "client" stanza configures the Nomad agent to accept jobs as assigned by
the Nomad server, join the cluster, and specify driver-specific configuration.
---
# `client` Stanza
<Placement groups={['client']} />
The `client` stanza configures the Nomad agent to accept jobs as assigned by
the Nomad server, join the cluster, and specify driver-specific configuration.
```hcl
client {
enabled = true
servers = ["1.2.3.4:4647", "5.6.7.8:4647"]
}
```
## Plugin Options
Nomad 0.9 now supports pluggable drivers. Operators should use the new
[plugin][plugin-stanza] syntax to modify driver configuration. To find the
plugin options supported by each individual Nomad driver, please see the
[drivers documentation](/docs/drivers). The pre-0.9 `client.options`
stanza will be supported in 0.9 for backward compatibility (except for the `lxc`
driver) but will be removed in a future release.
## `client` Parameters
- `alloc_dir` `(string: "[data_dir]/alloc")` - Specifies the directory to use
for allocation data. By default, this is the top-level
[data_dir](/docs/configuration#data_dir) suffixed with
"alloc", like `"/opt/nomad/alloc"`. This must be an absolute path.
- `chroot_env` <code>([ChrootEnv](#chroot_env-parameters): nil)</code> -
Specifies a key-value mapping that defines the chroot environment for jobs
using the Exec and Java drivers.
- `enabled` `(bool: false)` - Specifies if client mode is enabled. All other
client configuration options depend on this value.
- `max_kill_timeout` `(string: "30s")` - Specifies the maximum amount of time a
job is allowed to wait to exit. Individual jobs may customize their own kill
timeout, but it may not exceed this value.
- `disable_remote_exec` `(bool: false)` - Specifies if the client should disable
remote task execution to tasks running on this client.
- `meta` `(map[string]string: nil)` - Specifies a key-value map that annotates
with user-defined metadata.
- `network_interface` `(string: varied)` - Specifies the name of the interface
to force network fingerprinting on. When run in dev mode, this defaults to the
loopback interface. When not in dev mode, the interface attached to the
default route is used. The scheduler chooses from these fingerprinted IP
addresses when allocating ports for tasks.
If no non-local IP addresses are found, Nomad could fingerprint link-local IPv6
addresses depending on the client's
[`"fingerprint.network.disallow_link_local"`](#fingerprint-network-disallow_link_local)
configuration value.
- `network_speed` `(int: 0)` - Specifies an override for the network link speed.
This value, if set, overrides any detected or defaulted link speed. Most
clients can determine their speed automatically, and thus in most cases this
should be left unset.
- `cpu_total_compute` `(int: 0)` - Specifies an override for the total CPU
compute. This value should be set to `# Cores * Core MHz`. For example, a
quad-core running at 2 GHz would have a total compute of 8000 (4 \* 2000). Most
clients can determine their total CPU compute automatically, and thus in most
cases this should be left unset.
- `memory_total_mb` `(int:0)` - Specifies an override for the total memory. If set,
this value overrides any detected memory.
- `node_class` `(string: "")` - Specifies an arbitrary string used to logically
group client nodes by user-defined class. This can be used during job
placement as a filter.
- `options` <code>([Options](#options-parameters): nil)</code> - Specifies a
key-value mapping of internal configuration for clients, such as for driver
configuration.
- `reserved` <code>([Reserved](#reserved-parameters): nil)</code> - Specifies
that Nomad should reserve a portion of the node's resources from receiving
tasks. This can be used to target a certain capacity usage for the node. For
example, 20% of the node's CPU could be reserved to target a CPU utilization
of 80%.
- `servers` `(array<string>: [])` - Specifies an array of addresses to the Nomad
servers this client should join. This list is used to register the client with
the server nodes and advertise the available resources so that the agent can
receive work. This may be specified as an IP address or DNS, with or without
the port. If the port is omitted, the default port of `4647` is used.
- `server_join` <code>([server_join][server-join]: nil)</code> - Specifies
how the Nomad client will connect to Nomad servers. The `start_join` field
is not supported on the client. The retry_join fields may directly specify
the server address or use go-discover syntax for auto-discovery. See the
documentation for more detail.
- `state_dir` `(string: "[data_dir]/client")` - Specifies the directory to use
to store client state. By default, this is - the top-level
[data_dir](/docs/configuration#data_dir) suffixed with
"client", like `"/opt/nomad/client"`. This must be an absolute path.
- `gc_interval` `(string: "1m")` - Specifies the interval at which Nomad
attempts to garbage collect terminal allocation directories.
- `gc_disk_usage_threshold` `(float: 80)` - Specifies the disk usage percent which
Nomad tries to maintain by garbage collecting terminal allocations.
- `gc_inode_usage_threshold` `(float: 70)` - Specifies the inode usage percent
which Nomad tries to maintain by garbage collecting terminal allocations.
- `gc_max_allocs` `(int: 50)` - Specifies the maximum number of allocations
which a client will track before triggering a garbage collection of terminal
allocations. This will _not_ limit the number of allocations a node can run at
a time, however after `gc_max_allocs` every new allocation will cause terminal
allocations to be GC'd.
- `gc_parallel_destroys` `(int: 2)` - Specifies the maximum number of
parallel destroys allowed by the garbage collector. This value should be
relatively low to avoid high resource usage during garbage collections.
- `no_host_uuid` `(bool: true)` - By default a random node UUID will be
generated, but setting this to `false` will use the system's UUID. Before
Nomad 0.6 the default was to use the system UUID.
- `cni_path` `(string: "/opt/cni/bin")` - Sets the search path that is used for
CNI plugin discovery. Multiple paths can be searched using colon delimited
paths
- `cni_config_dir` `(string: "/opt/cni/config")` - Sets the directory where CNI
network configuration is located. The client will use this path when fingerprinting CNI networks.
- `bridge_network name` `(string: "nomad")` - Sets the name of the bridge to be
created by nomad for allocations running with bridge networking mode on the
client.
- `bridge_network_subnet` `(string: "172.26.66.0/23")` - Specifies the subnet
which the client will use to allocate IP addresses from.
- `template` <code>([Template](#template-parameters): nil)</code> - Specifies
controls on the behavior of task
[`template`](/docs/job-specification/template) stanzas.
- `host_volume` <code>([host_volume](#host_volume-stanza): nil)</code> - Exposes
paths from the host as volumes that can be mounted into jobs.
- `host_network` <code>([host_network](#host_network-stanza): nil)</code> - Registers
additional host networks with the node that can be selected when port mapping.
### `chroot_env` Parameters
Drivers based on [isolated fork/exec](/docs/drivers/exec) implement file
system isolation using chroot on Linux. The `chroot_env` map allows the chroot
environment to be configured using source paths on the host operating system.
The mapping format is:
```text
source_path -> dest_path
```
The following example specifies a chroot which contains just enough to run the
`ls` utility:
```hcl
client {
chroot_env {
"/bin/ls" = "/bin/ls"
"/etc/ld.so.cache" = "/etc/ld.so.cache"
"/etc/ld.so.conf" = "/etc/ld.so.conf"
"/etc/ld.so.conf.d" = "/etc/ld.so.conf.d"
"/etc/passwd" = "/etc/passwd"
"/lib" = "/lib"
"/lib64" = "/lib64"
}
}
```
When `chroot_env` is unspecified, the `exec` driver will use a default chroot
environment with the most commonly used parts of the operating system. Please
see the [Nomad `exec` driver documentation](/docs/drivers/exec#chroot) for
the full list.
### `options` Parameters
~> Note: client configuration options for drivers will soon be deprecated. See
the [plugin stanza][plugin-stanza] documentation for more information.
The following is not an exhaustive list of options for only the Nomad
client. To find the options supported by each individual Nomad driver, please
see the [drivers documentation](/docs/drivers).
- `"driver.whitelist"` `(string: "")` - Specifies a comma-separated list of
whitelisted drivers . If specified, drivers not in the whitelist will be
disabled. If the whitelist is empty, all drivers are fingerprinted and enabled
where applicable.
```hcl
client {
options = {
"driver.whitelist" = "docker,qemu"
}
}
```
- `"driver.blacklist"` `(string: "")` - Specifies a comma-separated list of
blacklisted drivers . If specified, drivers in the blacklist will be
disabled.
```hcl
client {
options = {
"driver.blacklist" = "docker,qemu"
}
}
```
- `"env.blacklist"` `(string: see below)` - Specifies a comma-separated list of
environment variable keys not to pass to these tasks. Nomad passes the host
environment variables to `exec`, `raw_exec` and `java` tasks. If specified,
the defaults are overridden. If a value is provided, **all** defaults are
overridden (they are not merged).
```hcl
client {
options = {
"env.blacklist" = "MY_CUSTOM_ENVVAR"
}
}
```
The default list is:
```text
CONSUL_TOKEN
CONSUL_HTTP_TOKEN
VAULT_TOKEN
AWS_ACCESS_KEY_ID
AWS_SECRET_ACCESS_KEY
AWS_SESSION_TOKEN
GOOGLE_APPLICATION_CREDENTIALS
```
- `"user.blacklist"` `(string: see below)` - Specifies a comma-separated
blacklist of usernames for which a task is not allowed to run. This only
applies if the driver is included in `"user.checked_drivers"`. If a value is
provided, **all** defaults are overridden (they are not merged).
```hcl
client {
options = {
"user.blacklist" = "root,ubuntu"
}
}
```
The default list is:
```text
root
Administrator
```
- `"user.checked_drivers"` `(string: see below)` - Specifies a comma-separated
list of drivers for which to enforce the `"user.blacklist"`. For drivers using
containers, this enforcement is usually unnecessary. If a value is provided,
**all** defaults are overridden (they are not merged).
```hcl
client {
options = {
"user.checked_drivers" = "exec,raw_exec"
}
}
```
The default list is:
```text
exec
qemu
java
```
- `"fingerprint.whitelist"` `(string: "")` - Specifies a comma-separated list of
whitelisted fingerprinters. If specified, any fingerprinters not in the
whitelist will be disabled. If the whitelist is empty, all fingerprinters are
used.
```hcl
client {
options = {
"fingerprint.whitelist" = "network"
}
}
```
- `"fingerprint.blacklist"` `(string: "")` - Specifies a comma-separated list of
blacklisted fingerprinters. If specified, any fingerprinters in the blacklist
will be disabled.
```hcl
client {
options = {
"fingerprint.blacklist" = "network"
}
}
```
- `"fingerprint.network.disallow_link_local"` `(string: "false")` - Specifies
whether the network fingerprinter should ignore link-local addresses in the
case that no globally routable address is found. The fingerprinter will always
prefer globally routable addresses.
```hcl
client {
options = {
"fingerprint.network.disallow_link_local" = "true"
}
}
```
### `reserved` Parameters
- `cpu` `(int: 0)` - Specifies the amount of CPU to reserve, in MHz.
- `memory` `(int: 0)` - Specifies the amount of memory to reserve, in MB.
- `disk` `(int: 0)` - Specifies the amount of disk to reserve, in MB.
- `reserved_ports` `(string: "")` - Specifies a comma-separated list of ports to
reserve on all fingerprinted network devices. Ranges can be specified by using
a hyphen separated the two inclusive ends.
### `template` Parameters
- `function_denylist` `([]string: ["plugin"])` - Specifies a list of template
rendering functions that should be disallowed in job specs. By default the
`plugin` function is disallowed as it allows running arbitrary commands on
the host as root (unless Nomad is configured to run as a non-root user).
- `disable_file_sandbox` `(bool: false)` - Allows templates access to arbitrary
files on the client host via the `file` function. By default templates can
access files only within the task directory.
### `host_volume` Stanza
The `host_volume` stanza is used to make volumes available to jobs.
The key of the stanza corresponds to the name of the volume for use in the
`source` parameter of a `"host"` type [`volume`](/docs/job-specification/volume)
and ACLs.
```hcl
client {
host_volume "ca-certificates" {
path = "/etc/ssl/certs"
read_only = true
}
}
```
#### `host_volume` Parameters
- `path` `(string: "", required)` - Specifies the path on the host that should
be used as the source when this volume is mounted into a task. The path must
exist on client startup.
- `read_only` `(bool: false)` - Specifies whether the volume should only ever be
allowed to be mounted `read_only`, or if it should be writeable.
### `host_network` Stanza
The `host_network` stanza is used to register additional host networks with
the node that can be used when port mapping.
The key of the stanza corresponds to the name of the network used in the
[`host_network`](/docs/job-specification/network#host-networks).
```hcl
client {
host_network "public" {
cidr = "203.0.113.0/24"
reserved_ports = "22,80"
}
}
```
#### `host_network` Parameters
- `cidr` `(string: "")` - Specifies a cidr block of addresses to match against.
If an address is found on the node that is contained by this cidr block, the
host network will be registered with it.
- `interface` `(string: "")` - Filters searching of addresses to a specific interface.
- `reserved_ports` `(string: "")` - Specifies a comma-separated list of ports to
reserve on all fingerprinted network devices. Ranges can be specified by using
a hyphen separating the two inclusive ends.
## `client` Examples
### Common Setup
This example shows the most basic configuration for a Nomad client joined to a
cluster.
```hcl
client {
enabled = true
server_join {
retry_join = [ "1.1.1.1", "2.2.2.2" ]
retry_max = 3
retry_interval = "15s"
}
}
```
### Reserved Resources
This example shows a sample configuration for reserving resources to the client.
This is useful if you want to allocate only a portion of the client's resources
to jobs.
```hcl
client {
enabled = true
reserved {
cpu = 500
memory = 512
disk = 1024
reserved_ports = "22,80,8500-8600"
}
}
```
### Custom Metadata, Network Speed, and Node Class
This example shows a client configuration which customizes the metadata, network
speed, and node class. The scheduler can use this information while processing
[constraints][metadata_constraint]. The metadata is completely user configurable;
the values below are for illustrative purposes only.
```hcl
client {
enabled = true
network_speed = 500
node_class = "prod"
meta {
"owner" = "ops"
"cached_binaries" = "redis,apache,nginx,jq,cypress,nodejs"
"rack" = "rack-12-1"
}
}
```
[plugin-options]: #plugin-options
[plugin-stanza]: /docs/configuration/plugin
[server-join]: /docs/configuration/server_join 'Server Join'
[metadata_constraint]: /docs/job-specification/constraint#user-specified-metadata 'Nomad User-Specified Metadata Constraint Example'
Reference in New Issue View Git Blame Copy Permalink