luxolus
/
open-nomad
2
0
Fork 0
Code Issues 1 Pull Requests Packages Releases Wiki Activity

Add information about template to interpolation page (#10807) 

* Add information about templating using `env` function to refer to environment variables.
This commit is contained in:
Charlie Voiselle 2023-02-10 16:12:11 -05:00 committed by GitHub
parent 65ce3ec8de
commit 37a078ebce
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
6 changed files with 112 additions and 74 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
website/content/docs/job-specification/hcl2/functions/collection/flatten.mdx
View File

@ -35,7 +35,7 @@ Indirectly-nested lists, such as those in maps, are _not_ flattened.
The
[resource `for_each`](https://www.terraform.io/docs/configuration/resources.html#for_each-multiple-resource-instances-defined-by-a-map-or-set-of-strings)
and
[`dynamic` block](/docs/job-specification/hcl2/expressions#dynamic-blocks)
[`dynamic` block](/nomad/docs/job-specification/hcl2/expressions#dynamic-blocks)
language features both require a collection value that has one element for
each repetition.

2
website/content/docs/job-specification/hcl2/functions/collection/setproduct.mdx
View File

@ -122,7 +122,7 @@ elements all have a consistent type:
The
[resource `for_each`](https://www.terraform.io/docs/configuration/resources.html#for_each-multiple-resource-instances-defined-by-a-map-or-set-of-strings)
and
[`dynamic` block](/docs/job-specification/hcl2/expressions/#dynamic-blocks)
[`dynamic` block](/nomad/docs/job-specification/hcl2/expressions/#dynamic-blocks)
language features both require a collection value that has one element for
each repetition.

7
website/content/docs/runtime/environment.mdx
View File

@ -35,7 +35,7 @@ tell you which resources have been allocated after evaluation and placement.
Nomad will pass CPU and memory limits to your job as `NOMAD_CPU_LIMIT`,
`NOMAD_MEMORY_LIMIT`, and `NOMAD_MEMORY_MAX_LIMIT`. Your task should use these
values to adapt its behavior to fit inside the resource allocation that nomad
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.
@ -45,12 +45,12 @@ Both CPU and memory are presented as integers. The unit for CPU limit is
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
that accept dynamic resource allocations so they can scale up or down as your
cluster gets more or less busy.
### Networking
Nomad assigns IPs and ports to your jobs and exposes them via environment
Nomad assigns IP addresses and ports to your jobs and exposes them via environment
variables. See the [Networking](/nomad/docs/job-specification/network) page for more
details.
@ -109,6 +109,5 @@ passed to the tasks can be controlled using the client configuration
[`env.denylist`][].
[jobspec]: /nomad/docs/job-specification 'Nomad Job Specification'
[vault]: /nomad/docs/integrations/vault-integration 'Nomad Vault Integration'
[filesystem internals]: /nomad/docs/concepts/filesystem
[`env.denylist`]: /nomad/docs/configuration/client#env-denylist

2
website/content/docs/runtime/index.mdx
View File

@ -8,7 +8,7 @@ description: |-
# Runtime
This section details nomad's runtime information, including environment
This section details Nomad's runtime information, including environment
variables, interpolations, caveats, and more.
To learn more about Nomad's runtime, choose an item from the sidebar, or choose

112
website/content/docs/runtime/interpolation.mdx
View File

@ -12,8 +12,24 @@ task environment variables, and certain driver fields. Runtime environment
variables are not interpretable in constraints because they are only defined
once the scheduler has placed them on a particular node.
The syntax for interpreting variables is `${variable}`. An example and a
comprehensive list of interpretable fields can be seen below:
Nomad supports interpreting two classes of variables: [node attributes](#interpreted_node_vars)
and [runtime environment variables](#interpreted_env_vars). Node attributes are
interpretable in [constraints](/nomad/docs/job-specification/constraint),
[task environment variables](/nomad/docs/job-specification/env), and certain
task driver fields—for example the [`labels`](/nomad/docs/drivers/docker#labels)
attribute of the Docker [`config`](/nomad/docs/drivers/docker).
<Note>
Runtime environment variables are not defined until after the scheduler
has placed the job, so they are unavailable for use in job constraints.
</Note>
## Syntax
The syntax for interpreting variables in the Nomad job specification is
`${variable_name}`. The [`template` block](/nomad/docs/job-specification/template)
uses the `env` function to retrieve these variables from the environment, using
`{{env "variable_name"}}` instead. Examples can be seen below:
```hcl
task "docs" {
@ -43,6 +59,17 @@ task "docs" {
value = "linux"
}
template {
destination = "template.txt"
data = <<EOT
{{- /*
Environment variables are available to templates via the env function,
rather than the ${...} syntax.
*/ -}}
Running on {{env "attr.unique.hostname"}}.
EOT
}
# Environment variables are interpreted and can contain both runtime and
# node attributes. These environment variables are passed into the task.
env {
@ -57,42 +84,42 @@ task "docs" {
}
```
## Node Variables ((#interpreted_node_vars, #node-variables-))
## Node Attributes ((#interpreted_node_vars, #node-variables-))
Below is a full listing of node attributes that are interpretable. These
attributes are interpreted by **both** constraints and within the task and
driver.
| Variable | Description | Example Value |
| ------------------------- | ------------------------------------------- | -------------------------------------- |
| Variable | Description | Example Value |
| ----------------------| ------------------------------------------- | -------------------------------------- |
| `${node.unique.id}` | 36 character unique client identifier | `9afa5da1-8f39-25a2-48dc-ba31fd7c0023` |
| `${node.region}` | Client's region | `global` |
| `${node.datacenter}` | Client's datacenter | `dc1` |
| `${node.unique.name}` | Client's name | `nomad-client-10-1-2-4` |
| `${node.class}` | Client's class | `linux-64bit` |
| `${attr.<property>}` | Property given by `property` on the client | `${attr.cpu.arch} => amd64` |
| `${meta.<key>}` | Metadata value given by `key` on the client | `${meta.foo} => bar` |
| `${attr.<property>}` | Property given by `property` on the client | `${attr.cpu.arch} => amd64` |
| `${meta.<key>}` | Metadata value given by `key` on the client | `${meta.foo} => bar` |
Below is a table documenting common node properties:
Below is a table documenting common node properties.
| Property | Description |
| ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `${attr.cpu.arch}` | CPU architecture of the client (e.g. `amd64`, `386`) |
| Property | Description |
| ---------------------------------------------------| ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `${attr.cpu.arch}` | CPU architecture of the client (e.g. `amd64`, `386`) |
| `${attr.cpu.numcores}` | Number of CPU cores on the client. May differ from how many cores are available for reservation due to OS or configuration. See `cpu.reservablecores`. |
| `${attr.cpu.reservablecores}` | Number of CPU cores on the client avaible for scheduling. Number of cores used by the scheduler when placing work with `resources.cores` set. |
| `${attr.cpu.totalcompute}` | `cpu.frequency × cpu.numcores` but may be overridden by `client.cpu_total_compute` |
| `${attr.cpu.reservablecores}` | Number of CPU cores on the client available for scheduling. Number of cores used by the scheduler when placing work with `resources.cores` set. |
| `${attr.cpu.totalcompute}` | `cpu.frequency × cpu.numcores` but may be overridden by `client.cpu_total_compute` |
| `${attr.consul.datacenter}` | The Consul datacenter of the client (if Consul is found) |
| `${attr.driver.<property>}` | See the [task drivers](/nomad/docs/drivers) for property documentation |
| `${attr.driver.<property>}` | See the [task drivers](/nomad/docs/drivers) for property documentation |
| `${attr.unique.hostname}` | Hostname of the client |
| `${attr.unique.network.ip-address}` | The IP address fingerprinted by the client and from which task ports are allocated |
| `${attr.kernel.arch}` | Kernel architecture of the client (e.g. `x86_64`, `aarch64`) |
| `${attr.kernel.name}` | Kernel of the client (e.g. `linux`, `darwin`) |
| `${attr.kernel.version}` | Version of the client kernel (e.g. `3.19.0-25-generic`, `15.0.0`) |
| `${attr.kernel.version}` | Version of the client kernel (e.g. `3.19.0-25-generic`, `15.0.0`) |
| `${attr.platform.aws.ami-id}` | AMI ID of the client (if on AWS EC2) |
| `${attr.platform.aws.instance-life-cycle}` | Instance lifecycle (e.g. spot, on-demand) of the client (if on AWS EC2) |
| `${attr.platform.aws.instance-type}` | Instance type of the client (if on AWS EC2) |
| `${attr.platform.aws.placement.availability-zone}` | Availability Zone of the client (if on AWS EC2) |
| `${attr.os.name}` | Operating system of the client (e.g. `ubuntu`, `windows`, `darwin`) |
| `${attr.os.name}` | Operating system of the client (e.g. `ubuntu`, `windows`, `darwin`) |
| `${attr.os.version}` | Version of the client OS |
The full list of node attributes can be obtained by running `nomad node status -verbose [node]`.
@ -130,38 +157,41 @@ the task is running in. These are only defined once the task has been placed on
a particular node and as such can not be used in constraints.
Environment variables should be enclosed in brackets `${...}` for
interpolation.
interpolation or accessed using the `env` function inside the template
block—`{{env "..."}}`
### Dots in Variables ((#dots_in_vars))
Starting in Nomad 0.9, task configuration interpolation requires variables to
be valid identifiers. While this does not affect default variables or common
custom variables, it is possible to define a variable that is not a valid
identifier:
Nomad interprets dots in names as object notation. This causes names that have
multiple consecutive dots to be considered invalid. For example, an environment
variable named `invalid...name` cannot be interpolated using the standard
`"${invalid...name}"` syntax. If you do, the parser will return an
`Extra characters after interpolation expression` error. Nomad provides a
variable—`env`—that can access any environment variable, regardless
of its name, using index syntax.
```hcl
env {
"valid.name" = "ok"
"invalid...name" = "not a valid identifier"
}
```
job "sample" {
datacenters = ["dc1"]
group "g1" {
task "redis" {
The environment variable `invalid...name` cannot be interpolated using the
standard `"${invalid...name}"` syntax. The dots will be interpreted as object
notation so multiple consecutive dots are invalid.
# Note: to set an environment variable with an invalid name, you must
# use the HCL2 map assignment syntax for `env`. Otherwise, the job spec
# parser will throw an `Argument or block definition required` error
env = {
"invalid...name" = "value1"
"valid.name" = "value2"
}
To continue supporting all user environment variables Nomad 0.9 added a new
`env` variable which allows accessing any environment variable through index
syntax:
```hcl
task "redis" {
driver = "docker"
config {
image = "redis:7"
labels {
label1 = "${env["invalid...name"]}"
label2 = "${env["valid.name"]}"
driver = "docker"
config {
image = "redis:7"
labels {
label1 = "${env["invalid...name"]}"
label2 = "${valid.name}"
}
}
}
}
}

61
website/content/partials/envvars.mdx
View File

@ -2,58 +2,67 @@
| Variable | Description |
|--------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `NOMAD_ALLOC_DIR` | The path to the shared `alloc/` directory. See [here](/nomad/docs/runtime/environment#task-directories) for more information. |
| `NOMAD_TASK_DIR` | The path to the task `local/` directory. See [here](/nomad/docs/runtime/environment#task-directories) for more information. |
| `NOMAD_SECRETS_DIR` | Path to the task's secrets directory. See [here](/nomad/docs/runtime/environment#task-directories) for more information. |
| `NOMAD_ALLOC_DIR` | The path to the shared `alloc/` directory. See the [Runtime Task Directories documentation][taskdirs] for more information. |
| `NOMAD_TASK_DIR` | The path to the task `local/` directory. See the [Runtime Task Directories documentation][taskdirs] for more information. |
| `NOMAD_SECRETS_DIR` | Path to the task's `secrets/` directory. See the [Runtime Task Directories documentation][taskdirs] for more information. |
| `NOMAD_MEMORY_LIMIT` | Memory limit in MB for the task |
| `NOMAD_MEMORY_MAX_LIMIT` | The maximum memory limit the task may use if client has excess memory capacity, in MB. Omitted if task isn't configured with memory oversubscription. |
| `NOMAD_CPU_LIMIT` | CPU limit in MHz for the task |
| `NOMAD_CPU_CORES` | The specific CPU cores reserved for the task in cpuset list notation. Omitted if the task does not request cpu cores. E.g. `0-2,7,12-14` |
| `NOMAD_CPU_CORES` | The specific CPU cores reserved for the task in cpuset list notation. Omitted if the task does not request CPU cores. For example, `0-2,7,12-14` |
| `NOMAD_ALLOC_ID` | Allocation ID of the task |
| `NOMAD_SHORT_ALLOC_ID` | The first 8 characters of the allocation ID of the task |
| `NOMAD_ALLOC_NAME` | Allocation name of the task. This is derived from the job name, task group name, and allocation index. |
| `NOMAD_ALLOC_INDEX` | Allocation index; useful to distinguish instances of task groups. From 0 to (count - 1). For system jobs and sysbatch jobs, this value will always be 0. The index is unique within a given version of a job, but canaries or failed tasks in a deployment may reuse the index. |
| `NOMAD_TASK_NAME` | Task's name |
| `NOMAD_GROUP_NAME` | Group's name |
| `NOMAD_JOB_ID` | Job's ID, which is equal to the Job name when submitted through CLI but can be different when using the API |
| `NOMAD_JOB_ID` | Job's ID, which is equal to the Job name when submitted through the command-line tool but can be different when using the API |
| `NOMAD_JOB_NAME` | Job's name |
| `NOMAD_JOB_PARENT_ID` | ID of the Job's parent if it has one |
| `NOMAD_DC` | Datacenter in which the allocation is running |
| `NOMAD_PARENT_CGROUP` | The parent cgroup used to contain task cgroups (Linux only) |
| `NOMAD_NAMESPACE` | Namespace in which the allocation is running |
| `NOMAD_REGION` | Region in which the allocation is running |
| `NOMAD_META_<key>` | The metadata value given by `key` on the task's metadata. Note that this is different from [`${meta.<key>}`](/nomad/docs/runtime/interpolation#node-variables-) which are keys in the node's metadata. |
| `VAULT_TOKEN` | The task's Vault token. See [Vault Integration](/nomad/docs/integrations/vault-integration) for more details |
| `NOMAD_META_<key>` | The metadata value given by `key` on the task's metadata. <br/> **Note:** this is different from [`${meta.<key>}`](/nomad/docs/runtime/interpolation#node-variables-) which are keys in the node's metadata. |
| `VAULT_TOKEN` | The task's Vault token. See the [Vault Integration][vault] documentation for more details |
### Network-related Variables
| Variable | Description |
| ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `NOMAD_IP_<label>` | Host IP for the given port `label`. See [here for more](/nomad/docs/job-specification/network) information. |
| `NOMAD_PORT_<label>` | Port for the given port `label`. Driver-specified port when a port map is used, otherwise the host's static or dynamic port allocation. Services should bind to this port. See [here for more](/nomad/docs/job-specification/network) information. |
| `NOMAD_ADDR_<label>` | Host `IP:Port` pair for the given port `label`. |
| `NOMAD_HOST_PORT_<label>` | Port on the host for the port `label`. See [here](/nomad/docs/job-specification/network#mapped-ports) for more information. |
| `NOMAD_UPSTREAM_IP_<service>` | IP for the given `service` when defined as a Consul Connect [upstream](/nomad/docs/job-specification/upstreams). |
| `NOMAD_UPSTREAM_PORT_<service>` | Port for the given `service` when defined as a Consul Connect [upstream](/nomad/docs/job-specification/upstreams). |
| `NOMAD_UPSTREAM_ADDR_<service>` | Host `IP:Port` for the given `service` when defined as a Consul Connect [upstream](/nomad/docs/job-specification/upstreams). |
| `NOMAD_ENVOY_ADMIN_ADDR_<service>` | Local address `127.0.0.2:Port` for the admin port of the envoy sidecar for the given `service` when defined as a Consul Connect enabled service. Envoy runs inside the group network namespace unless configured for host networking. |
| `NOMAD_ENVOY_READY_ADDR_<service>` | Local address `127.0.0.1:Port` for the ready port of the envoy sidecar for the given `service` when defined as a Consul Connect enabled service. Envoy runs inside the group network namespace unless configured for host networking. |
| Variable | Description |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `NOMAD_IP_<label>` | Host IP for the given port `label`. See the [`network` block documentation][network-block] for more information. |
| `NOMAD_PORT_<label>` | Port for the given port `label`. Driver-specified port when a port map is used, otherwise the host's static or dynamic port allocation. Services should bind to this port. See the [`network` block documentation][network-block] for more information. |
| `NOMAD_ADDR_<label>` | Host `IP:Port` pair for the given port `label`. |
| `NOMAD_HOST_PORT_<label>` | Port on the host for the port `label`. See the [**Mapped Ports**](/nomad/docs/job-specification/network#mapped-ports) section of the `network` block documentation for more information. |
| `NOMAD_UPSTREAM_IP_<service>` | IP for the given `service` when defined as a Consul service mesh [upstream][]. |
| `NOMAD_UPSTREAM_PORT_<service>` | Port for the given `service` when defined as a Consul service mesh [upstream][]. |
| `NOMAD_UPSTREAM_ADDR_<service>` | Host `IP:Port` for the given `service` when defined as a Consul service mesh [upstream][]. |
| `NOMAD_ENVOY_ADMIN_ADDR_<service>` | Local address `127.0.0.2:Port` for the admin port of the envoy sidecar for the given `service` when defined as a Consul service mesh enabled service. Envoy runs inside the group network namespace unless configured for host networking. |
| `NOMAD_ENVOY_READY_ADDR_<service>` | Local address `127.0.0.1:Port` for the ready port of the envoy sidecar for the given `service` when defined as a Consul service mesh enabled service. Envoy runs inside the group network namespace unless configured for host networking. |
~> **Note:** 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>`.
<Note>
Nomad replaces characters that are neither alphanumeric nor underscores in
port labels or task names with underscores when generating environment variable
names such as `NOMAD_ADDR_<task>_<label>`
</Note>
### Consul-related Variables
This variables are only set for Connect native tasks.
<Note>These variables are only set for Consul service mesh native tasks.</Note>
| Variable | Description |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `CONSUL_HTTP_ADDR` | Specifies the address to the local Consul agent. Will be automatically set to a unix domain socket in bridge networking mode, or a tcp address in host networking mode. |
| `CONSUL_HTTP_TOKEN` | Specifies the Consul ACL token used to authorize with Consul. Will be automatically set to a generated Connect service identity token specific to the service instance if Consul ACLs are enabled. |
| `CONSUL_HTTP_SSL` | Specifies whether HTTPS should be used when communicating with consul. Will be automatically set to true if Nomad is configured to communicate with Consul using TLS. |
| `CONSUL_HTTP_ADDR` | Specifies the address to the local Consul agent. Will be automatically set to a unix domain socket in bridge networking mode, or a TCP address in host networking mode. |
| `CONSUL_HTTP_TOKEN` | Specifies the Consul ACL token used to authorize with Consul. Will be automatically set to a generated Consul service identity token specific to the service instance if Consul ACLs are enabled. |
| `CONSUL_HTTP_SSL` | Specifies whether HTTPS should be used when communicating with Consul. Will be automatically set to true if Nomad is configured to communicate with Consul using TLS. |
| `CONSUL_HTTP_SSL_VERIFY` | Specifies whether the HTTPS connection with Consul should be mutually verified. Will be automatically set to true if Nomad is configured to verify TLS certificates. |
| `CONSUL_CACERT` | Specifies the path to the CA certificate used for Consul communication. Will be automatically set if Nomad is configured with the `consul.share_ssl` option. |
| `CONSUL_CLIENT_CERT` | Specifies the path to the Client certificate used for Consul communication. Will be automatically set if Nomad is configured with the `consul.share_ssl` option. |
| `CONSUL_CLIENT_KEY` | Specifies the path to the CLient Key certificate used for Consul communication. Will be automatically set if Nomad is configured with the `consul.share_ssl` option. |
| `CONSUL_CLIENT_KEY` | Specifies the path to the Client Key certificate used for Consul communication. Will be automatically set if Nomad is configured with the `consul.share_ssl` option. |
| `CONSUL_TLS_SERVER_NAME` | Specifies the server name to use as the SNI host for Consul communication. Will be automatically set if Consul is configured to use TLS and the task is in a group using bridge networking mode. |
[upstream]: /nomad/docs/job-specification/upstreams
[taskdirs]: /nomad/docs/runtime/environment#task-directories
[network-block]: /nomad/docs/job-specification/network
[vault]: /nomad/docs/integrations/vault-integration