From a883bbfb42d955ebe58974cce458c70bec3075c2 Mon Sep 17 00:00:00 2001 From: Seth Vargo Date: Mon, 3 Oct 2016 15:50:35 -0400 Subject: [PATCH 1/6] Fix HCL on interpreted.html --- .../source/docs/jobspec/interpreted.html.md | 60 ++++++++++--------- 1 file changed, 31 insertions(+), 29 deletions(-) diff --git a/website/source/docs/jobspec/interpreted.html.md b/website/source/docs/jobspec/interpreted.html.md index cd22a8367..81d79f7d6 100644 --- a/website/source/docs/jobspec/interpreted.html.md +++ b/website/source/docs/jobspec/interpreted.html.md @@ -16,42 +16,45 @@ 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: -``` +```hcl task "demo" { - driver = "docker" + driver = "docker" - # Drivers support interpreting node attributes and runtime environment - # variables - config { - image = "my-app" + # Drivers support interpreting node attributes and runtime environment + # variables + config { + image = "my-app" - # Interpret runtime variables to inject the address to bind to and the - # location to write logs to. - args = ["--bind=${NOMAD_ADDR_RPC}", "--logs=${NOMAD_ALLOC_DIR}/logs"] + # Interpret runtime variables to inject the address to bind to and the + # location to write logs to. + args = [ + "--bind", "${NOMAD_ADDR_RPC}", + "--logs", "${NOMAD_ALLOC_DIR}/logs", + ] - port_map { - RPC = 6379 - } + port_map { + RPC = 6379 } + } - # Constraints only support node attributes as runtime environment variables - # are only defined after the task is placed on a node. - constraint { - attribute = "${attr.kernel.name}" - value = "linux" - } + # Constraints only support node attributes as runtime environment variables + # are only defined after the task is placed on a node. + constraint { + attribute = "${attr.kernel.name}" + value = "linux" + } - # Environment variables are interpreted and can contain both runtime and - # node attributes. - env { - "DC" = "Running on datacenter ${node.datacenter}" - "VERSION" = "Version ${NOMAD_META_VERSION}" - } + # Environment variables are interpreted and can contain both runtime and + # node attributes. There environment variables are passed into the task. + env { + "DC" = "Running on datacenter ${node.datacenter}" + "VERSION" = "Version ${NOMAD_META_VERSION}" + } - # Meta keys are also interpretable. - meta { - VERSION = "v0.3" - } + # Meta keys are also interpretable. + meta { + VERSION = "v0.3" + } } ``` @@ -229,4 +232,3 @@ a particular node and as such can not be used in constraints. Interpret an environment variable with key `env_key` set on the task. - From d92c944b429918c40e82d79cf8c2277ab4f5c7fc Mon Sep 17 00:00:00 2001 From: Seth Vargo Date: Mon, 3 Oct 2016 16:59:27 -0400 Subject: [PATCH 2/6] Fix an issue with horizontal docs scrolling --- website/source/assets/stylesheets/_docs.scss | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/website/source/assets/stylesheets/_docs.scss b/website/source/assets/stylesheets/_docs.scss index 319c13d95..71005ef5a 100755 --- a/website/source/assets/stylesheets/_docs.scss +++ b/website/source/assets/stylesheets/_docs.scss @@ -210,8 +210,15 @@ body.layout-intro{ -webkit-font-smoothing: antialiased; } - pre{ + pre { 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{ From 170668d128d8f75d1b8c0bc45973a9a2e0755d5c Mon Sep 17 00:00:00 2001 From: Seth Vargo Date: Mon, 3 Oct 2016 16:59:56 -0400 Subject: [PATCH 3/6] Update docs on interpreted Uses "property" instead of overloading "attribute" --- .../source/docs/jobspec/interpreted.html.md | 159 ++++++++++-------- 1 file changed, 90 insertions(+), 69 deletions(-) diff --git a/website/source/docs/jobspec/interpreted.html.md b/website/source/docs/jobspec/interpreted.html.md index 81d79f7d6..1a06b2603 100644 --- a/website/source/docs/jobspec/interpreted.html.md +++ b/website/source/docs/jobspec/interpreted.html.md @@ -17,7 +17,7 @@ The syntax for interpreting variables is `${variable}`. An example and a comprehensive list of interpretable fields can be seen below: ```hcl -task "demo" { +task "docs" { driver = "docker" # Drivers support interpreting node attributes and runtime environment @@ -61,100 +61,126 @@ task "demo" { ## 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 +attributes are interpreted by __both__ constraints and within the task and driver. - + - - - + + + - - - + + + - - - + + + - - - + + + - - - + + + - - - + + +
Variable DescriptionExampleExample Value
${node.unique.id}The 36 character unique client node identifier9afa5da1-8f39-25a2-48dc-ba31fd7c0023${node.unique.id}36 character unique client identifier9afa5da1-8f39-25a2-48dc-ba31fd7c0023
${node.datacenter}The client node's datacenterdc1${node.datacenter}Client's datacenterdc1
${node.unique.name}The client node's namenomad-client-10-1-2-4${node.unique.name}Client's namenomad-client-10-1-2-4
${node.class}The client node's classlinux-64bit${node.class}Client's classlinux-64bit
${attr."key"}The attribute given by `key` on the client node.platform.aws.instance-type:r3.large${attr.<property>}Property given by property on the client${attr.arch} => amd64
${meta."key"}The metadata value given by `key` on the client node.${meta.<key>}Metadata value given by key on the client${meta.foo} => bar
-Below is a table documenting common node attributes: +Below is a table documenting common node properties: - + - - + + - - + + - + - - + + - + - - + + - - + + - - + + - - + + - - + + - +
AttributeProperty Description
archCPU architecture of the client. Examples: `amd64`, `386`archCPU architecture of the client (e.g. amd64, 386)
consul.datacenterThe Consul datacenter of the client node if Consul foundconsul.datacenterThe Consul datacenter of the client (if Consul is found)
cpu.numcorescpu.numcores Number of CPU cores on the client
driver."key"See the [task drivers](/docs/drivers/index.html) for attribute documentationdriver.<property>See the [task drivers](/docs/drivers/index.html) for property documentation
unique.hostnameunique.hostname Hostname of the client
kernel.nameKernel of the client. Examples: `linux`, `darwin`kernel.nameKernel of the client (e.g. linux, darwin)
kernel.versionVersion of the client kernel. Examples: `3.19.0-25-generic`, `15.0.0`kernel.versionVersion of the client kernel (e.g. 3.19.0-25-generic, 15.0.0)
platform.aws.ami-idOn EC2, the AMI ID of the client nodeplatform.aws.ami-idAMI ID of the client (if on AWS EC2)
platform.aws.instance-typeOn EC2, the instance type of the client nodeplatform.aws.instance-typeInstance type of the client (if on AWS EC2)
os.nameOperating system of the client. Examples: `ubuntu`, `windows`, `darwin`os.nameOperating system of the client (e.g. ubuntu, windows, darwin)
os.versionos.version Version of the client OS
+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 The following are runtime environment variables that describe the environment @@ -167,68 +193,63 @@ a particular node and as such can not be used in constraints. Description - ${NOMAD_ALLOC_DIR} - The path to the shared `alloc/` directory. See - [here](/docs/jobspec/environment.html#task_dir) for more - information. + ${NOMAD_ALLOC_DIR} + The path to the shared alloc/ directory. See [here](/docs/jobspec/environment.html#task_dir) for more information. - ${NOMAD_TASK_DIR} - The path to the task `local/` directory. See - [here](/docs/jobspec/environment.html#task_dir) for more - information. + ${NOMAD_TASK_DIR} + The path to the task local/ directory. See [here](/docs/jobspec/environment.html#task_dir) for more information. - ${NOMAD_MEMORY_LIMIT} + ${NOMAD_MEMORY_LIMIT} The memory limit in MBytes for the task - ${NOMAD_CPU_LIMIT} + ${NOMAD_CPU_LIMIT} The CPU limit in MHz for the task - ${NOMAD_ALLOC_ID} + ${NOMAD_ALLOC_ID} The allocation ID of the task - ${NOMAD_ALLOC_NAME} + ${NOMAD_ALLOC_NAME} The allocation name of the task - ${NOMAD_ALLOC_INDEX} + ${NOMAD_ALLOC_INDEX} The allocation index; useful to distinguish instances of task groups - ${NOMAD_TASK_NAME} + ${NOMAD_TASK_NAME} The task's name - ${NOMAD_IP_"label"} - The IP for the given port `label`. See + ${NOMAD_IP_<label>} + The IP for the given port label. See [here](/docs/jobspec/networking.html) for more information. - ${NOMAD_PORT_"label"} - The port for the port `label`. See [here](/docs/jobspec/networking.html) - for more information. + ${NOMAD_PORT_<label>} + The port for the port label. See [here](/docs/jobspec/networking.html) for more information. - ${NOMAD_ADDR_"label"} - The `ip:port` pair for the given port `label`. See + ${NOMAD_ADDR_<label>} + The ip:port pair for the given port label. See [here](/docs/jobspec/networking.html) for more information. - ${NOMAD_HOST_PORT_"label"} + ${NOMAD_HOST_PORT_<label>} 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 + label. See [here](/docs/jobspec/networking.html#mapped_ports) for more information. - ${NOMAD_META_"key"} - The metadata value given by `key` on the task's metadata + ${NOMAD_META_<key>} + The metadata value given by key on the task's metadata - ${"env_key"} - Interpret an environment variable with key `env_key` set on the task. + ${"env_key"} + Interpret an environment variable with key env_key set on the task. From 283ab84cdf330d939807abd6441cc76ed73e6de3 Mon Sep 17 00:00:00 2001 From: Seth Vargo Date: Mon, 3 Oct 2016 17:00:32 -0400 Subject: [PATCH 4/6] Update driver docs with constraint examples --- website/source/docs/drivers/docker.html.md | 15 ++++++++++++++- website/source/docs/drivers/exec.html.md | 16 ++++++++++++++-- website/source/docs/drivers/java.html.md | 18 +++++++++++++++--- website/source/docs/drivers/qemu.html.md | 15 ++++++++++++++- website/source/docs/drivers/raw_exec.html.md | 16 ++++++++++++++-- website/source/docs/drivers/rkt.html.md | 15 ++++++++++++++- 6 files changed, 85 insertions(+), 10 deletions(-) diff --git a/website/source/docs/drivers/docker.html.md b/website/source/docs/drivers/docker.html.md index 4575831ec..2b9b4d43b 100644 --- a/website/source/docs/drivers/docker.html.md +++ b/website/source/docs/drivers/docker.html.md @@ -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 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 diff --git a/website/source/docs/drivers/exec.html.md b/website/source/docs/drivers/exec.html.md index 17d7d9a44..8de50ae38 100644 --- a/website/source/docs/drivers/exec.html.md +++ b/website/source/docs/drivers/exec.html.md @@ -85,8 +85,20 @@ also applies for running Nomad in -dev mode. The `exec` driver will set the following client attributes: -* `driver.exec` - This will be set to "1", indicating the - driver is available. +* `driver.exec` - This will be set to "1", indicating the driver is available. + +Here is an example of using these properties in a job file: + +```hcl +job "docs" { + # Only run this job where exec is enabled. (Note: this constraint is applied + # automatically if you specify a task that uses the exec driver). + constraint { + attribute = "${driver.exec}" + value = "1" + } +} +``` ## Resource Isolation diff --git a/website/source/docs/drivers/java.html.md b/website/source/docs/drivers/java.html.md index 9d4f395a7..35e25e72a 100644 --- a/website/source/docs/drivers/java.html.md +++ b/website/source/docs/drivers/java.html.md @@ -12,7 +12,7 @@ Name: `java` 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 -client via the [`artifact` downloader](/docs/jobspec/index.html#artifact_doc). +client via the [`artifact` downloader](/docs/jobspec/index.html#artifact_doc). ## Task Configuration @@ -61,7 +61,7 @@ task "web" { ## 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 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. @@ -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.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 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, providing a minimum amount of isolation. - diff --git a/website/source/docs/drivers/qemu.html.md b/website/source/docs/drivers/qemu.html.md index 182af6828..6eedcb5b3 100644 --- a/website/source/docs/drivers/qemu.html.md +++ b/website/source/docs/drivers/qemu.html.md @@ -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`. 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 @@ -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 * `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 Nomad uses Qemu to provide full software virtualization for virtual machine diff --git a/website/source/docs/drivers/raw_exec.html.md b/website/source/docs/drivers/raw_exec.html.md index bf8441822..48d4d7d22 100644 --- a/website/source/docs/drivers/raw_exec.html.md +++ b/website/source/docs/drivers/raw_exec.html.md @@ -86,8 +86,20 @@ explicitly enable the `raw_exec` driver in the client's The `raw_exec` driver will set the following client attributes: -* `driver.raw_exec` - This will be set to "1", indicating the - driver is available. +* `driver.raw_exec` - This will be set to "1", indicating the driver is available. + +Here is an example of using these properties in a job file: + +```hcl +job "docs" { + # Only run this job where raw-exec is enabled. (Note: this constraint is + # applied automatically if you specify a task that uses the raw-exec driver). + constraint { + attribute = "${driver.raw_exec}" + value = "1" + } +} +``` ## Resource Isolation diff --git a/website/source/docs/drivers/rkt.html.md b/website/source/docs/drivers/rkt.html.md index aacb0033c..549b34f2a 100644 --- a/website/source/docs/drivers/rkt.html.md +++ b/website/source/docs/drivers/rkt.html.md @@ -47,7 +47,7 @@ The `rkt` driver supports the following configuration in the job spec: ## Task 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 @@ -66,6 +66,19 @@ this by executing `rkt version` on the host and parsing the output version is `0.14.0` * `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 This driver supports CPU and memory isolation by delegating to `rkt`. Network isolation From 36da4df3b14bf92f326f7f678388960233d25154 Mon Sep 17 00:00:00 2001 From: Seth Vargo Date: Mon, 3 Oct 2016 17:10:53 -0400 Subject: [PATCH 5/6] Remove exec example --- website/source/docs/drivers/exec.html.md | 13 ------------- 1 file changed, 13 deletions(-) diff --git a/website/source/docs/drivers/exec.html.md b/website/source/docs/drivers/exec.html.md index 8de50ae38..84828b501 100644 --- a/website/source/docs/drivers/exec.html.md +++ b/website/source/docs/drivers/exec.html.md @@ -87,19 +87,6 @@ The `exec` driver will set the following client attributes: * `driver.exec` - This will be set to "1", indicating the driver is available. -Here is an example of using these properties in a job file: - -```hcl -job "docs" { - # Only run this job where exec is enabled. (Note: this constraint is applied - # automatically if you specify a task that uses the exec driver). - constraint { - attribute = "${driver.exec}" - value = "1" - } -} -``` - ## Resource Isolation The resource isolation provided varies by the operating system of From 3fd682076c869f6ccccdbf8b6c17075cd2664c2a Mon Sep 17 00:00:00 2001 From: Seth Vargo Date: Mon, 3 Oct 2016 17:11:10 -0400 Subject: [PATCH 6/6] Remove raw-exec example --- website/source/docs/drivers/raw_exec.html.md | 13 ------------- 1 file changed, 13 deletions(-) diff --git a/website/source/docs/drivers/raw_exec.html.md b/website/source/docs/drivers/raw_exec.html.md index 48d4d7d22..6877ee7ad 100644 --- a/website/source/docs/drivers/raw_exec.html.md +++ b/website/source/docs/drivers/raw_exec.html.md @@ -88,19 +88,6 @@ The `raw_exec` driver will set the following client attributes: * `driver.raw_exec` - This will be set to "1", indicating the driver is available. -Here is an example of using these properties in a job file: - -```hcl -job "docs" { - # Only run this job where raw-exec is enabled. (Note: this constraint is - # applied automatically if you specify a task that uses the raw-exec driver). - constraint { - attribute = "${driver.raw_exec}" - value = "1" - } -} -``` - ## Resource Isolation The `raw_exec` driver provides no isolation.