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

Fix formatting and add more examples to driver docs

Browse source
This commit is contained in:
Seth Vargo 2016-10-03 17:35:20 -04:00
parent b96fd48263
commit cbfa0b2df5
No known key found for this signature in database
GPG key ID: 905A90C2949E8787
6 changed files with 284 additions and 173 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

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

@ -16,24 +16,30 @@ and cleaning up after containers.
## Task Configuration
The `docker` driver is configured via a `config` block:
```
```hcl
task "webservice" {
driver = "docker"
config = {
image = "redis"
labels = {
group = "webservice-cache"
}
driver = "docker"
config {
image = "redis:3.2"
labels {
group = "webservice-cache"
}
}
}
```
The following options are available for use in the job specification.
The `docker` driver supports the following configuration in the job spec:
* `image` - The Docker image to run. The image may include a tag or custom URL and should include `https://` if required.
By default it will be fetched from Docker Hub.
* `image` - The Docker image to run. The image may include a tag or custom URL
and should include `https://` if required. By default it will be fetched from
Docker Hub.
```hcl
config {
image = "https://hub.docker.internal/redis:3.2"
}
````
* `load` - (Optional) A list of paths to image archive files. If
this key is not specified, Nomad assumes the `image` is hosted on a repository
@ -43,6 +49,12 @@ The following options are available for use in the job specification.
* `command` - (Optional) The command to run when starting the container.
```hcl
config {
command = "my-command"
}
```
* `args` - (Optional) A list of arguments to the optional `command`. If no
`command` is specified, the args are passed directly to the container.
References to environment variables or any [interpretable Nomad
@ -50,16 +62,28 @@ The following options are available for use in the job specification.
launching the task. For example:
```hcl
args = [
"${nomad.datacenter}",
"${MY_ENV}",
"${meta.foo}",
]
config {
args = [
"-bind", "${NOMAD_PORT_http}",
"${nomad.datacenter}",
"${MY_ENV}",
"${meta.foo}",
]
}
```
* `labels` - (Optional) A key/value map of labels to set to the containers on
start.
```hcl
config {
labels {
foo = "bar"
zip = "zap"
}
}
```
* `privileged` - (Optional) `true` or `false` (default). Privileged mode gives
the container access to devices on the host. Note that this also requires the
nomad agent and docker daemon to be configured to allow privileged
@ -142,23 +166,23 @@ The `auth` object supports the following keys:
Example:
```
task "secretservice" {
driver = "docker"
```hcl
task "example" {
driver = "docker"
config {
image = "secret/service"
config {
image = "secret/service"
auth {
username = "dockerhub_user"
password = "dockerhub_password"
}
auth {
username = "dockerhub_user"
password = "dockerhub_password"
}
}
}
```
**Please note that these credentials are stored in Nomad in plain text.**
Secrets management will be added in a later release.
!> **Be Careful!** At this time these credentials are stored in Nomad in plain
text. Secrets management will be added in a later release.
## Networking
@ -175,16 +199,16 @@ scope of Nomad.
You can allocate ports to your task using the port syntax described on the
[networking page](/docs/jobspec/networking.html). Here is a recap:
```
task "webservice" {
driver = "docker"
```hcl
task "example" {
driver = "docker"
resources {
network {
port "http" {}
port "https" {}
}
resources {
network {
port "http" {}
port "https" {}
}
}
}
```
@ -216,24 +240,24 @@ performance.
If you prefer to use the traditional port-mapping method, you can specify the
`port_map` option in your job specification. It looks like this:
```
task "redis" {
driver = "docker"
```hcl
task "example" {
driver = "docker"
resources {
network {
mbits = 20
port "redis" {}
}
config {
image = "redis"
port_map {
redis = 6379
}
}
config {
image = "redis"
port_map {
redis = 6379
}
resources {
network {
mbits = 20
port "redis" {}
}
}
}
```
@ -320,12 +344,12 @@ config file.
An example is given below:
```
client {
options = {
"docker.cleanup.image" = "false"
}
}
```hcl
client {
options = {
"docker.cleanup.image" = "false"
}
}
```
## Agent Attributes

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

@ -18,6 +18,17 @@ scripts or other wrappers which provide higher level features.
## Task Configuration
```hcl
task "webservice" {
driver = "exec"
config {
command = "my-binary"
args = ["-flag", "1"]
}
}
```
The `exec` driver supports the following configuration in the job spec:
* `command` - The command to execute. Must be provided. If executing a binary
@ -25,48 +36,45 @@ The `exec` driver supports the following configuration in the job spec:
is downloaded from an [`artifact`](/docs/jobspec/index.html#artifact_doc), the
path can be relative from the allocations's root directory.
* `args` - (Optional) A list of arguments to the optional `command`.
References to environment variables or any [interpretable Nomad
variables](/docs/jobspec/interpreted.html) will be interpreted
before launching the task. For example:
```
args = ["${nomad.datacenter}", "${MY_ENV}", "${meta.foo}"]
```
* `args` - (Optional) A list of arguments to the optional `command`. References
to environment variables or any [interpretable Nomad
variables](/docs/jobspec/interpreted.html) will be interpreted before
launching the task.
## Examples
To run a binary present on the Node:
```
task "example" {
driver = "exec"
```hcl
task "example" {
driver = "exec"
config {
# When running a binary that exists on the host, the path must be absolute
command = "/bin/sleep"
args = ["1"]
}
}
```
To execute a binary downloaded from an [`artifact`](/docs/jobspec/index.html#artifact_doc):
```
task "example" {
driver = "exec"
config {
command = "binary.bin"
}
artifact {
source = "https://dl.dropboxusercontent.com/u/1234/binary.bin"
options {
checksum = "sha256:abd123445ds4555555555"
}
config {
# When running a binary that exists on the host, the path must be absolute.
command = "/bin/sleep"
args = ["1"]
}
}
```
To execute a binary downloaded from an
[`artifact`](/docs/jobspec/index.html#artifact_doc):
```hcl
task "example" {
driver = "exec"
config {
command = "name-of-my-binary"
}
artifact {
source = "https://internal.file.server/name-of-my-binary"
options {
checksum = "sha256:abd123445ds4555555555"
}
}
}
```
## Client Requirements
@ -76,9 +84,14 @@ The `exec` driver can only be run when on Linux and running Nomad as root.
is only guaranteed on Linux. Further, the host must have cgroups mounted properly
in order for the driver to work.
If you are receiving the error `* Constraint "missing drivers" filtered <> nodes`
and using the exec driver, check to ensure that you are running Nomad as root. This
also applies for running Nomad in -dev mode.
If you are receiving the error:
```
* Constraint "missing drivers" filtered <> nodes
```
and using the exec driver, check to ensure that you are running Nomad as root.
This also applies for running Nomad in -dev mode.
## Client Attributes
@ -99,8 +112,18 @@ resources of a process and as such the Nomad agent must be run as root.
The chroot is populated with data in the following directories from the host
machine:
`["/bin", "/etc", "/lib", "/lib32", "/lib64", "/run/resolvconf", "/sbin",
"/usr"]`
```
[
"/bin",
"/etc",
"/lib",
"/lib32",
"/lib64",
"/run/resolvconf",
"/sbin",
"/usr",
]
```
This list is configurable through the agent client
[configuration file](/docs/agent/config.html#chroot_env).

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

@ -10,12 +10,23 @@ description: |-
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
client via the [`artifact` downloader](/docs/jobspec/index.html#artifact_doc).
## Task Configuration
```hcl
task "webservice" {
driver = "java"
config {
jar_path = "local/exaple.jar"
jvm_options = ["-Xmx2048m", "-Xms256m"]
}
}
```
The `java` driver supports the following configuration in the job spec:
* `jar_path` - The path to the downloaded Jar. In most cases this will just be
@ -23,14 +34,10 @@ The `java` driver supports the following configuration in the job spec:
contains the Jar in a subfolder, the path will need to be the relative path
(`subdir/from_archive/my.jar`).
* `args` - (Optional) A list of arguments to the optional `command`.
References to environment variables or any [interpretable Nomad
variables](/docs/jobspec/interpreted.html) will be interpreted
before launching the task. For example:
```
args = ["${nomad.datacenter}", "${MY_ENV}", "${meta.foo}"]
```
* `args` - (Optional) A list of arguments to the optional `command`. References
to environment variables or any [interpretable Nomad
variables](/docs/jobspec/interpreted.html) will be interpreted before
launching the task.
* `jvm_options` - (Optional) A list of JVM options to be passed while invoking
java. These options are passed without being validated in any way by Nomad.
@ -39,24 +46,25 @@ The `java` driver supports the following configuration in the job spec:
A simple config block to run a Java Jar:
```
```hcl
task "web" {
driver = "java"
config {
jar_path = "local/hello.jar"
jar_path = "local/hello.jar"
jvm_options = ["-Xmx2048m", "-Xms256m"]
}
# Specifying an artifact is required with the "java"
# driver. This is the # mechanism to ship the Jar to be run.
# Specifying an artifact is required with the "java" driver. This is the
# mechanism to ship the Jar to be run.
artifact {
source = "https://dl.dropboxusercontent.com/u/1234/hello.jar"
source = "https://internal.file.server/hello.jar"
options {
checksum = "md5:123445555555555"
}
}
}
```
## Client Requirements

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

@ -10,13 +10,13 @@ description: |-
Name: `qemu`
The `Qemu` driver provides a generic virtual machine runner. Qemu can utilize
The `qemu` driver provides a generic virtual machine runner. Qemu can utilize
the KVM kernel module to utilize hardware virtualization features and provide
great performance. Currently the `Qemu` driver can map a set of ports from the
great performance. Currently the `qemu` driver can map a set of ports from the
host machine to the guest virtual machine, and provides configuration for
resource allocation.
The `Qemu` driver can execute any regular `qemu` image (e.g. `qcow`, `img`,
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
@ -24,43 +24,61 @@ The driver requires the image to be accessible from the Nomad client via the
## Task Configuration
The `Qemu` driver supports the following configuration in the job spec:
```hcl
task "webservice" {
driver = "qemu"
* `image_path` - The path to the downloaded image. In most cases this will just be
the name of the image. However, if the supplied artifact is an archive that
config {
image_path = "/path/to/my/linux.img"
accelerator = "kvm"
args = ["-nodefaults", "-nodefconfig"]
}
}
```
The `qemu` driver supports the following configuration in the job spec:
* `image_path` - The path to the downloaded image. In most cases this will just
be the name of the image. However, if the supplied artifact is an archive that
contains the image in a subfolder, the path will need to be the relative path
(`subdir/from_archive/my.img`).
* `accelerator` - (Optional) The type of accelerator to use in the invocation.
If the host machine has `Qemu` installed with KVM support, users can specify
If the host machine has `qemu` installed with KVM support, users can specify
`kvm` for the `accelerator`. Default is `tcg`.
* `port_map` - (Optional) A `map[string]int` that maps port labels to ports
on the guest. This forwards the host port to the guest VM. For example,
`port_map { db = 6539 }` would forward the host port with label `db` to the
guest VM's port 6539.
* `port_map` - (Optional) A key/value map of port labels.
* `args` - (Optional) A `[]string` that is passed to qemu as command line options.
For example, `args = [ "-nodefconfig", "-nodefaults" ]`.
```hcl
config {
# Forward the host port with the label "db" to the guest VM's port 6539.
port_map {
db = 6539
}
}
```
* `args` - (Optional) A list of strings that is passed to qemu as command line
options.
## Examples
A simple config block to run a `Qemu` image:
A simple config block to run a `qemu` image:
```
task "virtual" {
driver = "qemu"
config {
image_path = "local/linux.img"
image_path = "local/linux.img"
accelerator = "kvm"
args = [ "-nodefaults", "-nodefconfig" ]
args = ["-nodefaults", "-nodefconfig"]
}
# Specifying an artifact is required with the "qemu"
# driver. This is the # mechanism to ship the image to be run.
artifact {
source = "https://dl.dropboxusercontent.com/u/1234/linux.img"
source = "https://internal.file.server/linux.img"
options {
checksum = "md5:123445555555555"
@ -70,13 +88,13 @@ task "virtual" {
## Client Requirements
The `Qemu` driver requires Qemu to be installed and in your system's `$PATH`.
The `qemu` driver requires Qemu to be installed and in your system's `$PATH`.
The task must also specify at least one artifact to download, as this is the only
way to retrieve the image being run.
## Client Attributes
The `Qemu` driver will set the following client attributes:
The `qemu` driver will set the following client attributes:
* `driver.qemu` - Set to `1` if Qemu is found on the host node. Nomad determines
this by executing `qemu-system-x86_64 -version` on the host and parsing the output

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

@ -16,6 +16,17 @@ As such, it should be used with extreme care and is disabled by default.
## Task Configuration
```hcl
task "webservice" {
driver = "raw_exec"
config {
command = "my-binary"
args = ["-flag", "1"]
}
}
```
The `raw_exec` driver supports the following configuration in the job spec:
* `command` - The command to execute. Must be provided. If executing a binary
@ -23,63 +34,59 @@ The `raw_exec` driver supports the following configuration in the job spec:
is downloaded from an [`artifact`](/docs/jobspec/index.html#artifact_doc), the
path can be relative from the allocations's root directory.
* `args` - (Optional) A list of arguments to the optional `command`.
References to environment variables or any [interpretable Nomad
variables](/docs/jobspec/interpreted.html) will be interpreted
before launching the task. For example:
```
args = ["${nomad.datacenter}", "${MY_ENV}", "${meta.foo}"]
```
* `args` - (Optional) A list of arguments to the optional `command`. References
to environment variables or any [interpretable Nomad
variables](/docs/jobspec/interpreted.html) will be interpreted before
launching the task. For example:
## Examples
To run a binary present on the Node:
```
task "example" {
driver = "raw_exec"
task "example" {
driver = "raw_exec"
config {
# When running a binary that exists on the host, the path must be absolute
command = "/bin/sleep"
args = ["1"]
}
config {
# When running a binary that exists on the host, the path must be absolute/
command = "/bin/sleep"
args = ["1"]
}
}
```
To execute a binary downloaded from an [`artifact`](/docs/jobspec/index.html#artifact_doc):
```
task "example" {
driver = "raw_exec"
task "example" {
driver = "raw_exec"
config {
command = "binary.bin"
}
config {
command = "name-of-my-binary"
}
artifact {
source = "https://dl.dropboxusercontent.com/u/1234/binary.bin"
options {
checksum = "sha256:abd123445ds4555555555"
}
artifact {
source = "https://internal.file.server/name-of-my-binary"
options {
checksum = "sha256:abd123445ds4555555555"
}
}
}
```
## Client Requirements
The `raw_exec` driver can run on all supported operating systems. It is however
disabled by default. In order to be enabled, the Nomad client configuration must
explicitly enable the `raw_exec` driver in the client's
[options](/docs/agent/config.html#options) field:
The `raw_exec` driver can run on all supported operating systems. For security
reasons, it is disabled by default. To enable raw exec, the Nomad client
configuration must explicitly enable the `raw_exec` driver in the client's
[options](/docs/agent/config.html#options):
```
client {
options = {
"driver.raw_exec.enable" = "1"
}
}
client {
options = {
"driver.raw_exec.enable" = "1"
}
}
```
## Client Attributes

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

@ -6,31 +6,62 @@ description: |-
The rkt task driver is used to run application containers using rkt.
---
# Rkt Driver - Experimental
# Rkt Driver
Name: `rkt`
The `rkt` driver provides an interface for using CoreOS rkt for running
application containers. Currently, the driver supports launching containers but
application containers.
~> **Experimental!** Currently, the rkt driver supports launching containers but
does not support dynamic ports. This can lead to port conflicts and as such,
this driver is being marked as experimental and should be used with care.
## Task Configuration
```hcl
task "webservice" {
driver = "rkt"
config {
image = "redis:3.2"
}
}
```
The `rkt` driver supports the following configuration in the job spec:
* `image` - The image to run. May be specified by name, hash, ACI address
or docker registry.
```hcl
config {
image = "https://hub.docker.internal/redis:3.2"
}
```
* `command` - (Optional) A command to execute on the ACI.
* `args` - (Optional) A list of arguments to the optional `command`.
References to environment variables or any [interpretable Nomad
variables](/docs/jobspec/interpreted.html) will be interpreted
before launching the task. For example:
```hcl
config {
command = "my-command"
}
```
args = ["${nomad.datacenter}", "${MY_ENV}", ${meta.foo}"]
* `args` - (Optional) A list of arguments to the optional `command`. References
to environment variables or any [interpretable Nomad
variables](/docs/jobspec/interpreted.html) will be interpreted before
launching the task.
```hcl
config {
args = [
"-bind", "${NOMAD_PORT_http}",
"${nomad.datacenter}",
"${MY_ENV}",
"${meta.foo}",
]
}
```
* `trust_prefix` - (Optional) The trust prefix to be passed to rkt. Must be
@ -81,5 +112,5 @@ job "docs" {
## Resource Isolation
This driver supports CPU and memory isolation by delegating to `rkt`. Network isolation
is not supported as of now.
This driver supports CPU and memory isolation by delegating to `rkt`. Network
isolation is not supported as of now.