diff --git a/website/content/docs/drivers/docker.mdx b/website/content/docs/drivers/docker.mdx index bcdffb1a2..c2b4919e0 100644 --- a/website/content/docs/drivers/docker.mdx +++ b/website/content/docs/drivers/docker.mdx @@ -1132,12 +1132,17 @@ Nomad limits containers' CPU based on CPU shares. CPU shares allow containers to burst past their CPU limits. CPU limits will only be imposed when there is contention for resources. When the host is under load your process may be throttled to stabilize QoS depending on how many shares it has. You can see how -many CPU shares are available to your process by reading `NOMAD_CPU_LIMIT`. +many CPU shares are available to your process by reading [`NOMAD_CPU_LIMIT`][runtime_env]. 1000 shares are approximately equal to 1 GHz. Please keep the implications of CPU shares in mind when you load test workloads on Nomad. +If resources [`cores`][cores] is set, the task is given an isolated reserved set of +CPU cores to make use of. The total set of cores the task may run on is the private +set combined with the variable set of unreserved cores. The private set of CPU cores +is available to your process by reading [`NOMAD_CPU_CORES`][runtime_env]. + ### Memory Nomad limits containers' memory usage based on total virtual memory. This means @@ -1148,7 +1153,7 @@ host. Since memory is not an elastic resource, you will need to make sure your container does not exceed the amount of memory allocated to it, or it will be terminated or crash when it tries to malloc. A process can inspect its memory -limit by reading `NOMAD_MEMORY_LIMIT`, but will need to track its own memory +limit by reading [`NOMAD_MEMORY_LIMIT`][runtime_env], but will need to track its own memory usage. Memory limit is expressed in megabytes so 1024 = 1 GB. ### IO @@ -1213,3 +1218,5 @@ Windows is relatively new and rapidly evolving you may want to consult the [network block]: /nomad/docs/job-specification/network#bridge-mode [`pids_limit`]: /nomad/docs/drivers/docker#pids_limit [Windows isolation]: https://learn.microsoft.com/en-us/virtualization/windowscontainers/manage-containers/hyperv-container +[cores]: /nomad/docs/job-specification/resources#cores +[runtime_env]: /nomad/docs/runtime/environment#job-related-variables \ No newline at end of file diff --git a/website/content/docs/drivers/exec.mdx b/website/content/docs/drivers/exec.mdx index 271095cce..9c37261a9 100644 --- a/website/content/docs/drivers/exec.mdx +++ b/website/content/docs/drivers/exec.mdx @@ -246,6 +246,21 @@ create. This list is configurable through the agent client [configuration file](/nomad/docs/configuration/client#chroot_env). +### CPU + +Nomad limits exec tasks' CPU based on CPU shares. CPU shares allow containers to +burst past their CPU limits. CPU limits will only be imposed when there is contention +for resources. When the host is under load your process may be throttled to stabilize +QoS depending on how many shares it has. You can see how many CPU shares are available +to your process by reading [`NOMAD_CPU_LIMIT`][runtime_env]. 1000 shares are approximately equal to 1 GHz. + +Please keep the implications of CPU shares in mind when you load test workloads on Nomad. + +If resources [`cores`][cores] is set, the task is given an isolated reserved set of +CPU cores to make use of. The total set of cores the task may run on is the private +set combined with the variable set of unreserved cores. The private set of CPU cores +is available to your process by reading [`NOMAD_CPU_CORES`][runtime_env]. + [default_pid_mode]: /nomad/docs/drivers/exec#default_pid_mode [default_ipc_mode]: /nomad/docs/drivers/exec#default_ipc_mode [cap_add]: /nomad/docs/drivers/exec#cap_add @@ -255,3 +270,5 @@ This list is configurable through the agent client [docker_caps]: https://docs.docker.com/engine/reference/run/#runtime-privilege-and-linux-capabilities [host volume]: /nomad/docs/configuration/client#host_volume-block [volume_mount]: /nomad/docs/job-specification/volume_mount +[cores]: /nomad/docs/job-specification/resources#cores +[runtime_env]: /nomad/docs/runtime/environment#job-related-variables diff --git a/website/content/docs/job-specification/resources.mdx b/website/content/docs/job-specification/resources.mdx index 72e12ea0f..3e2be15ac 100644 --- a/website/content/docs/job-specification/resources.mdx +++ b/website/content/docs/job-specification/resources.mdx @@ -34,12 +34,15 @@ job "docs" { - `cpu` `(int: 100)` - Specifies the CPU required to run this task in MHz. -- `cores` (`int`: <optional>) 1.1 Beta - Specifies the number of CPU cores to reserve - for the task. This may not be used with `cpu`. +- `cores` (`int`: <optional>) - Specifies the number of CPU cores + to reserve specifically for the task. This may not be used with `cpu`. The behavior + of setting `cores` is specific to each task driver (e.g. [docker][docker_cpu], [exec][exec_cpu]). - `memory` `(int: 300)` - Specifies the memory required in MB. -- `memory_max` (`int`: <optional>) 1.1 Beta - Optionally, specifies the maximum memory the task may use, if the client has excess memory capacity, in MB. See [Memory Oversubscription](#memory-oversubscription) for more details. +- `memory_max` (`int`: <optional>) - Optionally, specifies the + maximum memory the task may use, if the client has excess memory capacity, in MB. + See [Memory Oversubscription](#memory-oversubscription) for more details. - `device` ([Device][]: <optional>) - Specifies the device requirements. This may be repeated to request multiple device types. @@ -134,3 +137,5 @@ resource utilization and considering the following suggestions: killed. [device]: /nomad/docs/job-specification/device 'Nomad device Job Specification' +[docker_cpu]: /nomad/docs/drivers/docker#cpu +[exec_cpu]: /nomad/docs/drivers/exec#cpu