From d49b191cd7ca98d34a7610ef31945fbb60c387fe Mon Sep 17 00:00:00 2001 From: Ben Barnard Date: Tue, 11 Oct 2016 15:52:50 -0400 Subject: [PATCH] Minor documentation edits for grammar and clarity These are things I noticed as I read through the documentation. There are a couple of minor substantive corrections as well. --- website/source/docs/agent/config.html.md | 24 +++++++------- website/source/docs/agent/index.html.md | 8 ++--- .../docs/commands/eval-status.html.md.erb | 2 +- website/source/docs/commands/fs.html.md.erb | 8 ++--- website/source/docs/commands/logs.html.md.erb | 4 +-- website/source/docs/commands/plan.html.md.erb | 4 +-- website/source/docs/commands/run.html.md.erb | 4 +-- .../source/docs/commands/validate.html.md.erb | 4 +-- website/source/docs/drivers/docker.html.md | 9 ++--- website/source/docs/drivers/exec.html.md | 2 +- website/source/docs/drivers/java.html.md | 2 +- website/source/docs/drivers/raw_exec.html.md | 4 +-- website/source/docs/faq.html.md | 2 +- website/source/docs/http/client-fs.html.md | 2 +- website/source/docs/http/job.html.md | 4 +-- website/source/docs/install/index.html.md | 4 +-- .../source/docs/jobspec/environment.html.md | 12 +++---- website/source/docs/jobspec/index.html.md | 2 +- .../source/docs/jobspec/interpreted.html.md | 2 +- website/source/docs/jobspec/json.html.md | 27 +++++++-------- .../source/docs/jobspec/networking.html.md | 4 +-- .../source/docs/jobspec/schedulers.html.md | 6 ++-- .../docs/jobspec/servicediscovery.html.md | 33 +++++++++---------- 23 files changed, 84 insertions(+), 89 deletions(-) diff --git a/website/source/docs/agent/config.html.md b/website/source/docs/agent/config.html.md index 13d914c3f..5c80398bc 100644 --- a/website/source/docs/agent/config.html.md +++ b/website/source/docs/agent/config.html.md @@ -263,10 +263,10 @@ integration and are entirely optional. `host:port`. Defaults to `127.0.0.1:8500`, which is the same as the Consul default HTTP address. - * `token`: Token is used to provide a per-request ACL token. This options + * `token`: Token is used to provide a per-request ACL token. This option overrides the Consul Agent's default token. - * `auth`: The auth information to use for http access to the Consul Agent + * `auth`: The auth information to use for HTTP access to the Consul Agent given as `username:password`. * `ssl`: This boolean option sets the transport scheme to talk to the Consul @@ -440,9 +440,9 @@ configured on server nodes. `max_kill_timeout` is used. This is to prevent a user being able to set an unreasonable timeout. If unset, a default is used. - * `reserved`: `reserved` is used to reserve a portion of the nodes resources + * `reserved`: `reserved` is used to reserve a portion of the node's resources from being used by Nomad when placing tasks. It can be used to target - a certain capacity usage for the node. For example, 20% of the nodes CPU + a certain capacity usage for the node. For example, 20% of the node's CPU could be reserved to target a CPU utilization of 80%. The block has the following format: @@ -458,7 +458,7 @@ configured on server nodes. * `cpu`: `cpu` is given as MHz to reserve. * `memory`: `memory` is given as MB to reserve. * `disk`: `disk` is given as MB to reserve. - * `reserved_ports`: `reserved_ports` is a comma separated list of ports + * `reserved_ports`: `reserved_ports` is a comma-separated list of ports to reserve on all fingerprinted network devices. Ranges can be specified by using a hyphen separated the two inclusive ends. @@ -469,13 +469,13 @@ Client, but rather the set of options that configure the Client and not the drivers. To find the options supported by an individual driver, see the drivers documentation [here](/docs/drivers/index.html) -* `driver.whitelist`: A comma separated list of whitelisted drivers (e.g. +* `driver.whitelist`: A comma-separated list of whitelisted drivers (e.g. "docker,qemu"). If specified, drivers not in the whitelist will be disabled. If the whitelist is empty, all drivers are fingerprinted and enabled where applicable. * `env.blacklist`: Nomad passes the host environment variables to `exec`, - `raw_exec` and `java` tasks. `env.blacklist` is a comma separated list of + `raw_exec` and `java` tasks. `env.blacklist` is a comma-separated list of environment variable keys not to pass to these tasks. If specified, the defaults are overridden. The following are the default: @@ -500,14 +500,14 @@ documentation [here](/docs/drivers/index.html) * `qemu` * `java` -* `fingerprint.whitelist`: A comma separated list of whitelisted fingerprinters. +* `fingerprint.whitelist`: A comma-separated list of whitelisted fingerprinters. If specified, fingerprinters not in the whitelist will be disabled. If the whitelist is empty, all fingerprinters are used. ### Client ChrootEnv Map Drivers based on [Isolated Fork/Exec](/docs/drivers/exec.html) implement file -system isolation using chroot on Linux. The `chroot_env` map allows the chroot +system isolation using chroot on Linux. The `chroot_env` map allows the chroot environment to be configured using source paths on the host operating system. The mapping format is: `source_path -> dest_path`. @@ -534,7 +534,7 @@ environment with the most commonly used parts of the operating system. See A subset of the available Nomad agent configuration can optionally be passed in via CLI arguments. The `agent` command accepts the following arguments: -* `alloc-dir=`: Equivalent to the Client [alloc_dir](#alloc_dir) config +* `-alloc-dir=`: Equivalent to the Client [alloc_dir](#alloc_dir) config option. * `-atlas=`: Equivalent to the Atlas [infrastructure](#infrastructure) config option. @@ -555,9 +555,9 @@ via CLI arguments. The `agent` command accepts the following arguments: be specified multiple times to specify multiple agents to join. * `-log-level=`: Equivalent to the [log_level](#log_level) config option. * `-meta=`: Equivalent to the Client [meta](#meta) config option. -* `-network-interface`: Equivalent to the Client +* `-network-interface=`: Equivalent to the Client [network_interface](#network_interface) config option. -* `-network-speed`: Equivalent to the Client +* `-network-speed=`: Equivalent to the Client [network_speed](#network_speed) config option. * `-node=`: Equivalent to the [name](#name) config option. * `-node-class=`: Equivalent to the Client [node_class](#node_class) diff --git a/website/source/docs/agent/index.html.md b/website/source/docs/agent/index.html.md index 51e7d149f..d5c6914ed 100644 --- a/website/source/docs/agent/index.html.md +++ b/website/source/docs/agent/index.html.md @@ -92,13 +92,13 @@ respective signals. When gracefully exiting, clients will update their status to terminal on the servers so that tasks can be migrated to healthy agents. Servers will notify their intention to leave the cluster which allows them to -leave the [consensus quorum](/docs/internals/consensus.html). +leave the [consensus](/docs/internals/consensus.html) peer set. It is especially important that a server node be allowed to leave gracefully so that there will be a minimal impact on availability as the server leaves -the consensus quorum. If a server does not gracefully leave, and will not +the consensus peer set. If a server does not gracefully leave, and will not return into service, the [`server-force-leave` command](/docs/commands/server-force-leave.html) -should be used to eject it from the consensus quorum. +should be used to eject it from the consensus peer set. ## Lifecycle @@ -135,5 +135,5 @@ to the entire cluster, meaning all nodes will eventually be aware of each other. When a server _leaves_, it specifies its intent to do so, and the cluster marks that node as having _left_. If the server has _left_, replication to it will stop and it -is removed as a member of the consensus quorum. If the server has _failed_, replication +is removed from the consensus peer set. If the server has _failed_, replication will attempt to make progress to recover from a software or network failure. diff --git a/website/source/docs/commands/eval-status.html.md.erb b/website/source/docs/commands/eval-status.html.md.erb index 792717175..05a8c23b1 100644 --- a/website/source/docs/commands/eval-status.html.md.erb +++ b/website/source/docs/commands/eval-status.html.md.erb @@ -14,7 +14,7 @@ evaluation. In the case an evaluation could not place all the requested allocations, this command can be used to determine the failure reasons. Optionally, it can also be invoked in a monitor mode to track an outstanding -evaluation. In this mode, ogs will be output describing state changes to the +evaluation. In this mode, logs will be output describing state changes to the evaluation or its associated allocations. The monitor will exit when the evaluation reaches a terminal state. diff --git a/website/source/docs/commands/fs.html.md.erb b/website/source/docs/commands/fs.html.md.erb index 4870a62b4..4e96237ca 100644 --- a/website/source/docs/commands/fs.html.md.erb +++ b/website/source/docs/commands/fs.html.md.erb @@ -26,8 +26,8 @@ client. The following functionalities are available - `cat`, `tail`, `ls` and nomad fs [options] ``` -This command accepts a path and single allocation ID unless the `-job` flag is -specified, in which case an allocation is chosen for the given job. The path is +This command accepts a single allocation ID (unless the `-job` flag is specified, +in which case an allocation is chosen from the given job) and a path. The path is relative to the root of the allocation directory. The path is optional and it defaults to `/` of the allocation directory. @@ -41,14 +41,14 @@ defaults to `/` of the allocation directory. * `-verbose`: Display verbose output. -* `-job`: Use a random allocation from the specified job, prefering a running +* `-job`: Use a random allocation from the specified job, preferring a running allocation. * `-stat`: Show stat information instead of displaying the file, or listing the directory. * `-f`: Causes the output to not stop when the end of the file is reached, but -rather to wait for additional output. +rather to wait for additional output. * `-tail`: Show the files contents with offsets relative to the end of the file. If no offset is given, -n is defaulted to 10. diff --git a/website/source/docs/commands/logs.html.md.erb b/website/source/docs/commands/logs.html.md.erb index a00b12d1c..8c4de0191 100644 --- a/website/source/docs/commands/logs.html.md.erb +++ b/website/source/docs/commands/logs.html.md.erb @@ -16,7 +16,7 @@ The `logs` command displays the log of a given task. nomad logs [options] ``` -This commands streams the logs of the given task in the allocation. If the +This command streams the logs of the given task in the allocation. If the allocation is only running a single task, the task name can be omitted. Optionally, the `-job` option may be used in which case a random allocation from the given job will be chosen. @@ -35,7 +35,7 @@ the given job will be chosen. allocation. * `-f`: Causes the output to not stop when the end of the logs are reached, but -rather to wait for additional output. +rather to wait for additional output. * `-tail`: Show the logs contents with offsets relative to the end of the logs. If no offset is given, -n is defaulted to 10. diff --git a/website/source/docs/commands/plan.html.md.erb b/website/source/docs/commands/plan.html.md.erb index e47194992..10604ea4a 100644 --- a/website/source/docs/commands/plan.html.md.erb +++ b/website/source/docs/commands/plan.html.md.erb @@ -24,8 +24,8 @@ containing a [HCL job specification](/docs/jobspec/index.html). This file will be read and the job checked for any problems. If the supplied path is "-", the jobfile is read from STDIN. Otherwise it is read from the file at the supplied path or downloaded and read from URL specified. -Nomad downloads jobfile using [`go-getter`](https://github.com/hashicorp/go-getter) -and support `go-getter` syntax. +Nomad downloads the jobfile using [`go-getter`](https://github.com/hashicorp/go-getter) +and supports `go-getter` syntax. Plan invokes a dry-run of the scheduler to determine the effects of submitting either a new or updated version of a job. The plan will not result in any diff --git a/website/source/docs/commands/run.html.md.erb b/website/source/docs/commands/run.html.md.erb index 303fb7a37..95a7be81b 100644 --- a/website/source/docs/commands/run.html.md.erb +++ b/website/source/docs/commands/run.html.md.erb @@ -23,8 +23,8 @@ containing a valid [job specification](/docs/jobspec/index.html). This file will be read and the job will be submitted to Nomad for scheduling. If the supplied path is "-", the jobfile is read from STDIN. Otherwise it is read from the file at the supplied path or downloaded and read from URL specified. -Nomad downloads jobfile using [`go-getter`](https://github.com/hashicorp/go-getter) -and support `go-getter` syntax. +Nomad downloads the jobfile using [`go-getter`](https://github.com/hashicorp/go-getter) +and supports `go-getter` syntax. By default, on successful job submission the run command will enter an interactive monitor and display log information detailing the scheduling diff --git a/website/source/docs/commands/validate.html.md.erb b/website/source/docs/commands/validate.html.md.erb index 5a05f4568..5bf5e8fb9 100644 --- a/website/source/docs/commands/validate.html.md.erb +++ b/website/source/docs/commands/validate.html.md.erb @@ -22,8 +22,8 @@ containing a [HCL job specification](/docs/jobspec/index.html). This file will be read and the job checked for any problems. If the supplied path is "-", the jobfile is read from STDIN. Otherwise it is read from the file at the supplied path or downloaded and read from URL specified. -Nomad downloads jobfile using [`go-getter`](https://github.com/hashicorp/go-getter) -and support `go-getter` syntax. +Nomad downloads the jobfile using [`go-getter`](https://github.com/hashicorp/go-getter) +and supports `go-getter` syntax. On successful validation, exit code 0 will be returned, otherwise an exit code of 1 indicates an error. diff --git a/website/source/docs/drivers/docker.html.md b/website/source/docs/drivers/docker.html.md index 574936205..0b05dabbd 100644 --- a/website/source/docs/drivers/docker.html.md +++ b/website/source/docs/drivers/docker.html.md @@ -102,7 +102,7 @@ The `docker` driver supports the following configuration in the job spec: * `ipc_mode` - (Optional) The IPC mode to be used for the container. The default is `none` for a private IPC namespace. Other values are `host` for sharing the host IPC namespace or the name or id of an existing container. Note that - it is not possible to refer to Nomad started Docker containers since their + it is not possible to refer to Docker containers started by Nomad since their names are not known in advance. Note that setting this option also requires the Nomad agent to be configured to allow privileged containers. @@ -339,11 +339,11 @@ The `docker` driver has the following [client configuration options](/docs/agent/config.html#options): * `docker.endpoint` - Defaults to `unix:///var/run/docker.sock`. You will need - to customize this if you use a non-standard socket (http or another + to customize this if you use a non-standard socket (HTTP or another location). -* `docker.auth.config` - Allows an operator to specify a json file which is in - the dockercfg format containing authentication information for private registry. +* `docker.auth.config` - Allows an operator to specify a JSON file which is in + the dockercfg format containing authentication information for a private registry. * `docker.tls.cert` - Path to the server's certificate file (`.pem`). Specify this along with `docker.tls.key` and `docker.tls.ca` to use a TLS client to @@ -439,6 +439,7 @@ container does not exceed the amount of memory allocated to it, or it will be terminated or crash when it tries to malloc. A process can inspect its memory limit by reading `NOMAD_MEMORY_LIMIT`, but will need to track its own memory usage. Memory limit is expressed in megabytes so 1024 = 1Gb. +HIO!!! ### IO diff --git a/website/source/docs/drivers/exec.html.md b/website/source/docs/drivers/exec.html.md index 9ee1be5a5..83eaf9289 100644 --- a/website/source/docs/drivers/exec.html.md +++ b/website/source/docs/drivers/exec.html.md @@ -36,7 +36,7 @@ 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 +* `args` - (Optional) A list of arguments to the `command`. References to environment variables or any [interpretable Nomad variables](/docs/jobspec/interpreted.html) will be interpreted before launching the task. diff --git a/website/source/docs/drivers/java.html.md b/website/source/docs/drivers/java.html.md index 64efe00a3..91bbb4001 100644 --- a/website/source/docs/drivers/java.html.md +++ b/website/source/docs/drivers/java.html.md @@ -34,7 +34,7 @@ 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 +* `args` - (Optional) A list of arguments to the Jar's main method. References to environment variables or any [interpretable Nomad variables](/docs/jobspec/interpreted.html) will be interpreted before launching the task. diff --git a/website/source/docs/drivers/raw_exec.html.md b/website/source/docs/drivers/raw_exec.html.md index 04f51e59b..fb930b06f 100644 --- a/website/source/docs/drivers/raw_exec.html.md +++ b/website/source/docs/drivers/raw_exec.html.md @@ -34,10 +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 +* `args` - (Optional) A list of arguments to the `command`. References to environment variables or any [interpretable Nomad variables](/docs/jobspec/interpreted.html) will be interpreted before - launching the task. For example: + launching the task. ## Examples diff --git a/website/source/docs/faq.html.md b/website/source/docs/faq.html.md index fede6ee5f..a855fcb38 100644 --- a/website/source/docs/faq.html.md +++ b/website/source/docs/faq.html.md @@ -24,7 +24,7 @@ and [`disable_update_check`](/docs/agent/config.html#disable_update_check). Nomad makes use of a HashiCorp service called [SCADA](http://scada.hashicorp.com) (Supervisory Control And Data Acquisition). The SCADA system allows clients to maintain long-running connections to Atlas. Atlas can in turn provide auto-join facilities for -Nomad agents (supervisory control) and an dashboard showing the state of the system (data acquisition). +Nomad agents (supervisory control) and a dashboard showing the state of the system (data acquisition). Using the SCADA service is optional. SCADA is only enabled by opt-in. diff --git a/website/source/docs/http/client-fs.html.md b/website/source/docs/http/client-fs.html.md index c373eec2a..2278c6d1a 100644 --- a/website/source/docs/http/client-fs.html.md +++ b/website/source/docs/http/client-fs.html.md @@ -192,7 +192,7 @@ allocation was placed.
Description
- Stream a tasks stdout/stderr logs. + Stream a task's stdout/stderr logs.
Method
diff --git a/website/source/docs/http/job.html.md b/website/source/docs/http/job.html.md index c8944ae0b..763c50d6f 100644 --- a/website/source/docs/http/job.html.md +++ b/website/source/docs/http/job.html.md @@ -532,9 +532,9 @@ region is used; another region can be specified using the `?region=` query param
  • Diff A diff structure between the submitted job and the server side version. - The top-level object is a Job Diff which contains, Task Group Diffs + The top-level object is a Job Diff which contains Task Group Diffs, which in turn contain Task Diffs. Each of these objects then has Object - and Field Diff structures in-bedded. + and Field Diff structures embedded.
  • NextPeriodicLaunch diff --git a/website/source/docs/install/index.html.md b/website/source/docs/install/index.html.md index 9457a4e0f..48655fb10 100644 --- a/website/source/docs/install/index.html.md +++ b/website/source/docs/install/index.html.md @@ -25,8 +25,8 @@ Nomad is currently packaged as a zip file. We do not have any near term plans to provide system packages. Once the zip is downloaded, unzip it into any directory. The -`nomad` binary inside is all that is necessary to run Nomad (or -`nomad.exe` for Windows). Any additional files, if any, are not +`nomad` (or `nomad.exe` for Windows) binary inside is all that is +necessary to run Nomad. Any additional files, if any, are not required to run Nomad. Copy the binary to anywhere on your system. If you intend to access it diff --git a/website/source/docs/jobspec/environment.html.md b/website/source/docs/jobspec/environment.html.md index d28c40c9e..21930f1e5 100644 --- a/website/source/docs/jobspec/environment.html.md +++ b/website/source/docs/jobspec/environment.html.md @@ -96,7 +96,7 @@ the memory limit to inform how large your in-process cache should be, or to decide when to flush buffers to disk. Both CPU and memory are presented as integers. The unit for CPU limit is -`1024 = 1Ghz`. The unit for memory is `1 = 1 megabytes`. +`1024 = 1GHz`. The unit for memory is `1 = 1 megabyte`. Writing your applications to adjust to these values at runtime provides greater scheduling flexibility since you can adjust the resource allocations in your @@ -128,17 +128,17 @@ Depending on the driver and operating system being targeted, the directories are made available in various ways. For example, on `docker` the directories are bound to the container, while on `exec` on Linux the directories are mounted into the chroot. Regardless of how the directories are made available, the path to the -directories can be read through the following environment variables: -`NOMAD_ALLOC_DIR` and `NOMAD_TASK_DIR`. +directories can be read through the `NOMAD_ALLOC_DIR` and `NOMAD_TASK_DIR` +environment variables. ## Meta The job specification also allows you to specify a `meta` block to supply arbitrary configuration to a task. This allows you to easily provide job-specific configuration even if you use the same executable unit in multiple jobs. These -key-value pairs are passed through to the job as `NOMAD_META_=`, -where `key` is UPPERCASED from the job specification. +key-value pairs are passed through to the job as `NOMAD_META_=` +environment variables, where `key` is UPPERCASED from the job specification. -Currently there is no enforcement that the meta values be lowercase, but using +Currently there is no enforcement that the meta keys be lowercase, but using multiple keys with the same uppercased representation will lead to undefined behavior. diff --git a/website/source/docs/jobspec/index.html.md b/website/source/docs/jobspec/index.html.md index 5be87bd81..3c0dc33ac 100644 --- a/website/source/docs/jobspec/index.html.md +++ b/website/source/docs/jobspec/index.html.md @@ -410,7 +410,7 @@ The `constraint` object supports the following keys: * `version` - Specifies a version constraint against the attribute. This sets the operator to `version` and the `value` to what is - specified. This supports a comma separated list of constraints, + specified. This supports a comma-separated list of constraints, including the pessimistic operator. See the [go-version](https://github.com/hashicorp/go-version) repository for examples. diff --git a/website/source/docs/jobspec/interpreted.html.md b/website/source/docs/jobspec/interpreted.html.md index 1a06b2603..3f2c3966e 100644 --- a/website/source/docs/jobspec/interpreted.html.md +++ b/website/source/docs/jobspec/interpreted.html.md @@ -7,7 +7,7 @@ description: |- --- # Interpreted Variables -Nomad support interpreting two classes of variables, node attributes and runtime +Nomad supports interpreting two classes of variables, node attributes and runtime environment variables. Node attributes are interpretable in constraints, task environment variables and certain driver fields. Runtime environment variables are not interpretable in constraints because they are only defined once the diff --git a/website/source/docs/jobspec/json.html.md b/website/source/docs/jobspec/json.html.md index be38f6498..458e43663 100644 --- a/website/source/docs/jobspec/json.html.md +++ b/website/source/docs/jobspec/json.html.md @@ -321,15 +321,13 @@ The `Task` object supports the following keys: [Click here](/docs/jobspec/servicediscovery.html) to learn more about services. Below is the fields in the `Service` object: - * `Name`: Nomad automatically determines the name of a Task. By default the - name of a service is `$(job-name)-$(task-group)-$(task-name)`. Users can - explicitly name the service by specifying this option. If multiple - services are defined for a Task then only one task can have the default - name, all the services have to be explicitly named. Users can add the - following to the service names: `${JOB}`, `${TASKGROUP}`, `${TASK}`, - `${BASE}`. Nomad will replace them with the appropriate value of the - Job, Task Group, and Task names while registering the Job. `${BASE}` - expands to `${JOB}-${TASKGROUP}-${TASK}`. Names must be adhere to + * `Name`: An explicit name for the Service. Nomad will replace `${JOB}`, + `${TASKGROUP}` and `${TASK}` by the name of the job, task group or task, + respectively. `${BASE}` expands to the equivalent of + `${JOB}-${TASKGROUP}-${TASK}`, and is the default name for a Service. + Each service defined for a given task must have a distinct name, so if + a task has multiple services only one of them can use the default name + and the others must be explicitly named. Names must adhere to [RFC-1123 §2.1](https://tools.ietf.org/html/rfc1123#section-2) and are limited to alphanumeric and hyphen characters (i.e. `[a-z0-9\-]`), and be less than 64 characters in length. @@ -338,16 +336,15 @@ The `Task` object supports the following keys: interpolation is supported in tags. * `PortLabel`: `PortLabel` is an optional string and is used to associate - the port with the service. If specified, the port label must match one - defined in the resources block. This could be a label to either a - dynamic or a static port. If an incorrect port label is specified, Nomad - doesn't register the IP:Port with Consul. + a port with the service. If specified, the port label must match one + defined in the resources block. This could be a label of either a + dynamic or a static port. * `Checks`: `Checks` is an array of check objects. A check object defines a health check associated with the service. Nomad supports the `script`, `http` and `tcp` Consul Checks. Script checks are not supported for the qemu driver since the Nomad client doesn't have access to the file system - of a tasks using the Qemu driver. + of a task using the Qemu driver. * `Type`: This indicates the check types supported by Nomad. Valid options are currently `script`, `http` and `tcp`. @@ -366,7 +363,7 @@ The `Task` object supports the following keys: to add the relative URL of the health check endpoint. * `Protocol`: This indicates the protocol for the http checks. Valid - options are `http` and `https`. We default it to `http` + options are `http` and `https`. We default it to `http`. * `Command`: This is the command that the Nomad client runs for doing script based health check. diff --git a/website/source/docs/jobspec/networking.html.md b/website/source/docs/jobspec/networking.html.md index 1f165fe6c..3d2dcf969 100644 --- a/website/source/docs/jobspec/networking.html.md +++ b/website/source/docs/jobspec/networking.html.md @@ -10,7 +10,7 @@ description: |- When scheduling jobs in Nomad they are provisioned across your fleet of machines along with other jobs and services. Because you don't know in advance -what host your job will be provisioned on, Nomad will provide your task with +what host your job will be provisioned on, Nomad will provide your tasks with network configuration when they start up. Note that this document only applies to services that want to _listen_ @@ -109,7 +109,7 @@ The above example is for the Docker driver. The service is listening on port to this service. When the task is started, it is passed an additional environment variable named -`NOMAD_HOST_PORT_http` which indicates the host port that the http service is +`NOMAD_HOST_PORT_http` which indicates the host port that the HTTP service is bound to. Please refer to the [Docker](/docs/drivers/docker.html) and [QEMU](/docs/drivers/qemu.html) drivers for additional information. diff --git a/website/source/docs/jobspec/schedulers.html.md b/website/source/docs/jobspec/schedulers.html.md index a7566c9b6..c57fd3cc1 100644 --- a/website/source/docs/jobspec/schedulers.html.md +++ b/website/source/docs/jobspec/schedulers.html.md @@ -16,7 +16,7 @@ the differences between each of these schedulers. The `service` scheduler is designed for scheduling long lived services that should never go down. As such, the `service` scheduler ranks a large portion -of the nodes that meet the jobs constraints and selects the optimal node to +of the nodes that meet the job's constraints and selects the optimal node to place a task group on. The `service` scheduler uses a best fit scoring algorithm influenced by Google work on Borg. Ranking this larger set of candidate nodes increases scheduling time but provides greater guarantees about the optimality @@ -28,7 +28,7 @@ Batch jobs are much less sensitive to short term performance fluctuations and are short lived, finishing in a few minutes to a few days. Although the `batch` scheduler is very similar to the `service` scheduler, it makes certain optimizations for the batch workload. The main distinction is that after finding -the set of nodes that meet the jobs constraints it uses the power of two choices +the set of nodes that meet the job's constraints it uses the power of two choices described in Berkeley's Sparrow scheduler to limit the number of nodes that are ranked. @@ -41,6 +41,6 @@ that all registered `system` jobs will be re-evaluated and their tasks will be placed on the newly available nodes if the constraints are met. This scheduler type is extremely useful for deploying and managing tasks that -should be present on every node in the cluster. Since these tasks are being +should be present on every node in the cluster. Since these tasks are managed by Nomad, they can take advantage of job updating, rolling deploys, service discovery and more. diff --git a/website/source/docs/jobspec/servicediscovery.html.md b/website/source/docs/jobspec/servicediscovery.html.md index acb0b84a5..be5219d68 100644 --- a/website/source/docs/jobspec/servicediscovery.html.md +++ b/website/source/docs/jobspec/servicediscovery.html.md @@ -25,14 +25,14 @@ To configure Consul integration please see the Agent's configuration ## Service Definition Syntax -The service block in a Task definition defines a service which Nomad will -register with Consul. Multiple service blocks are allowed in a Task definition, -which allow registering multiple services for a Task that exposes multiple +The service block in a task definition defines a service which Nomad will +register with Consul. Multiple service blocks are allowed in a task definition, +which allow registering multiple services for a task that exposes multiple ports. ### Example -A brief example of a service definition in a Task +A brief example of a service definition in a task ```hcl group "database" { @@ -73,15 +73,13 @@ group "database" { } ``` -* `name`: Nomad automatically determines the name of a Task. By default the - name of a service is `$(job-name)-$(task-group)-$(task-name)`. Users can - explicitly name the service by specifying this option. If multiple services - are defined for a Task then only one task can have the default name, all - the services have to be explicitly named. Users can add the following to - the service names: `${JOB}`, `${TASKGROUP}`, `${TASK}`, `${BASE}`. Nomad - will replace them with the appropriate value of the Job, Task Group, and - Task names while registering the Job. `${BASE}` expands to - `${JOB}-${TASKGROUP}-${TASK}`. Names must be adhere to +* `Name`: An explicit name for the Service. Nomad will replace `${JOB}`, + `${TASKGROUP}` and `${TASK}` by the name of the job, task group or task, + respectively. `${BASE}` expands to the equivalent of + `${JOB}-${TASKGROUP}-${TASK}`, and is the default name for a Service. + Each service defined for a given task must have a distinct name, so if + a task has multiple services only one of them can use the default name + and the others must be explicitly named. Names must adhere to [RFC-1123 §2.1](https://tools.ietf.org/html/rfc1123#section-2) and are limited to alphanumeric and hyphen characters (i.e. `[a-z0-9\-]`), and be less than 64 characters in length. @@ -89,16 +87,15 @@ group "database" { * `tags`: A list of tags associated with this Service. String interpolation is supported in tags. -* `port`: `port` is optional and is used to associate the port with the service. +* `port`: `port` is optional and is used to associate a port with the service. If specified, the port label must match one defined in the resources block. - This could be a label to either a dynamic or a static port. If an incorrect - port label is specified, Nomad doesn't register the IP:Port with Consul. + This could be a label of either a dynamic or a static port. * `check`: A check block defines a health check associated with the service. Multiple check blocks are allowed for a service. Nomad supports the `script`, `http` and `tcp` Consul Checks. Script checks are not supported for the qemu driver since the Nomad client doesn't have access to the file system of a - tasks using the Qemu driver. + task using the Qemu driver. ### Check Syntax @@ -119,7 +116,7 @@ group "database" { of the health check endpoint. * `protocol`: This indicates the protocol for the http checks. Valid options - are `http` and `https`. We default it to `http` + are `http` and `https`. We default it to `http`. * `command`: This is the command that the Nomad client runs for doing script based health check.