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

Merge pull request #1784 from hashicorp/sethvargo/docs

Browse source 
Add more examples and clarify interpreted variables docs
This commit is contained in:
Seth Vargo 2016-10-03 17:17:57 -04:00 committed by GitHub
parent 1d71ac1a9f 3fd682076c
commit b96fd48263
8 changed files with 188 additions and 109 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

9
website/source/assets/stylesheets/_docs.scss
View file

@ -210,8 +210,15 @@ body.layout-intro{
-webkit-font-smoothing: antialiased; -webkit-font-smoothing: antialiased;
} }
pre{ pre {
margin: 0 0 18px; margin: 0 0 18px;
// This will force the code to scroll horizontally on small screens
// instead of wrapping.
code {
overflow-wrap: normal;
white-space: pre;
}
} }
a{ a{

15
website/source/docs/drivers/docker.html.md
View file

@ -334,7 +334,20 @@ The `docker` driver will set the following client attributes:
* `driver.docker` - This will be set to "1", indicating the driver is * `driver.docker` - This will be set to "1", indicating the driver is
available. available.
* `driver.docker.version` - This will be set to version of the docker server * `driver.docker.version` - This will be set to version of the docker server.
Here is an example of using these properties in a job file:
```hcl
job "docs" {
# Require docker version higher than 1.2.
constraint {
attribute = "${driver.docker.version}"
operator = ">"
version = "1.2"
}
}
```
## Resource Isolation ## Resource Isolation

3
website/source/docs/drivers/exec.html.md
View file

@ -85,8 +85,7 @@ also applies for running Nomad in -dev mode.
The `exec` driver will set the following client attributes: The `exec` driver will set the following client attributes:
* `driver.exec` - This will be set to "1", indicating the * `driver.exec` - This will be set to "1", indicating the driver is available.
driver is available.
## Resource Isolation ## Resource Isolation

18
website/source/docs/drivers/java.html.md
View file

@ -12,7 +12,7 @@ Name: `java`
The `Java` driver is used to execute Java applications packaged into a Java Jar The `Java` driver is used to execute Java applications packaged into a Java Jar
file. The driver requires the Jar file to be accessible from the Nomad file. The driver requires the Jar file to be accessible from the Nomad
client via the [`artifact` downloader](/docs/jobspec/index.html#artifact_doc). client via the [`artifact` downloader](/docs/jobspec/index.html#artifact_doc).
## Task Configuration ## Task Configuration
@ -61,7 +61,7 @@ task "web" {
## Client Requirements ## Client Requirements
The `java` driver requires Java to be installed and in your system's `$PATH`. On The `java` driver requires Java to be installed and in your system's `$PATH`. On
Linux, Nomad must run as root since it will use `chroot` and `cgroups` which Linux, Nomad must run as root since it will use `chroot` and `cgroups` which
require root privileges. The task must also specify at least one artifact to require root privileges. The task must also specify at least one artifact to
download, as this is the only way to retrieve the Jar being run. download, as this is the only way to retrieve the Jar being run.
@ -76,6 +76,19 @@ this by executing `java -version` on the host and parsing the output
* `driver.java.runtime` - Runtime version, ex: `Java(TM) SE Runtime Environment (build 1.6.0_65-b14-466.1-11M4716)` * `driver.java.runtime` - Runtime version, ex: `Java(TM) SE Runtime Environment (build 1.6.0_65-b14-466.1-11M4716)`
* `driver.java.vm` - Virtual Machine information, ex: `Java HotSpot(TM) 64-Bit Server VM (build 20.65-b04-466.1, mixed mode)` * `driver.java.vm` - Virtual Machine information, ex: `Java HotSpot(TM) 64-Bit Server VM (build 20.65-b04-466.1, mixed mode)`
Here is an example of using these properties in a job file:
```hcl
job "docs" {
# Only run this job where the JVM is higher than version 1.6.0.
constraint {
attribute = "${driver.java.version}"
operator = ">"
value = "1.6.0"
}
}
```
## Resource Isolation ## Resource Isolation
The resource isolation provided varies by the operating system of The resource isolation provided varies by the operating system of
@ -87,4 +100,3 @@ running as root, many of these mechanisms cannot be used.
As a baseline, the Java jars will be run inside a Java Virtual Machine, As a baseline, the Java jars will be run inside a Java Virtual Machine,
providing a minimum amount of isolation. providing a minimum amount of isolation.

15
website/source/docs/drivers/qemu.html.md
View file

@ -20,7 +20,7 @@ The `Qemu` driver can execute any regular `qemu` image (e.g. `qcow`, `img`,
`iso`), and is currently invoked with `qemu-system-x86_64`. `iso`), and is currently invoked with `qemu-system-x86_64`.
The driver requires the image to be accessible from the Nomad client via the The driver requires the image to be accessible from the Nomad client via the
[`artifact` downloader](/docs/jobspec/index.html#artifact_doc). [`artifact` downloader](/docs/jobspec/index.html#artifact_doc).
## Task Configuration ## Task Configuration
@ -82,6 +82,19 @@ The `Qemu` driver will set the following client attributes:
this by executing `qemu-system-x86_64 -version` on the host and parsing the output this by executing `qemu-system-x86_64 -version` on the host and parsing the output
* `driver.qemu.version` - Version of `qemu-system-x86_64`, ex: `2.4.0` * `driver.qemu.version` - Version of `qemu-system-x86_64`, ex: `2.4.0`
Here is an example of using these properties in a job file:
```hcl
job "docs" {
# Only run this job where the qemu version is higher than 1.2.3.
constraint {
attribute = "${driver.qemu.version}"
operator = ">"
value = "1.2.3"
}
}
```
## Resource Isolation ## Resource Isolation
Nomad uses Qemu to provide full software virtualization for virtual machine Nomad uses Qemu to provide full software virtualization for virtual machine

3
website/source/docs/drivers/raw_exec.html.md
View file

@ -86,8 +86,7 @@ explicitly enable the `raw_exec` driver in the client's
The `raw_exec` driver will set the following client attributes: The `raw_exec` driver will set the following client attributes:
* `driver.raw_exec` - This will be set to "1", indicating the * `driver.raw_exec` - This will be set to "1", indicating the driver is available.
driver is available.
## Resource Isolation ## Resource Isolation

15
website/source/docs/drivers/rkt.html.md
View file

@ -47,7 +47,7 @@ The `rkt` driver supports the following configuration in the job spec:
## Task Directories ## Task Directories
The `rkt` driver currently does not support mounting of the `alloc/` and `local/` directories. The `rkt` driver currently does not support mounting of the `alloc/` and `local/` directories.
Once support is added, version `v0.10.0` or above of `rkt` will be required. Once support is added, version `v0.10.0` or above of `rkt` will be required.
## Client Requirements ## Client Requirements
@ -66,6 +66,19 @@ this by executing `rkt version` on the host and parsing the output
version is `0.14.0` version is `0.14.0`
* `driver.rkt.appc.version` - Version of `appc` that `rkt` is using eg: `0.8.1` * `driver.rkt.appc.version` - Version of `appc` that `rkt` is using eg: `0.8.1`
Here is an example of using these properties in a job file:
```hcl
job "docs" {
# Only run this job where the rkt version is higher than 0.8.
constraint {
attribute = "${driver.rkt.version}"
operator = ">"
value = "0.8"
}
}
```
## Resource Isolation ## Resource Isolation
This driver supports CPU and memory isolation by delegating to `rkt`. Network isolation This driver supports CPU and memory isolation by delegating to `rkt`. Network isolation

219
website/source/docs/jobspec/interpreted.html.md
View file

@ -16,142 +16,171 @@ scheduler has placed them on a particular node.
The syntax for interpreting variables is `${variable}`. An example and a The syntax for interpreting variables is `${variable}`. An example and a
comprehensive list of interpretable fields can be seen below: comprehensive list of interpretable fields can be seen below:
``` ```hcl
task "demo" { task "docs" {
driver = "docker" driver = "docker"
# Drivers support interpreting node attributes and runtime environment # Drivers support interpreting node attributes and runtime environment
# variables # variables
config { config {
image = "my-app" image = "my-app"
# Interpret runtime variables to inject the address to bind to and the # Interpret runtime variables to inject the address to bind to and the
# location to write logs to. # location to write logs to.
args = ["--bind=${NOMAD_ADDR_RPC}", "--logs=${NOMAD_ALLOC_DIR}/logs"] args = [
"--bind", "${NOMAD_ADDR_RPC}",
"--logs", "${NOMAD_ALLOC_DIR}/logs",
]
port_map { port_map {
RPC = 6379 RPC = 6379
}
} }
}
# Constraints only support node attributes as runtime environment variables # Constraints only support node attributes as runtime environment variables
# are only defined after the task is placed on a node. # are only defined after the task is placed on a node.
constraint { constraint {
attribute = "${attr.kernel.name}" attribute = "${attr.kernel.name}"
value = "linux" value = "linux"
} }
# Environment variables are interpreted and can contain both runtime and # Environment variables are interpreted and can contain both runtime and
# node attributes. # node attributes. There environment variables are passed into the task.
env { env {
"DC" = "Running on datacenter ${node.datacenter}" "DC" = "Running on datacenter ${node.datacenter}"
"VERSION" = "Version ${NOMAD_META_VERSION}" "VERSION" = "Version ${NOMAD_META_VERSION}"
} }
# Meta keys are also interpretable. # Meta keys are also interpretable.
meta { meta {
VERSION = "v0.3" VERSION = "v0.3"
} }
} }
``` ```
## Node Variables <a id="interpreted_node_vars"></a> ## Node Variables <a id="interpreted_node_vars"></a>
Below is a full listing of node attributes that are interpretable. These Below is a full listing of node attributes that are interpretable. These
attributes are Interpreted by __both__ constraints and within the task and attributes are interpreted by __both__ constraints and within the task and
driver. driver.
<table class="table table-bordered table-striped"> <table class="table table-bordered table-striped">
<tr> <tr>
<th>Variable</th> <th>Variable</th>
<th>Description</th> <th>Description</th>
<th>Example</th> <th>Example Value</th>
</tr> </tr>
<tr> <tr>
<td>${node.unique.id}</td> <td><tt>${node.unique.id}</tt></td>
<td>The 36 character unique client node identifier</td> <td>36 character unique client identifier</td>
<td>9afa5da1-8f39-25a2-48dc-ba31fd7c0023</td> <td><tt>9afa5da1-8f39-25a2-48dc-ba31fd7c0023</tt></td>
</tr> </tr>
<tr> <tr>
<td>${node.datacenter}</td> <td><tt>${node.datacenter}</tt></td>
<td>The client node's datacenter</td> <td>Client's datacenter</td>
<td>dc1</td> <td><tt>dc1</tt></td>
</tr> </tr>
<tr> <tr>
<td>${node.unique.name}</td> <td><tt>${node.unique.name}</tt></td>
<td>The client node's name</td> <td>Client's name</td>
<td>nomad-client-10-1-2-4</td> <td><tt>nomad-client-10-1-2-4</tt></td>
</tr> </tr>
<tr> <tr>
<td>${node.class}</td> <td><tt>${node.class}</tt></td>
<td>The client node's class</td> <td>Client's class</td>
<td>linux-64bit</td> <td><tt>linux-64bit</tt></td>
</tr> </tr>
<tr> <tr>
<td>${attr."key"}</td> <td><tt>${attr.&lt;property&gt;}</tt></td>
<td>The attribute given by `key` on the client node.</td> <td>Property given by <tt>property</tt> on the client</td>
<td>platform.aws.instance-type:r3.large</td> <td><tt>${attr.arch} => amd64</tt></td>
</tr> </tr>
<tr> <tr>
<td>${meta."key"}</td> <td><tt>${meta.&lt;key&gt;}</tt></td>
<td>The metadata value given by `key` on the client node.</td> <td>Metadata value given by <tt>key</tt> on the client</td>
<td></td> <td><tt>${meta.foo} => bar</tt></td>
</tr> </tr>
</table> </table>
Below is a table documenting common node attributes: Below is a table documenting common node properties:
<table class="table table-bordered table-striped"> <table class="table table-bordered table-striped">
<tr> <tr>
<th>Attribute</th> <th>Property</th>
<th>Description</th> <th>Description</th>
</tr> </tr>
<tr> <tr>
<td>arch</td> <td><tt>arch</tt></td>
<td>CPU architecture of the client. Examples: `amd64`, `386`</td> <td>CPU architecture of the client (e.g. <tt>amd64</tt>, <tt>386</tt>)</td>
</tr> </tr>
<tr> <tr>
<td>consul.datacenter</td> <td><tt>consul.datacenter</tt></td>
<td>The Consul datacenter of the client node if Consul found</td> <td>The Consul datacenter of the client (if Consul is found)</td>
</tr> </tr>
<tr> <tr>
<td>cpu.numcores</td> <td><tt>cpu.numcores</tt></td>
<td>Number of CPU cores on the client</td> <td>Number of CPU cores on the client</td>
</tr> </tr>
<tr> <tr>
<td>driver."key"</td> <td><tt>driver.&lt;property&gt;</tt></td>
<td>See the [task drivers](/docs/drivers/index.html) for attribute documentation</td> <td>See the [task drivers](/docs/drivers/index.html) for property documentation</td>
</tr> </tr>
<tr> <tr>
<td>unique.hostname</td> <td><tt>unique.hostname</tt></td>
<td>Hostname of the client</td> <td>Hostname of the client</td>
</tr> </tr>
<tr> <tr>
<td>kernel.name</td> <td><tt>kernel.name</tt></td>
<td>Kernel of the client. Examples: `linux`, `darwin`</td> <td>Kernel of the client (e.g. <tt>linux</tt>, <tt>darwin</tt>)</td>
</tr> </tr>
<tr> <tr>
<td>kernel.version</td> <td><tt>kernel.version</tt></td>
<td>Version of the client kernel. Examples: `3.19.0-25-generic`, `15.0.0`</td> <td>Version of the client kernel (e.g. <tt>3.19.0-25-generic</tt>, <tt>15.0.0</tt>)</td>
</tr> </tr>
<tr> <tr>
<td>platform.aws.ami-id</td> <td><tt>platform.aws.ami-id</tt></td>
<td>On EC2, the AMI ID of the client node</td> <td>AMI ID of the client (if on AWS EC2)</td>
</tr> </tr>
<tr> <tr>
<td>platform.aws.instance-type</td> <td><tt>platform.aws.instance-type</tt></td>
<td>On EC2, the instance type of the client node</td> <td>Instance type of the client (if on AWS EC2)</td>
</tr> </tr>
<tr> <tr>
<td>os.name</td> <td><tt>os.name</tt></td>
<td>Operating system of the client. Examples: `ubuntu`, `windows`, `darwin`</td> <td>Operating system of the client (e.g. <tt>ubuntu</tt>, <tt>windows</tt>, <tt>darwin</tt>)</td>
</tr> </tr>
<tr> <tr>
<td>os.version</td> <td><tt>os.version</tt></td>
<td>Version of the client OS</td> <td>Version of the client OS</td>
</tr> </tr>
</table> </table>
Here are some examples of using node attributes and properties in a job file:
```hcl
job "docs" {
# This will constrain this job to only run on 64-bit clients.
constraint {
attribute = "${attr.arch}"
value = "amd64"
}
# This will restrict the job to only run on clients with 4 or more cores.
# Note: you may also declare a resource requirement for CPU for a task.
constraint {
attribute = "${cpu.numcores}"
operator = ">="
value = "4"
}
# Only run this job on a memory-optimized AWS EC2 instance.
constraint {
attribute = "${attr.platform.aws.instance-type}"
value = "m4.xlarge"
}
}
```
## Environment Variables <a id="interpreted_env_vars"></a> ## Environment Variables <a id="interpreted_env_vars"></a>
The following are runtime environment variables that describe the environment The following are runtime environment variables that describe the environment
@ -164,69 +193,63 @@ a particular node and as such can not be used in constraints.
<th>Description</th> <th>Description</th>
</tr> </tr>
<tr> <tr>
<td>${NOMAD_ALLOC_DIR}</td> <td><tt>${NOMAD_ALLOC_DIR}</tt></td>
<td>The path to the shared `alloc/` directory. See <td>The path to the shared <tt>alloc/</tt> directory. See [here](/docs/jobspec/environment.html#task_dir) for more information.</td>
[here](/docs/jobspec/environment.html#task_dir) for more
information.</td>
</tr> </tr>
<tr> <tr>
<td>${NOMAD_TASK_DIR}</td> <td><tt>${NOMAD_TASK_DIR}</tt></td>
<td>The path to the task `local/` directory. See <td>The path to the task <tt>local/</tt> directory. See [here](/docs/jobspec/environment.html#task_dir) for more information.</td>
[here](/docs/jobspec/environment.html#task_dir) for more
information.</td>
</tr> </tr>
<tr> <tr>
<td>${NOMAD_MEMORY_LIMIT}</td> <td><tt>${NOMAD_MEMORY_LIMIT}</tt></td>
<td>The memory limit in MBytes for the task</td> <td>The memory limit in MBytes for the task</td>
</tr> </tr>
<tr> <tr>
<td>${NOMAD_CPU_LIMIT}</td> <td><tt>${NOMAD_CPU_LIMIT}</tt></td>
<td>The CPU limit in MHz for the task</td> <td>The CPU limit in MHz for the task</td>
</tr> </tr>
<tr> <tr>
<td>${NOMAD_ALLOC_ID}</td> <td><tt>${NOMAD_ALLOC_ID}</tt></td>
<td>The allocation ID of the task</td> <td>The allocation ID of the task</td>
</tr> </tr>
<tr> <tr>
<td>${NOMAD_ALLOC_NAME}</td> <td><tt>${NOMAD_ALLOC_NAME}</tt></td>
<td>The allocation name of the task</td> <td>The allocation name of the task</td>
</tr> </tr>
<tr> <tr>
<td>${NOMAD_ALLOC_INDEX}</td> <td><tt>${NOMAD_ALLOC_INDEX}</tt></td>
<td>The allocation index; useful to distinguish instances of task groups</td> <td>The allocation index; useful to distinguish instances of task groups</td>
</tr> </tr>
<tr> <tr>
<td>${NOMAD_TASK_NAME}</td> <td><tt>${NOMAD_TASK_NAME}</tt></td>
<td>The task's name</td> <td>The task's name</td>
</tr> </tr>
<tr> <tr>
<td>${NOMAD_IP_"label"}</td> <td><tt>${NOMAD_IP_&lt;label&gt;}</tt></td>
<td>The IP for the given port `label`. See <td>The IP for the given port <tt>label</tt>. See
[here](/docs/jobspec/networking.html) for more information.</td> [here](/docs/jobspec/networking.html) for more information.</td>
</tr> </tr>
<tr> <tr>
<td>${NOMAD_PORT_"label"}</td> <td><tt>${NOMAD_PORT_&lt;label&gt;}</tt></td>
<td>The port for the port `label`. See [here](/docs/jobspec/networking.html) <td>The port for the port <tt>label</tt>. See [here](/docs/jobspec/networking.html) for more information.</td>
for more information.</td>
</tr> </tr>
<tr> <tr>
<td>${NOMAD_ADDR_"label"}</td> <td><tt>${NOMAD_ADDR_&lt;label&gt;}</tt></td>
<td>The `ip:port` pair for the given port `label`. See <td>The <tt>ip:port</tt> pair for the given port <tt>label</tt>. See
[here](/docs/jobspec/networking.html) for more information.</td> [here](/docs/jobspec/networking.html) for more information.</td>
</tr> </tr>
<tr> <tr>
<td>${NOMAD_HOST_PORT_"label"}</td> <td><tt>${NOMAD_HOST_PORT_&lt;label&gt;}</tt></td>
<td>The port on the host if port forwarding is being used for the port <td>The port on the host if port forwarding is being used for the port
`label`. See [here](/docs/jobspec/networking.html#mapped_ports) for more <tt>label</tt>. See [here](/docs/jobspec/networking.html#mapped_ports) for more
information.</td> information.</td>
</tr> </tr>
<tr> <tr>
<td>${NOMAD_META_"key"}</td> <td><tt>${NOMAD_META_&lt;key&gt;}</tt></td>
<td>The metadata value given by `key` on the task's metadata</td> <td>The metadata value given by <tt>key</tt> on the task's metadata</td>
</tr> </tr>
<tr> <tr>
<td>${"env_key"}</td> <td><tt>${"env_key"}</tt></td>
<td>Interpret an environment variable with key `env_key` set on the task.</td> <td>Interpret an environment variable with key <tt>env_key</tt> set on the task.</td>
</tr> </tr>
</table> </table>