From ebc3d9b9ca10c3c0be513cc439ef0df1b6358355 Mon Sep 17 00:00:00 2001 From: Chris Bednarski Date: Wed, 23 Sep 2015 14:58:25 -0700 Subject: [PATCH] Added docs for runtime environment --- .../source/docs/jobspec/environment.html.md | 73 +++++++++++++++++++ website/source/layouts/docs.erb | 5 ++ 2 files changed, 78 insertions(+) create mode 100644 website/source/docs/jobspec/environment.html.md diff --git a/website/source/docs/jobspec/environment.html.md b/website/source/docs/jobspec/environment.html.md new file mode 100644 index 000000000..440642561 --- /dev/null +++ b/website/source/docs/jobspec/environment.html.md @@ -0,0 +1,73 @@ +--- +layout: "docs" +page_title: "Runtime Environment" +sidebar_current: "docs-jobspec-environment" +description: |- + Learn how to configure the Nomad runtime environment. +--- + +# Runtime Environment + +Some settings you specify in your [jobspec](/docs/jobspec/) are passed to tasks +when they start. Also, some settings are dynamically allocated when your job is +scheduled. Both types of values are made available to your job through +environment variables. + +## Resources + +When you request resources for a job, Nomad creates a resource offer. The final +resources for your job are not determined until it is scheduled. Nomad will +tell you which resources + +### CPU and Memory + +Nomad will pass CPU and memory to your job as `NOMAD_CPU_LIMIT` and +`NOMAD_MEMORY_LIMIT`. Your task should use these values to adapt its behavior to +fit inside the resource allocation that nomad provides. For example, you can use +the memory limit to inform how large your in-process cache should be, or to +decide when to flush buffers to disk. + +Both CPU and memory are presented as integers. The unit for CPU limit is `1024 = 1Ghz`. The unit for memory is megabytes. + +Writing your applications to adjust to these values at runtime provides greater +scheduling flexibility since you can adjust the resource allocations in your +jobspec without needing to change your code. You can also schedule workloads that +use dynamic resource allocations so they can scale down/up as your cluster gets +more or less busy. + +### IPs and Named Ports + +Each task will receive port allocations on a single IP address. The IP is made +available through `NOMAD_IP.` + +If you requested reserved ports in your jobspec and your task is successfully scheduled, these ports are available for your use. Ports from `reserved_ports` in the job spec +are not exposed through the environment. If you requested dynamic ports in your +jobspec these are made known to your application via environment variables +`NOMAD_PORT_{LABEL}`. For example `dynamic_ports = ["http"]` becomes +`NOMAD_PORT_HTTP`. + +Some drivers such as Docker and QEMU use port mapping. With port mapping the +application code can run on a fixed port and nomad will automatically map a +random allocated port in the driver. In this case, you should use numeric port +labels to indicate which ports are exposed in your container or VM. For example +with `dynamic_ports = ["5000"]` Docker will automatically map the allocated host +port to port 5000 in the container. + +Even with automatic port mapping, numeric ports are also exported via +environment variables such as `NOMAD_PORT_5000` so you can use these with +drivers that do not support port mapping. You may also be able to use named +ports if you want to bind to a dynamic port inside a container or VM. + +Please see the relevant driver documentation for exact details. + +## Meta + +The jobspec also allows you to specify a `meta` block to supply arbitrary +configuration to a task. This allows you to easily provide job-specific +configuration even if you use the same executable unit in multiple jobs. These +key-value pairs are passed through to the job as `NOMAD_META_{KEY}={value}`, +where `key` is UPPERCASED from the jobspec. + +Currently there is no enforcement that the meta values be lowercase, but using +multiple keys with the same uppercased representation will lead to undefined +behavior. diff --git a/website/source/layouts/docs.erb b/website/source/layouts/docs.erb index 7bedde384..7c6b1db6e 100644 --- a/website/source/layouts/docs.erb +++ b/website/source/layouts/docs.erb @@ -34,6 +34,11 @@ > Job Specification + >