From cbfa0b2df559a226b818bce5163d9b78e55ecacc Mon Sep 17 00:00:00 2001 From: Seth Vargo Date: Mon, 3 Oct 2016 17:35:20 -0400 Subject: [PATCH] Fix formatting and add more examples to driver docs --- website/source/docs/drivers/docker.html.md | 138 +++++++++++-------- website/source/docs/drivers/exec.html.md | 101 ++++++++------ website/source/docs/drivers/java.html.md | 36 +++-- website/source/docs/drivers/qemu.html.md | 56 +++++--- website/source/docs/drivers/raw_exec.html.md | 75 +++++----- website/source/docs/drivers/rkt.html.md | 51 +++++-- 6 files changed, 284 insertions(+), 173 deletions(-) diff --git a/website/source/docs/drivers/docker.html.md b/website/source/docs/drivers/docker.html.md index 2b9b4d43b..6051a5fb1 100644 --- a/website/source/docs/drivers/docker.html.md +++ b/website/source/docs/drivers/docker.html.md @@ -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 diff --git a/website/source/docs/drivers/exec.html.md b/website/source/docs/drivers/exec.html.md index 84828b501..9ee1be5a5 100644 --- a/website/source/docs/drivers/exec.html.md +++ b/website/source/docs/drivers/exec.html.md @@ -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). diff --git a/website/source/docs/drivers/java.html.md b/website/source/docs/drivers/java.html.md index 35e25e72a..64efe00a3 100644 --- a/website/source/docs/drivers/java.html.md +++ b/website/source/docs/drivers/java.html.md @@ -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 diff --git a/website/source/docs/drivers/qemu.html.md b/website/source/docs/drivers/qemu.html.md index 6eedcb5b3..954ad9617 100644 --- a/website/source/docs/drivers/qemu.html.md +++ b/website/source/docs/drivers/qemu.html.md @@ -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 diff --git a/website/source/docs/drivers/raw_exec.html.md b/website/source/docs/drivers/raw_exec.html.md index 6877ee7ad..04f51e59b 100644 --- a/website/source/docs/drivers/raw_exec.html.md +++ b/website/source/docs/drivers/raw_exec.html.md @@ -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 diff --git a/website/source/docs/drivers/rkt.html.md b/website/source/docs/drivers/rkt.html.md index 549b34f2a..6f83e636a 100644 --- a/website/source/docs/drivers/rkt.html.md +++ b/website/source/docs/drivers/rkt.html.md @@ -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.