Fix formatting and add more examples to driver docs
This commit is contained in:
Seth Vargo
parent
b96fd48263
commit
cbfa0b2df5
|
|
@ -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 = {
|
||||
|
||||
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
|
||||
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,8 +166,8 @@ The `auth` object supports the following keys:
|
|||
|
||||
Example:
|
||||
|
||||
```
|
||||
task "secretservice" {
|
||||
```hcl
|
||||
task "example" {
|
||||
driver = "docker"
|
||||
|
||||
config {
|
||||
|
|
@ -157,8 +181,8 @@ task "secretservice" {
|
|||
}
|
||||
```
|
||||
|
||||
**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,8 +199,8 @@ 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" {
|
||||
```hcl
|
||||
task "example" {
|
||||
driver = "docker"
|
||||
|
||||
resources {
|
||||
|
|
@ -216,17 +240,10 @@ 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" {
|
||||
```hcl
|
||||
task "example" {
|
||||
driver = "docker"
|
||||
|
||||
resources {
|
||||
network {
|
||||
mbits = 20
|
||||
port "redis" {}
|
||||
}
|
||||
}
|
||||
|
||||
config {
|
||||
image = "redis"
|
||||
|
||||
|
|
@ -234,6 +251,13 @@ task "redis" {
|
|||
redis = 6379
|
||||
}
|
||||
}
|
||||
|
||||
resources {
|
||||
network {
|
||||
mbits = 20
|
||||
port "redis" {}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
|
|
@ -320,7 +344,7 @@ config file.
|
|||
|
||||
An example is given below:
|
||||
|
||||
```
|
||||
```hcl
|
||||
client {
|
||||
options = {
|
||||
"docker.cleanup.image" = "false"
|
||||
|
|
|
|||
|
|
@ -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,43 +36,40 @@ 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:
|
||||
|
||||
```
|
||||
```hcl
|
||||
task "example" {
|
||||
driver = "exec"
|
||||
|
||||
config {
|
||||
# When running a binary that exists on the host, the path must be absolute
|
||||
# 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):
|
||||
To execute a binary downloaded from an
|
||||
[`artifact`](/docs/jobspec/index.html#artifact_doc):
|
||||
|
||||
```
|
||||
```hcl
|
||||
task "example" {
|
||||
driver = "exec"
|
||||
|
||||
config {
|
||||
command = "binary.bin"
|
||||
command = "name-of-my-binary"
|
||||
}
|
||||
|
||||
artifact {
|
||||
source = "https://dl.dropboxusercontent.com/u/1234/binary.bin"
|
||||
source = "https://internal.file.server/name-of-my-binary"
|
||||
options {
|
||||
checksum = "sha256:abd123445ds4555555555"
|
||||
}
|
||||
|
|
@ -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).
|
||||
|
|
|
|||
|
|
@ -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,7 +46,7 @@ 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"
|
||||
|
||||
|
|
@ -48,15 +55,16 @@ task "web" {
|
|||
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
|
||||
|
|
|
|||
|
|
@ -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,28 +24,46 @@ 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" {
|
||||
|
|
@ -60,7 +78,7 @@ task "virtual" {
|
|||
# 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
|
||||
|
|
|
|||
|
|
@ -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,14 +34,10 @@ 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
|
||||
|
||||
|
|
@ -41,7 +48,7 @@ To run a binary present on the Node:
|
|||
driver = "raw_exec"
|
||||
|
||||
config {
|
||||
# When running a binary that exists on the host, the path must be absolute
|
||||
# When running a binary that exists on the host, the path must be absolute/
|
||||
command = "/bin/sleep"
|
||||
args = ["1"]
|
||||
}
|
||||
|
|
@ -55,11 +62,11 @@ To execute a binary downloaded from an [`artifact`](/docs/jobspec/index.html#art
|
|||
driver = "raw_exec"
|
||||
|
||||
config {
|
||||
command = "binary.bin"
|
||||
command = "name-of-my-binary"
|
||||
}
|
||||
|
||||
artifact {
|
||||
source = "https://dl.dropboxusercontent.com/u/1234/binary.bin"
|
||||
source = "https://internal.file.server/name-of-my-binary"
|
||||
options {
|
||||
checksum = "sha256:abd123445ds4555555555"
|
||||
}
|
||||
|
|
@ -69,10 +76,10 @@ To execute a binary downloaded from an [`artifact`](/docs/jobspec/index.html#art
|
|||
|
||||
## 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 {
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
Loading…
Reference in New Issue