mirror of
https://github.com/kemko/nomad.git
synced 2026-01-01 16:05:42 +03:00
217 lines
7.0 KiB
Plaintext
217 lines
7.0 KiB
Plaintext
---
|
|
layout: docs
|
|
page_title: Raw Fork/Exec task driver
|
|
description: Nomad's Raw Exec task driver lets you execute commands with no resource isolation. Learn how to use the Raw Fork/Exec task driver in your jobs. Configure the command to execute, command arguments, cgroup overrides, work directory, and out-of-memory (OOM) behavior. Review the Isolated Fork/Exec task driver capabilities, plugin options, client requirements, and client attributes.
|
|
---
|
|
|
|
# Raw Fork/Exec task driver
|
|
|
|
Name: `raw_exec`
|
|
|
|
The `raw_exec` driver is used to execute a command for a task without any
|
|
isolation. Further, the task is started as the same user as the Nomad process.
|
|
As such, it should be used with extreme care and is disabled by default.
|
|
|
|
## Task Configuration
|
|
|
|
```hcl
|
|
task "webservice" {
|
|
driver = "raw_exec"
|
|
|
|
config {
|
|
command = "my-binary"
|
|
args = ["-flag", "1"]
|
|
}
|
|
}
|
|
```
|
|
|
|
The `raw_exec` driver supports the following configuration in the job spec:
|
|
|
|
- `command` - The command to execute. Must be provided. If executing a binary
|
|
that exists on the host, the path must be absolute. If executing a binary that
|
|
is downloaded from an [`artifact`](/nomad/docs/job-specification/artifact), the
|
|
path can be relative from the allocation's root directory.
|
|
|
|
- `args` - (Optional) A list of arguments to the `command`. References
|
|
to environment variables or any [interpretable Nomad
|
|
variables](/nomad/docs/runtime/interpolation) will be interpreted before
|
|
launching the task.
|
|
|
|
- `cgroup_v1_override` - (Optional) A map of controller names to paths. The
|
|
task will be added to these cgroups. The task will fail if these cgroups do
|
|
not exist. **WARNING:** May conflict with other Nomad driver's cgroups and
|
|
have unintended side effects.
|
|
|
|
- `cgroup_v2_override` - (Optional) Adds the task to a unified cgroup path.
|
|
Paths may be relative to the cgroupfs root or absolute. **WARNING:** May
|
|
conflict with other Nomad driver's cgroups and have unintended side
|
|
effects.
|
|
|
|
~> On Linux, you cannot set the `task.user` field on a task using the `raw_exec`
|
|
driver if you have hardened the Nomad client according to the
|
|
[production][hardening] guide. On Windows, when Nomad is running as a [system
|
|
service][service], you may specify a less-privileged service user. For example,
|
|
`NT AUTHORITY\LocalService`, `NT AUTHORITY\NetworkService`.
|
|
|
|
- `oom_score_adj` - (Optional) A positive integer to indicate the likelihood of
|
|
the task being OOM killed (valid only for Linux). Defaults to 0.
|
|
|
|
- `work_dir` - (Optional) Sets a custom working directory for the task. This
|
|
must be an absolute path. This will also change the working directory when
|
|
using `nomad alloc exec`.
|
|
|
|
- `denied_envvars` - (Optional) Passes a list of environment variables that
|
|
the driver should scrub from the task environment. Supports globbing, with "*"
|
|
wildcard accepted as prefix and/or suffix.
|
|
|
|
## Examples
|
|
|
|
To run a binary present on the Node:
|
|
|
|
```
|
|
task "example" {
|
|
driver = "raw_exec"
|
|
|
|
config {
|
|
# When running a binary that exists on the host, the path must be absolute/
|
|
command = "/bin/sleep"
|
|
args = ["1"]
|
|
}
|
|
}
|
|
```
|
|
|
|
To execute a binary downloaded from an [`artifact`](/nomad/docs/job-specification/artifact):
|
|
|
|
```
|
|
task "example" {
|
|
driver = "raw_exec"
|
|
|
|
config {
|
|
command = "name-of-my-binary"
|
|
}
|
|
|
|
artifact {
|
|
source = "https://internal.file.server/name-of-my-binary"
|
|
options {
|
|
checksum = "sha256:abd123445ds4555555555"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
## Capabilities
|
|
|
|
The `raw_exec` driver implements the following [capabilities](/nomad/docs/concepts/plugins/task-drivers#capabilities-capabilities-error).
|
|
|
|
| Feature | Implementation |
|
|
| -------------------- | -------------- |
|
|
| `nomad alloc signal` | true |
|
|
| `nomad alloc exec` | true |
|
|
| filesystem isolation | none |
|
|
| network isolation | host, group |
|
|
| volume mounting | none |
|
|
|
|
## Client Requirements
|
|
|
|
The `raw_exec` driver can run on all supported operating systems. For security
|
|
reasons, it is disabled by default. To enable raw exec, the Nomad client
|
|
configuration must explicitly enable the `raw_exec` driver in the plugin's options:
|
|
|
|
```
|
|
plugin "raw_exec" {
|
|
config {
|
|
enabled = true
|
|
}
|
|
}
|
|
```
|
|
|
|
Nomad versions before v0.9 use the following client configuration. This configuration is
|
|
also supported in Nomad v0.9.0, but is deprecated in favor of the plugin block:
|
|
|
|
```
|
|
client {
|
|
options = {
|
|
"driver.raw_exec.enable" = "1"
|
|
}
|
|
}
|
|
```
|
|
|
|
## Plugin Options
|
|
|
|
- `enabled` - Specifies whether the driver should be enabled or disabled.
|
|
Defaults to `false`.
|
|
|
|
- `denied_host_uids` - (Optional) Specifies a comma-separated list of host uids to
|
|
deny. Ranges can be specified by using a hyphen separating the two inclusive ends.
|
|
If a "user" value is specified in task configuration and that user has a user id in
|
|
the given ranges, the task will error before starting. This will not be checked on Windows
|
|
clients.
|
|
|
|
```hcl
|
|
config {
|
|
denied_host_uids = "0,10-15,22"
|
|
}
|
|
```
|
|
|
|
- `denied_host_gids` - (Optional) Specifies a comma-separated list of host gids to
|
|
deny. Ranges can be specified by using a hyphen separating the two inclusive ends.
|
|
If a "user" value is specified in task configuration and that user is part of
|
|
any groups with gid's in the specified ranges, the task will error before
|
|
starting. This will not be checked on Windows clients.
|
|
|
|
```hcl
|
|
config {
|
|
denied_host_gids = "2,4-8"
|
|
}
|
|
```
|
|
|
|
- `denied_envvars` - (Optional) Passes a list of environment variables that
|
|
the driver should scrub from all task environments. Supports globbing with "*"
|
|
wildcard accepted as prefix and/or suffix.
|
|
|
|
```hcl
|
|
config {
|
|
denied_envvars = ["AWS_SECRET_KEY", "*_TOKEN"]
|
|
}
|
|
```
|
|
## Client Options
|
|
|
|
~> Note: client configuration options will soon be deprecated. Please use
|
|
[plugin options][plugin-options] instead. See the [plugin block][plugin-block] documentation for more information.
|
|
|
|
- `driver.raw_exec.enable` - Specifies whether the driver should be enabled or
|
|
disabled. Defaults to `false`.
|
|
|
|
## Client Attributes
|
|
|
|
The `raw_exec` driver will set the following client attributes:
|
|
|
|
- `driver.raw_exec` - This will be set to "1", indicating the driver is available.
|
|
|
|
## Resource Isolation
|
|
|
|
The `raw_exec` driver provides no filesystem isolation.
|
|
|
|
If the launched process creates a new process group, it is possible that
|
|
Nomad will leak processes on shutdown unless the application forwards signals
|
|
properly. Nomad will not leak any processes if cgroups are being used to
|
|
manage the process tree. Cgroups are used on Linux when Nomad is being run with
|
|
appropriate privileges, and the cgroup system is mounted.
|
|
|
|
If the cluster is configured with memory oversubscription enabled, a task using
|
|
the `raw_exec` driver can be configured to have no maximum memory limit by
|
|
setting `memory_max = -1`.
|
|
|
|
```hcl
|
|
resources {
|
|
cpu = 500
|
|
memory = 128
|
|
memory_max = -1 # no limit
|
|
}
|
|
```
|
|
|
|
[hardening]: /nomad/docs/install/production/requirements#user-permissions
|
|
[service]: /nomad/docs/install/windows-service
|
|
[plugin-options]: #plugin-options
|
|
[plugin-block]: /nomad/docs/configuration/plugin
|