How the Nomad calculator works

01 What the two settings do

• memory is the memory the task requires, in MB. Without memory_max it is also the hard limit. Nomad docs
• memory_max is the most the task may use when its client has memory to spare. With it set, memory becomes the reservation and memory_max the hard limit. Nomad docs

Nomad's own advice matches the shared model: set memory to the task's typical usage and memory_max to absorb unexpected load spikes. Nomad docs So the calculator sizes memory from the average and memory_max from the peak.

In Kubernetes, requests and limits play comparable roles; the Kubernetes guide sizes them the same way, from the average and the peak.

02 memory and memory_max

memory     = max(average × (1 + request margin), 10)     rounded up to a whole MB
memory_max = max(peak × (1 + limit margin), memory)       rounded up to a whole MB

The margins come from the sensitivity, workload type and environment you choose; the sizing model explains them, and they are assumptions too.

• Nomad's MB are mebibytes: it converts them to bytes with 1024 × 1024, so MiB values pass through unchanged. Nomad source
• Nomad rejects a task with less than 10 MB of memory, or with memory_max below memory, so the result is raised to whichever applies. Nomad source

Worked example

Average 410 MiB, peak 630 MiB, generic workload, medium sensitivity, production, a group count of 3:

When the peak is close to the average, memory can decide memory_max. Average 1000 MiB and peak 1010 MiB, high sensitivity:

03 Memory oversubscription

memory_max only works when memory oversubscription is enabled in the scheduler configuration. It's off by default and enabled once per cluster: Nomad docs

nomad operator scheduler set-config -memory-oversubscription=true

Without it, memory is the hard limit, so a task sized here would be killed at its average-based value. The note under the result says to set memory to the memory_max value in that case. Assumption

Nomad also advises keeping an eye on memory use and leaving enough reserved memory on each client, because oversubscribed tasks can run a client out of memory. Nomad docs

04 Every warning, and why

05 What to paste

nomad_client_allocs_memory_usage{job="web", task="api"}

• Nomad publishes allocation metrics when telemetry has publish_allocation_metrics on, and serves them in Prometheus format at /v1/metrics?format=prometheus with prometheus_metrics on. Nomad docs
• nomad.client.allocs.memory.usage is a gauge of the total memory a task uses, in bytes, labelled with job, task_group, task and alloc_id, among others. Filtering by both job and task keeps another job's task of the same name out. Nomad docs
• Total usage includes file cache. Nomad also reports rss and cache separately, but RSS leaves out memory the task does need, so the calculator sizes from total usage and errs on the high side. Assumption

06 All assumptions in one place

Besides the margins of the shared sizing model:

Our default: a value we chose. Our reading: how we read documentation that isn't explicit. About your setup: something we take for granted about your data or cluster.

Values you can change

The calculator’s Advanced: margins and defaults section, closed by default, lets you replace these values when your setup differs. Each field’s “?” says how it moves the result; a value outside the range is used at its nearest end, and “Reset to defaults” puts them all back.

07 References

• resources block — memory, memory_max and how to choose them.
• nomad operator scheduler set-config — enabling memory oversubscription.
• Telemetry configuration — publish_allocation_metrics and prometheus_metrics.
• Metrics reference — nomad.client.allocs.memory.*.
• Nomad source: structs.go — MB to bytes, the 10 MB minimum and memory_max ≥ memory.

← Back to the Nomad calculator