102 lines
4.4 KiB
Plaintext
102 lines
4.4 KiB
Plaintext
---
|
|
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
|
|
|
|
<%= partial "envvars.html.md" %>
|
|
|
|
~> Port labels and task names will have any non-alphanumeric or underscore
|
|
characters 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, group and
|
|
job's names. These are given as `NOMAD_ALLOC_ID`, `NOMAD_ALLOC_NAME`,
|
|
`NOMAD_ALLOC_INDEX`, `NOMAD_JOB_NAME`, `NOMAD_GROUP_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"
|