175 lines
6.1 KiB
Markdown
175 lines
6.1 KiB
Markdown
---
|
|
layout: "docs"
|
|
page_title: "Environment - Runtime"
|
|
sidebar_current: "docs-runtime-environment"
|
|
description: |-
|
|
Learn how to configure the Nomad runtime environment.
|
|
---
|
|
|
|
# Runtime Environment
|
|
|
|
Some settings you specify in your [job specification][jobspec] are passed
|
|
to tasks when they start. Other settings are dynamically allocated when your job
|
|
is scheduled. Both types of values are made available to your job through
|
|
environment variables.
|
|
|
|
## Summary
|
|
|
|
<table class="table table-bordered table-striped">
|
|
<tr>
|
|
<th>Variable</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
<tr>
|
|
<td>`NOMAD_ALLOC_DIR`</td>
|
|
<td>Path to the shared alloc directory</td>
|
|
</tr>
|
|
<tr>
|
|
<td>`NOMAD_TASK_DIR`</td>
|
|
<td>Path to the local task directory</td>
|
|
</tr>
|
|
<tr>
|
|
<td>`NOMAD_SECRETS_DIR`</td>
|
|
<td>Path to the task's secrets directory</td>
|
|
</tr>
|
|
<tr>
|
|
<td>`NOMAD_MEMORY_LIMIT`</td>
|
|
<td>The task's memory limit in MB</td>
|
|
</tr>
|
|
<tr>
|
|
<td>`NOMAD_CPU_LIMIT`</td>
|
|
<td>The task's CPU limit in MHz</td>
|
|
</tr>
|
|
<tr>
|
|
<td>`NOMAD_ALLOC_ID`</td>
|
|
<td>The allocation ID of the task</td>
|
|
</tr>
|
|
<tr>
|
|
<td>`NOMAD_ALLOC_NAME`</td>
|
|
<td>The allocation name of the task</td>
|
|
</tr>
|
|
<tr>
|
|
<td>`NOMAD_ALLOC_INDEX`</td>
|
|
<td>The allocation index; useful to distinguish instances of task groups</td>
|
|
</tr>
|
|
<tr>
|
|
<td>`NOMAD_TASK_NAME`</td>
|
|
<td>The task's name</td>
|
|
</tr>
|
|
<tr>
|
|
<td>`NOMAD_JOB_NAME`</td>
|
|
<td>The job's name</td>
|
|
</tr>
|
|
<tr>
|
|
<td>`NOMAD_IP_<label>`</td>
|
|
<td>The IP of the port with the given label</td>
|
|
</tr>
|
|
<tr>
|
|
<td>`NOMAD_PORT_<label>`</td>
|
|
<td>The port value with the given label</td>
|
|
</tr>
|
|
<tr>
|
|
<td>`NOMAD_ADDR_<label>`</td>
|
|
<td>The IP:Port pair of the port with the given label</td>
|
|
</tr>
|
|
<tr>
|
|
<td>`NOMAD_ADDR_<task>_<label`></td>
|
|
<td>The allocated address, given as IP:Port for the given label of other tasks in the same group</td>
|
|
</tr>
|
|
<tr>
|
|
<td>`NOMAD_HOST_PORT_<label>`</td>
|
|
<td>The host port for the given label if the port is port mapped</td>
|
|
</tr>
|
|
<tr>
|
|
<td>`NOMAD_META_<key>`</td>
|
|
<td>The metadata of the task</td>
|
|
</tr>
|
|
<tr>
|
|
<td>`VAULT_TOKEN`</td>
|
|
<td>The task's Vault token. See [Vault Integration](/docs/vault-integration/index.html) for more details</td>
|
|
</tr>
|
|
</table>
|
|
|
|
Port labels and task names will have any dashes `-` in their names replaced by
|
|
underscores `_` when they're used in environment variable names such as
|
|
`NOMAD_ADDR_<task>_<label>`.
|
|
|
|
## Task Identifiers
|
|
|
|
Nomad will pass both the allocation ID and name as well as the task and job's
|
|
names. These are given as `NOMAD_ALLOC_ID`, `NOMAD_ALLOC_NAME`,
|
|
`NOMAD_ALLOC_INDEX`, `NOMAD_JOB_NAME`, and `NOMAD_TASK_NAME`. The allocation ID
|
|
and index can be useful when the task being run needs a unique identifier or to
|
|
know its instance count.
|
|
|
|
## 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 have been allocated after evaluation and placement.
|
|
|
|
### CPU and Memory
|
|
|
|
Nomad will pass CPU and memory limits 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 `1 = 1 megabyte`.
|
|
|
|
Writing your applications to adjust to these values at runtime provides greater
|
|
scheduling flexibility since you can adjust the resource allocations in your
|
|
job specification without needing to change your code. You can also schedule workloads
|
|
that accept dynamic resource allocations so they can scale down/up as your
|
|
cluster gets more or less busy.
|
|
|
|
### Networking
|
|
|
|
Nomad assigns IPs and ports to your jobs and exposes them via environment
|
|
variables. See the [Networking](/docs/job-specification/network.html) page for more
|
|
details.
|
|
|
|
### Task Directories
|
|
|
|
Nomad makes the following directories available to tasks:
|
|
|
|
* `alloc/`: This directory is shared across all tasks in a task group and can be
|
|
used to store data that needs to be used by multiple tasks, such as a log
|
|
shipper.
|
|
* `local/`: This directory is private to each task. It can be used to store
|
|
arbitrary data that should not be shared by tasks in the task group.
|
|
* `secrets/`: This directory is private to each task, not accessible via the
|
|
`nomad fs` command or filesystem APIs and where possible backed by an
|
|
in-memory filesystem. It can be used to store secret data that should not be
|
|
visible outside the task.
|
|
|
|
These directories are persisted until the allocation is removed, which occurs
|
|
hours after all the tasks in the task group enter terminal states. This gives
|
|
time to view the data produced by tasks.
|
|
|
|
Depending on the driver and operating system being targeted, the directories are
|
|
made available in various ways. For example, on `docker` the directories are
|
|
bound to the container, while on `exec` on Linux the directories are mounted into the
|
|
chroot. Regardless of how the directories are made available, the path to the
|
|
directories can be read through the `NOMAD_ALLOC_DIR`, `NOMAD_TASK_DIR`, and
|
|
`NOMAD_SECRETS_DIR` environment variables.
|
|
|
|
## Meta
|
|
|
|
The job specification 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>`
|
|
environment variables. Prior to Nomad 0.5.5 the key was uppercased and since
|
|
then both the original case and an uppercased version are injected. The
|
|
uppercased version will be deprecated in a future release.
|
|
|
|
Currently there is no enforcement that the meta keys be lowercase, but using
|
|
multiple keys with the same uppercased representation will lead to undefined
|
|
behavior.
|
|
|
|
[jobspec]: /docs/job-specification/index.html "Nomad Job Specification"
|
|
[vault]: /docs/vault-integration/index.html "Nomad Vault Integration"
|