luxolus/open-nomad
2
0
Fork 0
Code Issues 1 Pull requests Packages Releases Wiki Activity
open-nomad/website/content/docs/configuration/client.mdx
Luiz Aoqui f4bf4528a1
docs: networking (#15358) 
Co-authored-by: Charlie Voiselle <464492+angrycub@users.noreply.github.com>
2023-01-06 11:47:10 -05:00

647 lines
24 KiB
Plaintext
Raw Blame History

---
layout: docs
page_title: client Stanza - Agent Configuration
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"]
}
```
## `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. This value support [go-sockaddr/template
format][go-sockaddr/template].
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.
- `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.
- `min_dynamic_port` `(int:20000)` - Specifies the minimum dynamic port to be
assigned. Individual ports and ranges of ports may be excluded from dynamic
port assignment via [`reserved`](#reserved-parameters) parameters.
- `max_dynamic_port` `(int:32000)` - Specifies the maximum dynamic port to be
assigned. Individual ports and ranges of ports may be excluded from dynamic
port assignment via [`reserved`](#reserved-parameters) parameters.
- `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, a value equal to 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. Filenames should use the `.conflist` extension. Filenames with
the `.conf` or `.json` extensions are loaded as individual plugin
configuration.
- `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.64.0/20")` - Specifies the subnet
which the client will use to allocate IP addresses from.
- `artifact` <code>([Artifact](#artifact-parameters): varied)</code> -
Specifies controls on the behavior of task
[`artifact`](/docs/job-specification/artifact) stanzas.
- `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.
- `cgroup_parent` `(string: "/nomad")` - Specifies the cgroup parent for which cgroup
subsystems managed by Nomad will be mounted under. Currently this only applies to the
`cpuset` subsystems. This field is ignored on non Linux platforms.
### `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.
As of Nomad 1.2, Nomad will never attempt to embed the `alloc_dir` in the
chroot as doing so would cause infinite recursion.
### `options` Parameters
~> Note: In Nomad 0.9 client configuration options for drivers were 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.allowlist"` `(string: "")` - Specifies a comma-separated list of
allowlisted drivers . If specified, drivers not in the allowlist will be
disabled. If the allowlist is empty, all drivers are fingerprinted and enabled
where applicable.
```hcl
client {
options = {
"driver.allowlist" = "docker,qemu"
}
}
```
- `"driver.denylist"` `(string: "")` - Specifies a comma-separated list of
denylisted drivers . If specified, drivers in the denylist will be
disabled.
```hcl
client {
options = {
"driver.denylist" = "docker,qemu"
}
}
```
- `"env.denylist"` `(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.denylist" = "MY_CUSTOM_ENVVAR"
}
}
```
The default list is:
```text
CONSUL_TOKEN
CONSUL_HTTP_TOKEN
VAULT_TOKEN
NOMAD_LICENSE
AWS_ACCESS_KEY_ID
AWS_SECRET_ACCESS_KEY
AWS_SESSION_TOKEN
GOOGLE_APPLICATION_CREDENTIALS
```
- `"user.denylist"` `(string: see below)` - Specifies a comma-separated
denylist 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.denylist" = "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.denylist"`. 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.allowlist"` `(string: "")` - Specifies a comma-separated list of
allowlisted fingerprinters. If specified, any fingerprinters not in the
allowlist will be disabled. If the allowlist is empty, all fingerprinters are
used.
```hcl
client {
options = {
"fingerprint.allowlist" = "network"
}
}
```
- `"fingerprint.denylist"` `(string: "")` - Specifies a comma-separated list of
denylisted fingerprinters. If specified, any fingerprinters in the denylist
will be disabled.
```hcl
client {
options = {
"fingerprint.denylist" = "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.
- `cores` `(int: 0)` - Specifies the number of CPU cores to reserve.
- `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 separating the two inclusive ends. See also
[`host_network`](#host_network-stanza) for reserving ports on specific host
networks.
### `artifact` Parameters
- `http_read_timeout` `(string: "30m")` - Specifies the maximum duration in
which an HTTP download request must complete before it is canceled. Set to
`0` to not enforce a limit.
- `http_max_size` `(string: "100GB")` - Specifies the maximum size allowed for
artifacts downloaded via HTTP. Set to `0` to not enforce a limit.
- `gcs_timeout` `(string: "30m")` - Specifies the maximum duration in which a
Google Cloud Storate operation must complete before it is canceled. Set to
`0` to not enforce a limit.
- `git_timeout` `(string: "30m")` - Specifies the maximum duration in which a
Git operation must complete before it is canceled. Set to `0` to not enforce
a limit.
- `hg_timeout` `(string: "30m")` - Specifies the maximum duration in which a
Mercurial operation must complete before it is canceled. Set to `0` to not
enforce a limit.
- `s3_timeout` `(string: "30m")` - Specifies the maximum duration in which an
S3 operation must complete before it is canceled. Set to `0` to not enforce a
limit.
- `disable_filesystem_isolation` `(bool: false)` - Specifies whether filesystem
isolation should be disabled for artifact downloads. Applies only to systems
where filesystem isolation via [landlock] is possible (Linux kernel 5.13+).
- `set_environment_variables` `(string:"")` - Specifies a comma separated list
of environment variables that should be inherited by the artifact sandbox from
the Nomad client's environment. By default a minimal environment is set including
a `PATH` appropriate for the operating system.
### `template` Parameters
- `function_denylist` `([]string: ["plugin", "writeToFile"])` - Specifies a
list of template rendering functions that should be disallowed in job specs.
By default the `plugin` and `writeToFile` functions are disallowed as they
allow unrestricted root access to the host.
- `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 working directory].
- `max_stale` `(string: "87600h")` - This is the maximum interval to allow "stale"
data. If `max_stale` is set to `0`, only the Consul leader will respond to queries, and
requests that reach a follower will forward to the leader. In large clusters with
many requests, this is not as scalable. This option allows any follower to respond
to a query, so long as the last-replicated data is within this bound. Higher values
result in less cluster load, but are more likely to have outdated data. This default
of 10 years (`87600h`) matches the default Consul configuration.
- `wait` `(map: { min = "5s" max = "4m" })` - Defines the minimum and maximum amount
of time to wait before attempting to re-render a template. Consul Template re-renders
templates whenever rendered variables from Consul, Nomad, or Vault change. However in
order to minimize how often tasks are restarted or reloaded, Nomad will configure Consul
Template with a backoff timer that will tick on an interval equal to the specified `min`
value. Consul Template will always wait at least the as long as the `min` value specified.
If the underlying data has not changed between two tick intervals, Consul Template will
re-render. If the underlying data has changed, Consul Template will delay re-rendering
until the underlying data stabilizes for at least one tick interval, or the configured
`max` duration has elapsed. Once the `max` duration has elapsed, Consul Template will
re-render the template with the data available at the time. This is useful to enable in
systems where Consul is in a degraded state, or the referenced data values are changing
rapidly, because it will reduce the number of times a template is rendered. This
configuration is also exposed in the _task template stanza_ to allow overrides per task.
```hcl
wait {
min = "5s"
max = "4m"
}
```
- `wait_bounds` `(map: nil)` - Defines client level lower and upper bounds for
per-template `wait` configuration. If the individual template configuration has
a `min` lower than `wait_bounds.min` or a `max` greater than the `wait_bounds.max`,
the bounds will be enforced, and the template `wait` will be adjusted before being
sent to `consul-template`.
```hcl
wait_bounds {
min = "5s"
max = "10s"
}
```
- `block_query_wait` `(string: "5m")` - This is amount of time in seconds to wait
for the results of a blocking query. Many endpoints in Consul support a feature known as
"blocking queries". A blocking query is used to wait for a potential change
using long polling.
- `consul_retry` `(map: { attempts = 0 backoff = "250ms" max_backoff = "1m" })`-
This controls the retry behavior when an error is returned from Consul. The template
runner will not exit in the face of failure. Instead, it uses exponential back-off
and retry functions to wait for the Consul cluster to become available, as is
customary in distributed systems.
```hcl
consul_retry {
# This specifies the number of attempts to make before giving up. Each
# attempt adds the exponential backoff sleep time. Setting this to
# zero will implement an unlimited number of retries.
attempts = 0
# This is the base amount of time to sleep between retry attempts. Each
# retry sleeps for an exponent of 2 longer than this base. For 5 retries,
# the sleep times would be: 250ms, 500ms, 1s, 2s, then 4s.
backoff = "250ms"
# This is the maximum amount of time to sleep between retry attempts.
# When max_backoff is set to zero, there is no upper limit to the
# exponential sleep between retry attempts.
# If max_backoff is set to 10s and backoff is set to 1s, sleep times
# would be: 1s, 2s, 4s, 8s, 10s, 10s, ...
max_backoff = "1m"
}
```
- `vault_retry` `(map: { attempts = 0 backoff = "250ms" max_backoff = "1m" })` -
This controls the retry behavior when an error is returned from Vault. Consul
Template is highly fault tolerant, meaning it does not exit in the face of failure.
Instead, it uses exponential back-off and retry functions to wait for the cluster
to become available, as is customary in distributed systems.
```hcl
vault_retry {
# This specifies the number of attempts to make before giving up. Each
# attempt adds the exponential backoff sleep time. Setting this to
# zero will implement an unlimited number of retries.
attempts = 0
# This is the base amount of time to sleep between retry attempts. Each
# retry sleeps for an exponent of 2 longer than this base. For 5 retries,
# the sleep times would be: 250ms, 500ms, 1s, 2s, then 4s.
backoff = "250ms"
# This is the maximum amount of time to sleep between retry attempts.
# When max_backoff is set to zero, there is no upper limit to the
# exponential sleep between retry attempts.
# If max_backoff is set to 10s and backoff is set to 1s, sleep times
# would be: 1s, 2s, 4s, 8s, 10s, 10s, ...
max_backoff = "1m"
}
```
- `nomad_retry` `(map: { attempts = 0 backoff = "250ms" max_backoff = "1m" })` -
This controls the retry behavior when an error is returned from Nomad. Consul
Template is highly fault tolerant, meaning it does not exit in the face of failure.
Instead, it uses exponential back-off and retry functions to wait for the cluster
to become available, as is customary in distributed systems.
```hcl
nomad_retry {
# This specifies the number of attempts to make before giving up. Each
# attempt adds the exponential backoff sleep time. Setting this to
# zero will implement an unlimited number of retries.
attempts = 0
# This is the base amount of time to sleep between retry attempts. Each
# retry sleeps for an exponent of 2 longer than this base. For 5 retries,
# the sleep times would be: 250ms, 500ms, 1s, 2s, then 4s.
backoff = "250ms"
# This is the maximum amount of time to sleep between retry attempts.
# When max_backoff is set to zero, there is no upper limit to the
# exponential sleep between retry attempts.
# If max_backoff is set to 10s and backoff is set to 1s, sleep times
# would be: 1s, 2s, 4s, 8s, 10s, 10s, ...
max_backoff = "1m"
}
```
### `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 addresses associated with this network. Ranges can be specified by using
a hyphen separating the two inclusive ends.
[`reserved.reserved_ports`](#reserved_ports) are also reserved on each host
network.
## `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
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'
[task working directory]: /docs/runtime/environment#task-directories 'Task directories'
[go-sockaddr/template]: https://godoc.org/github.com/hashicorp/go-sockaddr/template
[landlock]: https://docs.kernel.org/userspace-api/landlock.html
Reference in a new issue View git blame Copy permalink