From f182e398e83056c6b3df5591f30806dac061d04f Mon Sep 17 00:00:00 2001 From: Armon Dadgar Date: Sun, 20 Sep 2015 15:31:33 -0700 Subject: [PATCH 01/17] website: skeleton drivers --- website/source/docs/drivers/custom.html.md | 15 +- website/source/docs/drivers/docker.html.md | 14 + .../source/docs/drivers/docker/index.html.md | 358 ------------------ website/source/docs/drivers/exec.html.md | 14 + website/source/docs/drivers/index.html.md | 79 +--- website/source/docs/drivers/java.html.md | 14 + website/source/docs/drivers/qemu.html.md | 14 + website/source/layouts/docs.erb | 10 +- 8 files changed, 81 insertions(+), 437 deletions(-) create mode 100644 website/source/docs/drivers/docker.html.md delete mode 100644 website/source/docs/drivers/docker/index.html.md create mode 100644 website/source/docs/drivers/exec.html.md create mode 100644 website/source/docs/drivers/java.html.md create mode 100644 website/source/docs/drivers/qemu.html.md diff --git a/website/source/docs/drivers/custom.html.md b/website/source/docs/drivers/custom.html.md index 53f30939e..7f2bde558 100644 --- a/website/source/docs/drivers/custom.html.md +++ b/website/source/docs/drivers/custom.html.md @@ -3,17 +3,14 @@ layout: "docs" page_title: "Drivers: Custom" sidebar_current: "docs-drivers-custom" description: |- - Create custom secret backends for Nomad. + Create custom task drivers for Nomad. --- # Custom Drivers -Nomad does not currently support the creation of custom secret backends. -The primary reason is because we want to ensure the core of Nomad is -secure before attempting any sort of plug-in system. We're interested -in supporting custom secret backends, but do not yet have a clear strategy -or timeline to do. +Nomad does not currently support pluggable task drivers, however the +interface that a task driver must implement is minimal. In the short term, +custom drivers can be implemented in Go and compiled into the binary, +however in the long term we plan to expose a plugin interface such that +task drivers can be dynamically registered without recompiling the Nomad binary. -In the mean time, you can use the -[generic backend](/docs/secrets/generic/index.html) to support custom -data with custom leases. diff --git a/website/source/docs/drivers/docker.html.md b/website/source/docs/drivers/docker.html.md new file mode 100644 index 000000000..d9bb939c1 --- /dev/null +++ b/website/source/docs/drivers/docker.html.md @@ -0,0 +1,14 @@ +--- +layout: "docs" +page_title: "Drivers: Docker" +sidebar_current: "docs-drivers-docker" +description: |- + The Docker task driver is used to run Docker based tasks. +--- + +# Docker Driver + +Name: `docker` + +TODO + diff --git a/website/source/docs/drivers/docker/index.html.md b/website/source/docs/drivers/docker/index.html.md deleted file mode 100644 index ee88d0a96..000000000 --- a/website/source/docs/drivers/docker/index.html.md +++ /dev/null @@ -1,358 +0,0 @@ ---- -layout: "docs" -page_title: "Drivers: Docker" -sidebar_current: "docs-drivers-docker" -description: |- - The AWS secret backend for Nomad generates access keys dynamically based on IAM policies. ---- - -# Docker Driver - -Name: `aws` - -The AWS secret backend for Nomad generates AWS access credentials dynamically -based on IAM policies. This makes IAM much easier to use: credentials could -be generated on the fly, and are automatically revoked when the Nomad -lease is expired. - -This page will show a quick start for this backend. For detailed documentation -on every path, use `vault path-help` after mounting the backend. - -## Quick Start - -The first step to using the aws backend is to mount it. -Unlike the `generic` backend, the `aws` backend is not mounted by default. - -```text -$ vault mount aws -Successfully mounted 'aws' at 'aws'! -``` - -Next, we must configure the root credentials that are used to manage IAM credentials: - -```text -$ vault write aws/config/root \ - access_key=AKIAJWVN5Z4FOFT7NLNA \ - secret_key=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 \ - region=us-east-1 -``` - -The following parameters are required: - -- `access_key` - the AWS access key that has permission to manage IAM - credentials. -- `secret_key` - the AWS secret key that has permission to manage IAM - credentials. -- `region` the AWS region for API calls. - -The next step is to configure a role. A role is a logical name that maps -to a policy used to generated those credentials. For example, lets create -a "deploy" role: - -```text -$ vault write aws/roles/deploy \ - name=deploy \ - policy=@policy.json -``` - -This path will create a named role along with the IAM policy used -to restrict permissions for it. This is used to dynamically create -a new pair of IAM credentials when needed. - -The `@` tells Nomad to load the policy from the file named `policy.json`. Here -is an example IAM policy to get started: - -```javascript -{ - "Version": "2012-10-17", - "Statement": { - "Effect": "Allow", - "Action": "iam:*", - "Resource": "*" - } -} -``` - -For more information on IAM policies, please see the -[AWS IAM policy documentation](http://docs.aws.amazon.com/IAM/latest/UserGuide/PoliciesOverview.html). - -To generate a new set of IAM credentials, we simply read from that role: - -```text -$ vault read aws/creds/deploy -Key Value -lease_id aws/creds/deploy/7cb8df71-782f-3de1-79dd-251778e49f58 -lease_duration 3600 -access_key AKIAIOMYUTSLGJOGLHTQ -secret_key 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 -``` - -If you run the command again, you will get a new set of credentials: - -```text -$ vault read aws/creds/deploy -Key Value -lease_id aws/creds/deploy/82d89562-ff19-382e-6be9-cb45c8f6a42d -lease_duration 3600 -access_key AKIAJZ5YRPHFH3QHRRRQ -secret_key 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 -``` - -If you get an error message similar to either of the following, the root credentials that you wrote to `aws/config/root` have insufficient privilege: - -```text -$ vault read aws/creds/deploy -* Error creating IAM user: User: arn:aws:iam::000000000000:user/hashicorp is not authorized to perform: iam:CreateUser on resource: arn:aws:iam::000000000000:user/vault-root-1432735386-4059 - -$ vault revoke aws/creds/deploy/774cfb27-c22d-6e78-0077-254879d1af3c -Revoke error: Error making API request. - -URL: PUT http://127.0.0.1:8200/v1/sys/revoke/aws/creds/deploy/774cfb27-c22d-6e78-0077-254879d1af3c -Code: 400. Errors: - -* invalid request -``` - -The root credentials need permission to perform various IAM actions. These are the actions that the AWS secret backend uses to manage IAM credentials. Here is an example IAM policy that would grant these permissions: - -```javascript -{ - "Version": "2012-10-17", - "Statement": [ - { - "Effect": "Allow", - "Action": [ - "iam:CreateAccessKey", - "iam:CreateUser", - "iam:PutUserPolicy", - "iam:ListGroupsForUser", - "iam:ListUserPolicies", - "iam:ListAccessKeys", - "iam:DeleteAccessKey", - "iam:DeleteUserPolicy", - "iam:RemoveUserFromGroup", - "iam:DeleteUser" - ], - "Resource": [ - "arn:aws:iam::ACCOUNT-ID-WITHOUT-HYPHENS:user/vault-*" - ] - } - ] -} -``` - -Note that this policy example is unrelated to the policy you wrote to `aws/roles/deploy`. This policy example should be applied to the IAM user (or role) associated with the root credentials that you wrote to `aws/config/root`. You have to apply it yourself in IAM. The policy you wrote to `aws/roles/deploy` is the policy you want the AWS secret backend to apply to the temporary credentials it returns from `aws/creds/deploy`. - -If you get stuck at any time, simply run `vault path-help aws` or with a subpath for -interactive help output. - -## API - -### /aws/config/root -#### POST - -
-
Description
-
- Configures the root IAM credentials used. - This is a root protected endpoint. -
- -
Method
-
POST
- -
URL
-
`/aws/config/root`
- -
Parameters
-
-
    -
  • - access_key - required - The AWS Access Key -
    • -
  • - secret_key - required - The AWS Secret Key -
    • -
  • - region - required - The AWS region for API calls -
    • -
-
- -
Returns
-
- A `204` response code. -
-
- -### /aws/config/lease -#### POST - -
-
Description
-
- Configures the lease settings for generated credentials. - This is a root protected endpoint. -
- -
Method
-
POST
- -
URL
-
`/aws/config/lease`
- -
Parameters
-
-
    -
  • - lease - required - The lease value provided as a string duration - with time suffix. Hour is the largest suffix. -
    • -
  • - lease_max - required - The maximum lease value provided as a string duration - with time suffix. Hour is the largest suffix. -
    • -
-
- -
Returns
-
- A `204` response code. -
-
- -### /aws/roles/ -#### POST - -
-
Description
-
- Creates or updates a named role. -
- -
Method
-
POST
- -
URL
-
`/aws/roles/`
- -
Parameters
-
-
    -
  • - policy - required - The IAM policy in JSON format. -
    • -
-
- -
Returns
-
- A `204` response code. -
-
- -#### GET - -
-
Description
-
- Queries a named role. -
- -
Method
-
GET
- -
URL
-
`/aws/roles/`
- -
Parameters
-
- None -
- -
Returns
-
- - ```javascript - { - "data": { - "policy": "..." - } - } - ``` - -
-
- -#### DELETE - -
-
Description
-
- Deletes a named role. -
- -
Method
-
DELETE
- -
URL
-
`/aws/roles/`
- -
Parameters
-
- None -
- -
Returns
-
- A `204` response code. -
-
- - -### /aws/creds/ -#### GET - -
-
Description
-
- Generates a dynamic IAM credential based on the named role. -
- -
Method
-
GET
- -
URL
-
`/aws/creds/`
- -
Parameters
-
- None -
- -
Returns
-
- - ```javascript - { - "data": { - "access_key": "...", - "secret_key": "..." - } - } - ``` - -
-
diff --git a/website/source/docs/drivers/exec.html.md b/website/source/docs/drivers/exec.html.md new file mode 100644 index 000000000..03286208e --- /dev/null +++ b/website/source/docs/drivers/exec.html.md @@ -0,0 +1,14 @@ +--- +layout: "docs" +page_title: "Drivers: Exec" +sidebar_current: "docs-drivers-exec" +description: |- + The Exec task driver is used to run binaries using OS isolation primitives. +--- + +# Fork/Exec Driver + +Name: `exec` + +TODO + diff --git a/website/source/docs/drivers/index.html.md b/website/source/docs/drivers/index.html.md index 4175c7e8e..e5a950392 100644 --- a/website/source/docs/drivers/index.html.md +++ b/website/source/docs/drivers/index.html.md @@ -1,75 +1,24 @@ --- layout: "docs" -page_title: "Drivers" +page_title: "Task Drivers" sidebar_current: "docs-drivers" description: |- - Secret backends are mountable backends that store or generate secrets in Nomad. + Task Drivers are used to integrate with the host OS to run tasks in Nomad. --- -# Drivers +# Task Drivers -Secret backends are the components in Nomad which store and generate -secrets. +Task drivers are used by Nomad clients to execute a task and provide resource +isolation. By having extensible task drivers, Nomad has the flexibility to +support a broad set of workloads across all major operating systems. -Some secret backends, such as "generic", simply store and read -secrets verbatim. Other secret backends, such as "aws", create _dynamic -secrets_: secrets that are made on demand. +The list of supported task is on the left. Each task driver documents the +configuration available in a job specification, the environments it can be +used in, and the resource isolation mechanisms available. -Secret backends are part of the -[mount system](#) -in Nomad. They behave very similarly to a virtual filesystem: -any read/write/delete is sent to the secret backend, and the secret -backend can choose to react to that operation however it sees fit. +Nomad strives to mask the details of running a task from users and instead +provides a clean abstraction. It is possible for the same task to be executed +with different isolation levels depending on the client running the task. +The goal is to use the strictest isolation available and gracefully degrade +protections where necessary. -For example, the "generic" backend passes through any operation back -to the configured storage backend for Nomad. A "read" turns into a -"read" of the storage backend at the same path, a "write" turns into -a write, etc. This is a lot like a normal filesystem. - -The "aws" backend, on the other hand, behaves differently. When you -write to `aws/config/root`, it expects a certain format and stores that -information as configuration. You cannot read from this path. When you -read from `aws/`, it looks up an IAM policy named `` and -generates AWS access credentials on demand and returns them. It does not -behave at all like a typical filesystem: you are not simply storing and -retrieving values, you are interacting with an API. - -## Mounting/Unmounting Secret Backends - -Secret backends can be mounted/unmounted using the CLI or the API. -There are three operations that can be performed with a secret backend -with regards to mounting: - - * **Mount** - This mounts a new secret backend. Multiple secret - backends of the same type can be mounted at the same time by - specifying different mount points. By default, secret backends are - mounted to the same path as their name. This is what you want most - of the time. - - * **Unmount** - This unmounts an existing secret backend. When a secret - backend is unmounted, all of its secrets are revoked (if they support - it), and all of the data stored for that backend in the physical storage - layer is deleted. - - * **Remount** - This moves the mount point for an existing secret backend. - This revokes all secrets, since secret leases are tied to the path they - were created at. The data stored for the backend will not be deleted. - -Once a secret backend is mounted, you can interact with it directly -at its mount point according to its own API. You can use the `vault path-help` -system to determine the paths it responds to. - -## Barrier View - -An important concept around secret backends is that they receive a -_barrier view_ to the configured Nomad physical storage. This is a lot -like a [chroot](http://en.wikipedia.org/wiki/Chroot). - -Whenever a secret backend is mounted, a random UUID is generated. This -becomes the data root for that backend. Whenever that backend writes to -the physical storage layer, it is prefixed with that UUID folder. Since -the Nomad storage layer does not support relative access (such as `..`), -this makes it impossible for a mounted backend to access any other data. - -This is an important security feature in Nomad: even a malicious backend -cannot access the data from any other backend. diff --git a/website/source/docs/drivers/java.html.md b/website/source/docs/drivers/java.html.md new file mode 100644 index 000000000..130fc999b --- /dev/null +++ b/website/source/docs/drivers/java.html.md @@ -0,0 +1,14 @@ +--- +layout: "docs" +page_title: "Drivers: Java" +sidebar_current: "docs-drivers-java" +description: |- + The Java task driver is used to run Jars using the JVM. +--- + +# Java Driver + +Name: `java` + +TODO + diff --git a/website/source/docs/drivers/qemu.html.md b/website/source/docs/drivers/qemu.html.md new file mode 100644 index 000000000..f617179f5 --- /dev/null +++ b/website/source/docs/drivers/qemu.html.md @@ -0,0 +1,14 @@ +--- +layout: "docs" +page_title: "Drivers: Qemu" +sidebar_current: "docs-drivers-qemu" +description: |- + The Qemu task driver is used to run virtual machines using Qemu/KVM. +--- + +# Qemu Driver + +Name: `qemu` + +TODO + diff --git a/website/source/layouts/docs.erb b/website/source/layouts/docs.erb index a0af2ed94..6a0ec604e 100644 --- a/website/source/layouts/docs.erb +++ b/website/source/layouts/docs.erb @@ -94,22 +94,22 @@
> - Drivers + Task Drivers
    > - Docker + Docker > - Fork/Exec + Fork/Exec > - Java + Java > - Qemu + Qemu > From c8dcdd3c8a7b7a6ce77ef0ac3f36f1d28994ebfe Mon Sep 17 00:00:00 2001 From: Armon Dadgar Date: Sun, 20 Sep 2015 15:42:33 -0700 Subject: [PATCH 02/17] website: document exec driver --- website/source/docs/drivers/exec.html.md | 38 +++++++++++++++++++++++- 1 file changed, 37 insertions(+), 1 deletion(-) diff --git a/website/source/docs/drivers/exec.html.md b/website/source/docs/drivers/exec.html.md index 03286208e..2a4d4e5c4 100644 --- a/website/source/docs/drivers/exec.html.md +++ b/website/source/docs/drivers/exec.html.md @@ -10,5 +10,41 @@ description: |- Name: `exec` -TODO +The `exec` driver is used to simply execute a particular command for a task. +This is the simplest driver and is extremely flexible. In particlar, because +it can invoke any command, it can be used to call scripts or other wrappers +which provide higher level features. + +## Task Configuration + +The `exec` driver supports the following configuration in the job spec: + +* `command` - The command to execute. Must be provided. + +* `args` - The argument list to the command, space seperated. Optional. + +## Client Requirements + +The `exec` driver has no special requirements and can run on all +supported operating systems. The resource isolation primitives vary +by OS. + +## Client Attributes + +The `exec` driver will set the following client attributes: + +* `driver.exec` - This will always be set to "1", indicating the + driver is available. + +## Resource Isolation + +The resource isolation provided varies by the operating system of +the client and the configuration. + +On Linux, Nomad will attempt to use cgroups, namespaces, and chroot +to isolate the resources of a process. If the Nomad agent is not +running as root many of these mechanisms cannot be used. + +As a baseline, the task driver will just execute the command +with no additional resource isolation if none are available. From aa3a95bdc61dde9f22ec94fdc1962a56823414c3 Mon Sep 17 00:00:00 2001 From: Armon Dadgar Date: Sun, 20 Sep 2015 15:51:49 -0700 Subject: [PATCH 03/17] website: improve cross linking --- website/source/docs/drivers/index.html.md | 4 ++-- website/source/docs/jobspec/index.html.md | 10 +++++++--- 2 files changed, 9 insertions(+), 5 deletions(-) diff --git a/website/source/docs/drivers/index.html.md b/website/source/docs/drivers/index.html.md index e5a950392..88937e949 100644 --- a/website/source/docs/drivers/index.html.md +++ b/website/source/docs/drivers/index.html.md @@ -13,8 +13,8 @@ isolation. By having extensible task drivers, Nomad has the flexibility to support a broad set of workloads across all major operating systems. The list of supported task is on the left. Each task driver documents the -configuration available in a job specification, the environments it can be -used in, and the resource isolation mechanisms available. +configuration available in a [job specification](/docs/jobspec/index.html), +the environments it can be used in, and the resource isolation mechanisms available. Nomad strives to mask the details of running a task from users and instead provides a clean abstraction. It is possible for the same task to be executed diff --git a/website/source/docs/jobspec/index.html.md b/website/source/docs/jobspec/index.html.md index 6d6e7ecca..337c98e63 100644 --- a/website/source/docs/jobspec/index.html.md +++ b/website/source/docs/jobspec/index.html.md @@ -150,9 +150,9 @@ The `group` object supports the following keys: The `task` object supports the following keys: -* `driver` - Specifies the driver that should be used to run the - task. See the driver documentation for what is available. Examples - include "docker", "qemu", "java", and "exec". +* `driver` - Specifies the task driver that should be used to run the + task. See the [driver documentation](/docs/drivers/index.html) for what + is available. Examples include "docker", "qemu", "java", and "exec". * `constraint` - This can be provided multiple times to define additional constraints. See the constraint reference for more details. @@ -256,6 +256,10 @@ Below is a table documenting common node attributes: cpu.numcores Number of CPU cores on the client + + driver.\ + See the [task drivers](/docs/drivers/index.html) for attribute documentation + hostname Hostname of the client From 67ea126dc253aa496ed19897252f66fc0d129226 Mon Sep 17 00:00:00 2001 From: Armon Dadgar Date: Sun, 20 Sep 2015 16:12:43 -0700 Subject: [PATCH 04/17] website: docs layout --- website/source/layouts/docs.erb | 61 +++++++++++++++++---------------- 1 file changed, 31 insertions(+), 30 deletions(-) diff --git a/website/source/layouts/docs.erb b/website/source/layouts/docs.erb index 6a0ec604e..3497d16db 100644 --- a/website/source/layouts/docs.erb +++ b/website/source/layouts/docs.erb @@ -33,11 +33,40 @@ > Installation - + + +
    > Job Specification - + + + > + Task Drivers + + + +
    > Commands (CLI) @@ -90,34 +119,6 @@ > HTTP API - -
    - - > - Task Drivers - - -
<% end %> From e8fabad2679529b561c885eade74f874f13f7a76 Mon Sep 17 00:00:00 2001 From: Armon Dadgar Date: Sun, 20 Sep 2015 16:12:52 -0700 Subject: [PATCH 05/17] website: initial http layout --- website/source/docs/http/index.html.md | 30 ++++++++++-- website/source/layouts/http.erb | 63 +++++++++++++++++++++++++- 2 files changed, 87 insertions(+), 6 deletions(-) diff --git a/website/source/docs/http/index.html.md b/website/source/docs/http/index.html.md index 16145bce1..422a015cc 100644 --- a/website/source/docs/http/index.html.md +++ b/website/source/docs/http/index.html.md @@ -3,13 +3,33 @@ layout: "http" page_title: "HTTP API" sidebar_current: "docs-http-overview" description: |- - Nomad has an HTTP API that can be used to control every aspect of Nomad. + Nomad has an HTTP API that can be used to programmatically use Nomad. --- # HTTP API -The Nomad HTTP API gives you full access to Nomad via HTTP. Every -aspect of Nomad can be controlled via this API. The Nomad CLI uses -the HTTP API to access Nomad. +The Nomad HTTP API is the primary interface to using Nomad, and is used +to query the current state of the system as well as to modify it. +The Nomad CLI makes use of the Go HTTP client and invokes the HTTP API. + +All API routes are prefixed with `/v1/`. This documentation is only for the v1 API. + +## Data Model + +There are four primary "nouns" in Nomad, these are jobs, nodes, allocations, and evaluations: + +[![Nomad Data Model](/assets/images/nomad-data-model.png)](/assets/images/nomad-data-model.png) + +Jobs are submitted by users and represent a _desired state_. A job is a declarative description +of tasks to run which are bounded by constraints and require resources. Nodes are the servers +in the clusters that tasks can be scheduled on. The mapping of tasks in a job to nodes is done +using allocations. An allocation is used to declare that a set of tasks in a job should be run +on a particular node. Scheduling is the process of determining the appropriate allocations and +is done as part of an evaluation. + +The API is modeled closely on the underlying data model. Use the links to the left for +documentation about specific endpoints. + +There are a set of "Agent" APIs which are used to interact with a specific agent and not the +broader cluster. -TODO: Document Nomand API diff --git a/website/source/layouts/http.erb b/website/source/layouts/http.erb index 038bc1f3b..8e8881306 100644 --- a/website/source/layouts/http.erb +++ b/website/source/layouts/http.erb @@ -10,7 +10,68 @@ > Overview - + + + > + Jobs + + + + > + Nodes + + + + > + Allocations + + + + > + Evaluations + + + + > + Agent + + <% end %> From 14241ab3e55740203dabf0c6a20ac8dd572c5513 Mon Sep 17 00:00:00 2001 From: Armon Dadgar Date: Sun, 20 Sep 2015 16:52:08 -0700 Subject: [PATCH 06/17] website: HTTP docs --- website/source/docs/http/index.html.md | 68 ++++++++++++++++++-- website/source/docs/http/jobs.html.md | 88 ++++++++++++++++++++++++++ website/source/layouts/http.erb | 4 +- 3 files changed, 154 insertions(+), 6 deletions(-) create mode 100644 website/source/docs/http/jobs.html.md diff --git a/website/source/docs/http/index.html.md b/website/source/docs/http/index.html.md index 422a015cc..671d19fa5 100644 --- a/website/source/docs/http/index.html.md +++ b/website/source/docs/http/index.html.md @@ -14,7 +14,7 @@ The Nomad CLI makes use of the Go HTTP client and invokes the HTTP API. All API routes are prefixed with `/v1/`. This documentation is only for the v1 API. -## Data Model +## Data Model and API Layout There are four primary "nouns" in Nomad, these are jobs, nodes, allocations, and evaluations: @@ -28,8 +28,68 @@ on a particular node. Scheduling is the process of determining the appropriate a is done as part of an evaluation. The API is modeled closely on the underlying data model. Use the links to the left for -documentation about specific endpoints. +documentation about specific endpoints. There are also "Agent" APIs which interact with +a specific agent and not the broader cluster used for administration. + +## Blocking Queries + +Certain endpoints support a feature called a "blocking query." A blocking query +is used to wait for a potential change using long polling. + +Not all endpoints support blocking, but those that do are clearly designated in the +documentation. Any endpoint that supports blocking will also set the HTTP header +`X-Nomad-Index`, a unique identifier representing the current state of the +requested resource. On subsequent requests for this resource, the client can set the `index` +query string parameter to the value of `X-Nomad-Index`, indicating that the client wishes +to wait for any changes subsequent to that index. + +In addition to `index`, endpoints that support blocking will also honor a `wait` +parameter specifying a maximum duration for the blocking request. This is limited to +10 minutes. If not set, the wait time defaults to 5 minutes. This value can be specified +in the form of "10s" or "5m" (i.e., 10 seconds or 5 minutes, respectively). + +A critical note is that the return of a blocking request is **no guarantee** of a change. It +is possible that the timeout was reached or that there was an idempotent write that does +not affect the result of the query. + +## Consistency Modes + +Most of the read query endpoints support multiple levels of consistency. Since no policy will +suit all clients' needs, these consistency modes allow the user to have the ultimate say in +how to balance the trade-offs inherent in a distributed system. + +The two read modes are: + +* default - If not specified, the default is strongly consistent in almost all cases. However, + there is a small window in which a new leader may be elected during which the old leader may + service stale values. The trade-off is fast reads but potentially stale values. The condition + resulting in stale reads is hard to trigger, and most clients should not need to worry about + this case. Also, note that this race condition only applies to reads, not writes. + +* stale - This mode allows any server to service the read regardless of whether + it is the leader. This means reads can be arbitrarily stale; however, results are generally + consistent to within 50 milliseconds of the leader. The trade-off is very fast and + scalable reads with a higher likelihood of stale values. Since this mode allows reads without + a leader, a cluster that is unavailable will still be able to respond to queries. + +To switch these modes, use the `stale` query parameter on request. + +To support bounding the acceptable staleness of data, responses provide the `X-Nomad-LastContact` +header containing the time in milliseconds that a server was last contacted by the leader node. +The `X-Nomad-KnownLeader` header also indicates if there is a known leader. These can be used +by clients to gauge the staleness of a result and take appropriate action. + +## Cross-Region Requests + +By default any request to the HTTP API is assumed to pertain to the region of the machine +servicing the request. A target region can be explicitly specified with the `region` query +parameter. The request will be transparently forwarded and serviced by a server in the +appropriate region. + +## Formatted JSON Output + +By default, the output of all HTTP API requests is minimized JSON. If the client passes `pretty` +on the query string, formatted JSON will be returned. + -There are a set of "Agent" APIs which are used to interact with a specific agent and not the -broader cluster. diff --git a/website/source/docs/http/jobs.html.md b/website/source/docs/http/jobs.html.md new file mode 100644 index 000000000..f9a78a089 --- /dev/null +++ b/website/source/docs/http/jobs.html.md @@ -0,0 +1,88 @@ +--- +layout: "http" +page_title: "HTTP API: /v1/jobs" +sidebar_current: "docs-http-jobs" +description: |- + The '/1/jobs' endpoint is used list jobs and register new ones. +--- + +# /v1/jobs + +The `jobs` endpoint is used to query the status of existing jobs in Nomad +and to to register new jobs. By default, the agent's local region is used; +another region can be specified using the `?region=` query parameter. + +## GET + +
+
Description
+
+ Lists all the jobs registered with Nomad. +
+ +
Method
+
GET
+ +
URL
+
`/v1/jobs`
+ +
Parameters
+
+ None +
+ +
Returns
+
+ + ```javascript + { + "aws": { + "type": "aws", + "description": "AWS keys" + }, + + "sys": { + "type": "system", + "description": "system endpoint" + } + } + ``` + +
+
+ +## PUT / POST + +
+
Description
+
+ Registers a new job +
+ +
Method
+
PUT or POST
+ +
URL
+
`/v1/jobs`
+ +
Parameters
+
+
    +
  • + type + required + The name of the backend type, such as "aws" +
    • +
  • + description + optional + A human-friendly description of the mount. +
    • +
+
+ +
Returns
+
`204` response code. +
+
+ diff --git a/website/source/layouts/http.erb b/website/source/layouts/http.erb index 8e8881306..a2d7dae31 100644 --- a/website/source/layouts/http.erb +++ b/website/source/layouts/http.erb @@ -15,8 +15,8 @@ > Jobs
    - > - /v1/jobs + > + /v1/jobs > From d4982d16d70db2191493da95d857085337abd353 Mon Sep 17 00:00:00 2001 From: Armon Dadgar Date: Sun, 20 Sep 2015 17:02:12 -0700 Subject: [PATCH 07/17] client: optimize initial heartbeat time --- client/client.go | 16 ++++++++++++++-- 1 file changed, 14 insertions(+), 2 deletions(-) diff --git a/client/client.go b/client/client.go index 2f2b221c1..da6ad20bf 100644 --- a/client/client.go +++ b/client/client.go @@ -46,6 +46,11 @@ const ( // register errors after start. This is to improve the user experience // in dev mode where the leader isn't elected for a few seconds. registerErrGrace = 10 * time.Second + + // initialHeartbeatStagger is used to stagger the interval between + // starting and the intial heartbeat. After the intial heartbeat, + // we switch to using the TTL specified by the servers. + initialHeartbeatStagger = 10 * time.Second ) // DefaultConfig returns the default configuration @@ -399,8 +404,15 @@ func (c *Client) run() { } } - // Setup the heartbeat timer - heartbeat := time.After(c.heartbeatTTL) + // Setup the heartbeat timer, for the initial registration + // we want to do this quickly. We want to do it extra quickly + // in development mode. + var heartbeat <-chan time.Time + if c.config.DevMode { + heartbeat = time.After(0) + } else { + heartbeat = time.After(randomStagger(initialHeartbeatStagger)) + } // Watch for changes in allocations allocUpdates := make(chan []*structs.Allocation, 1) From 798c8791fd2918306801b639fadf44058ce70aa4 Mon Sep 17 00:00:00 2001 From: Armon Dadgar Date: Sun, 20 Sep 2015 17:08:57 -0700 Subject: [PATCH 08/17] nomad: remove errwrap, directly wrap --- nomad/structs/structs.go | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/nomad/structs/structs.go b/nomad/structs/structs.go index e937555b2..5df59950a 100644 --- a/nomad/structs/structs.go +++ b/nomad/structs/structs.go @@ -7,7 +7,6 @@ import ( "strings" "time" - "github.com/hashicorp/errwrap" "github.com/hashicorp/go-msgpack/codec" "github.com/hashicorp/go-multierror" ) @@ -780,8 +779,8 @@ func (j *Job) Validate() error { // Validate the task group for idx, tg := range j.TaskGroups { if err := tg.Validate(); err != nil { - outer := fmt.Errorf("Task group %d validation failed", idx+1) - mErr.Errors = append(mErr.Errors, errwrap.Wrap(outer, err)) + outer := fmt.Errorf("Task group %d validation failed: %s", idx+1, err) + mErr.Errors = append(mErr.Errors, outer) } } return mErr.ErrorOrNil() @@ -889,8 +888,8 @@ func (tg *TaskGroup) Validate() error { // Validate the tasks for idx, task := range tg.Tasks { if err := task.Validate(); err != nil { - outer := fmt.Errorf("Task %d validation failed", idx+1) - mErr.Errors = append(mErr.Errors, errwrap.Wrap(outer, err)) + outer := fmt.Errorf("Task %d validation failed: %s", idx+1, err) + mErr.Errors = append(mErr.Errors, outer) } } return mErr.ErrorOrNil() From 2c3febc8afc599fc6130ee117f1d04b85acac778 Mon Sep 17 00:00:00 2001 From: Armon Dadgar Date: Sun, 20 Sep 2015 17:38:26 -0700 Subject: [PATCH 09/17] http: validating job is provided to avoid nil pointer --- command/agent/job_endpoint.go | 3 +++ 1 file changed, 3 insertions(+) diff --git a/command/agent/job_endpoint.go b/command/agent/job_endpoint.go index 4812ee08f..ceaa8096f 100644 --- a/command/agent/job_endpoint.go +++ b/command/agent/job_endpoint.go @@ -160,6 +160,9 @@ func (s *HTTPServer) jobUpdate(resp http.ResponseWriter, req *http.Request, if err := decodeBody(req, &args, nil); err != nil { return nil, CodedError(400, err.Error()) } + if args.Job == nil { + return nil, CodedError(400, "Job must be specified") + } if jobName != "" && args.Job.ID != jobName { return nil, CodedError(400, "Job ID does not match") } From f39c20868b14133faf13992661d725e60f3ac965 Mon Sep 17 00:00:00 2001 From: Armon Dadgar Date: Sun, 20 Sep 2015 17:38:37 -0700 Subject: [PATCH 10/17] website: API docs for Jobs --- website/source/docs/http/job.html.md | 348 ++++++++++++++++++++++++++ website/source/docs/http/jobs.html.md | 46 ++-- website/source/layouts/http.erb | 12 +- 3 files changed, 381 insertions(+), 25 deletions(-) create mode 100644 website/source/docs/http/job.html.md diff --git a/website/source/docs/http/job.html.md b/website/source/docs/http/job.html.md new file mode 100644 index 000000000..2d79cb264 --- /dev/null +++ b/website/source/docs/http/job.html.md @@ -0,0 +1,348 @@ +--- +layout: "http" +page_title: "HTTP API: /v1/job" +sidebar_current: "docs-http-job-" +description: |- + The '/1/job' endpoint is used for CRUD on a single job. +--- + +# /v1/job/\ + +The `job` endpoint is used for CRUD on a singel job. By default, the agent's local +region is used; another region can be specified using the `?region=` query parameter. + +## GET + +
    +
    Description
    +
    + Query a single job for its specification and status. +
    + +
    Method
    +
    GET
    + +
    URL
    +
    `/v1/job/`
    + +
    Parameters
    +
    + None +
    + +
    Returns
    +
    + + ```javascript + { + "Region": "global", + "ID": "binstore-storagelocker", + "Name": "binstore-storagelocker", + "Type": "service", + "Priority": 50, + "AllAtOnce": false, + "Datacenters": [ + "us2", + "eu1" + ], + "Constraints": [ + { + "Hard": true, + "LTarget": "kernel.os", + "RTarget": "windows", + "Operand": "=", + "Weight": 0 + } + ], + "TaskGroups": [ + { + "Name": "binsl", + "Count": 5, + "Constraints": [ + { + "Hard": true, + "LTarget": "kernel.os", + "RTarget": "linux", + "Operand": "=", + "Weight": 0 + } + ], + "Tasks": [ + { + "Name": "binstore", + "Driver": "docker", + "Config": { + "image": "hashicorp/binstore" + }, + "Constraints": null, + "Resources": { + "CPU": 500, + "MemoryMB": 0, + "DiskMB": 0, + "IOPS": 0, + "Networks": [ + { + "Device": "", + "CIDR": "", + "IP": "", + "MBits": 100, + "ReservedPorts": null, + "DynamicPorts": 0 + } + ] + }, + "Meta": null + }, + { + "Name": "storagelocker", + "Driver": "java", + "Config": { + "image": "hashicorp/storagelocker" + }, + "Constraints": [ + { + "Hard": true, + "LTarget": "kernel.arch", + "RTarget": "amd64", + "Operand": "=", + "Weight": 0 + } + ], + "Resources": { + "CPU": 500, + "MemoryMB": 0, + "DiskMB": 0, + "IOPS": 0, + "Networks": null + }, + "Meta": null + } + ], + "Meta": { + "elb_checks": "3", + "elb_interval": "10", + "elb_mode": "tcp" + } + } + ], + "Update": { + "Stagger": 0, + "MaxParallel": 0 + }, + "Meta": { + "foo": "bar" + }, + "Status": "", + "StatusDescription": "", + "CreateIndex": 14, + "ModifyIndex": 14 + } + ``` + +
    +
    + +## PUT / POST + +
    +
    Description
    +
    + Registers a new job or updates an existing job +
    + +
    Method
    +
    PUT or POST
    + +
    URL
    +
    `/v1/job/`
    + +
    Parameters
    +
    +
      +
    • + Job + required + The JSON definition of the job. The general structure is given + by the [job specification](/docs/jobspec/index.html), and matches + the return response of GET. +
      • +
    +
    + +
    Returns
    +
    + + ```javascript + { + "EvalID": "d092fdc0-e1fd-2536-67d8-43af8ca798ac", + "EvalCreateIndex": 35, + "JobModifyIndex": 34, + } + ``` + +
    +
    + +## DELETE + +
    +
    Description
    +
    + Deregisters a job, and stops all allocations part of it. +
    + +
    Method
    +
    DELETE
    + +
    URL
    +
    `/v1/job/`
    + +
    Parameters
    +
    + None +
    + +
    Returns
    +
    + + ```javascript + { + "EvalID": "d092fdc0-e1fd-2536-67d8-43af8ca798ac", + "EvalCreateIndex": 35, + "JobModifyIndex": 34, + } + ``` + +
    +
    + +# /v1/job/\/evaluate +## PUT / POST + +
    +
    Description
    +
    + Creates a new evaluation for the given job. This can be used to force + run the scheduling logic if necessary. +
    + +
    Method
    +
    PUT or POST
    + +
    URL
    +
    `/v1/job//evaluate`
    + +
    Parameters
    +
    + None +
    + +
    Returns
    +
    + + ```javascript + { + "EvalID": "d092fdc0-e1fd-2536-67d8-43af8ca798ac", + "EvalCreateIndex": 35, + "JobModifyIndex": 34, + } + ``` + +
    +
    + +# /v1/job/\/allocations +## GET + +
    +
    Description
    +
    + Query the allocations belonging to a single job. +
    + +
    Method
    +
    GET
    + +
    URL
    +
    `/v1/job//allocations`
    + +
    Parameters
    +
    + None +
    + +
    Returns
    +
    + + ```javascript + [ + { + "ID": "3575ba9d-7a12-0c96-7b28-add168c67984", + "EvalID": "151accaa-1ac6-90fe-d427-313e70ccbb88", + "Name": "binstore-storagelocker.binsl[0]", + "NodeID": "a703c3ca-5ff8-11e5-9213-970ee8879d1b", + "JobID": "binstore-storagelocker", + "TaskGroup": "binsl", + "DesiredStatus": "run", + "DesiredDescription": "", + "ClientStatus": "running", + "ClientDescription": "", + "CreateIndex": 16, + "ModifyIndex": 16 + }, + ... + ] + ``` + +
    +
    + +# /v1/job/\/evaluations +## GET + +
    +
    Description
    +
    + Query the evaluations belonging to a single job. +
    + +
    Method
    +
    GET
    + +
    URL
    +
    `/v1/job//evaluations`
    + +
    Parameters
    +
    + None +
    + +
    Returns
    +
    + + ```javascript + [ + { + "ID": "151accaa-1ac6-90fe-d427-313e70ccbb88", + "Priority": 50, + "Type": "service", + "TriggeredBy": "job-register", + "JobID": "binstore-storagelocker", + "JobModifyIndex": 14, + "NodeID": "", + "NodeModifyIndex": 0, + "Status": "complete", + "StatusDescription": "", + "Wait": 0, + "NextEval": "", + "PreviousEval": "", + "CreateIndex": 15, + "ModifyIndex": 17 + }, + ... + ] + ``` + +
    +
    + diff --git a/website/source/docs/http/jobs.html.md b/website/source/docs/http/jobs.html.md index f9a78a089..f724ce0ac 100644 --- a/website/source/docs/http/jobs.html.md +++ b/website/source/docs/http/jobs.html.md @@ -35,17 +35,19 @@ another region can be specified using the `?region=` query parameter.
    ```javascript + [ { - "aws": { - "type": "aws", - "description": "AWS keys" - }, - - "sys": { - "type": "system", - "description": "system endpoint" - } - } + "ID": "binstore-storagelocker", + "Name": "binstore-storagelocker", + "Type": "service", + "Priority": 50, + "Status": "", + "StatusDescription": "", + "CreateIndex": 14, + "ModifyIndex": 14 + }, + ... + ] ```
    @@ -56,7 +58,7 @@ another region can be specified using the `?region=` query parameter.
    Description
    - Registers a new job + Registers a new job.
    Method
    @@ -69,20 +71,26 @@ another region can be specified using the `?region=` query parameter.
    • - type + Job required - The name of the backend type, such as "aws" -
      • -
    • - description - optional - A human-friendly description of the mount. + The JSON definition of the job. The general structure is given + by the [job specification](/docs/jobspec/index.html), and matches + the return response of [GET against `/v1/job/`](/docs/http/job.html).
    Returns
    -
    `204` response code. +
    + + ```javascript + { + "EvalID": "d092fdc0-e1fd-2536-67d8-43af8ca798ac", + "EvalCreateIndex": 35, + "JobModifyIndex": 34, + } + ``` +
    diff --git a/website/source/layouts/http.erb b/website/source/layouts/http.erb index a2d7dae31..e2de19061 100644 --- a/website/source/layouts/http.erb +++ b/website/source/layouts/http.erb @@ -19,13 +19,13 @@ /v1/jobs - > - /v1/job + > + /v1/job
- > + > Nodes
    > @@ -38,7 +38,7 @@
- > + > Allocations
    > @@ -51,7 +51,7 @@
- > + > Evaluations
    > @@ -64,7 +64,7 @@
- > + > Agent
    > From 67ea9a6e3f9257d9296410c489de5bce14f773e4 Mon Sep 17 00:00:00 2001 From: Armon Dadgar Date: Sun, 20 Sep 2015 17:53:43 -0700 Subject: [PATCH 11/17] website: Node API docs --- website/source/docs/http/node.html.md | 208 +++++++++++++++++++++++++ website/source/docs/http/nodes.html.md | 57 +++++++ website/source/layouts/http.erb | 8 +- 3 files changed, 269 insertions(+), 4 deletions(-) create mode 100644 website/source/docs/http/node.html.md create mode 100644 website/source/docs/http/nodes.html.md diff --git a/website/source/docs/http/node.html.md b/website/source/docs/http/node.html.md new file mode 100644 index 000000000..42d8e4075 --- /dev/null +++ b/website/source/docs/http/node.html.md @@ -0,0 +1,208 @@ +--- +layout: "http" +page_title: "HTTP API: /v1/node" +sidebar_current: "docs-http-node-" +description: |- + The '/1/node-' endpoint is used to query a specific client node. +--- + +# /v1/node + +The `node` endpoint is used to query the a specific client node. +By default, the agent's local region is used; another region can +be specified using the `?region=` query parameter. + +## GET + +
    +
    Description
    +
    + Query the status of a client node registered with Nomad. +
    + +
    Method
    +
    GET
    + +
    URL
    +
    `/v1/node/`
    + +
    Parameters
    +
    + None +
    + +
    Returns
    +
    + + ```javascript + { + "ID": "c9972143-861d-46e6-df73-1d8287bc3e66", + "Datacenter": "dc1", + "Name": "Armons-MacBook-Air.local", + "Attributes": { + "arch": "amd64", + "cpu.frequency": "1300.000000", + "cpu.modelname": "Intel(R) Core(TM) i5-4250U CPU @ 1.30GHz", + "cpu.numcores": "2", + "cpu.totalcompute": "2600.000000", + "driver.exec": "1", + "driver.java": "1", + "driver.java.runtime": "Java(TM) SE Runtime Environment (build 1.8.0_05-b13)", + "driver.java.version": "1.8.0_05", + "driver.java.vm": "Java HotSpot(TM) 64-Bit Server VM (build 25.5-b02, mixed mode)", + "hostname": "Armons-MacBook-Air.local", + "kernel.name": "darwin", + "kernel.version": "14.4.0\n", + "memory.totalbytes": "8589934592", + "os.name": "darwin", + "os.version": "14.4.0", + "storage.bytesfree": "35888713728", + "storage.bytestotal": "249821659136", + "storage.volume": "/dev/disk1" + }, + "Resources": { + "CPU": 2600, + "MemoryMB": 8192, + "DiskMB": 34226, + "IOPS": 0, + "Networks": null + }, + "Reserved": null, + "Links": {}, + "Meta": {}, + "NodeClass": "", + "Drain": false, + "Status": "ready", + "StatusDescription": "", + "CreateIndex": 3, + "ModifyIndex": 4 + } + ``` + +
    +
    + +# /v1/node/\/allocations +## GET + +
    +
    Description
    +
    + Query the allocations belonging to a single node. +
    + +
    Method
    +
    GET
    + +
    URL
    +
    `/v1/node//allocations`
    + +
    Parameters
    +
    + None +
    + +
    Returns
    +
    + + ```javascript + [ + { + "ID": "3575ba9d-7a12-0c96-7b28-add168c67984", + "EvalID": "151accaa-1ac6-90fe-d427-313e70ccbb88", + "Name": "binstore-storagelocker.binsl[0]", + "NodeID": "a703c3ca-5ff8-11e5-9213-970ee8879d1b", + "JobID": "binstore-storagelocker", + "TaskGroup": "binsl", + "DesiredStatus": "run", + "DesiredDescription": "", + "ClientStatus": "running", + "ClientDescription": "", + "CreateIndex": 16, + "ModifyIndex": 16 + }, + ... + ] + ``` + +
    +
    + +# /v1/node/\/evaluate +## PUT / POST + +
    +
    Description
    +
    + Creates a new evaluation for the given node. This can be used to force + run the scheduling logic if necessary. +
    + +
    Method
    +
    PUT or POST
    + +
    URL
    +
    `/v1/node//evaluate`
    + +
    Parameters
    +
    + None +
    + +
    Returns
    +
    + + ```javascript + { + "EvalIDs": ["d092fdc0-e1fd-2536-67d8-43af8ca798ac"], + "EvalCreateIndex": 35, + "NodeModifyIndex": 34, + } + ``` + +
    +
    + +# /v1/node/\/drain +## PUT / POST + +
    +
    Description
    +
    + Toggle the drain mode of the node. When enabled, no further + allocations will be assigned and existing allocations will be + migrated. +
    + +
    Method
    +
    PUT or POSt
    + +
    URL
    +
    `/v1/node//drain`
    + +
    Parameters
    +
    +
      +
    • + enable + required + Boolean value provided as a query parameter to either set + enabled to true or false. +
      • +
    +
    + +
    Returns
    +
    + + ```javascript + { + "EvalID": "d092fdc0-e1fd-2536-67d8-43af8ca798ac", + "EvalCreateIndex": 35, + "NodeModifyIndex": 34, + } + ``` + +
    +
    + diff --git a/website/source/docs/http/nodes.html.md b/website/source/docs/http/nodes.html.md new file mode 100644 index 000000000..36fa96fcd --- /dev/null +++ b/website/source/docs/http/nodes.html.md @@ -0,0 +1,57 @@ +--- +layout: "http" +page_title: "HTTP API: /v1/nodes" +sidebar_current: "docs-http-nodes" +description: |- + The '/1/nodes' endpoint is used to list the client nodes. +--- + +# /v1/nodes + +The `nodes` endpoint is used to query the status of client nodes. +By default, the agent's local region is used; another region can +be specified using the `?region=` query parameter. + +## GET + +
    +
    Description
    +
    + Lists all the client nodes registered with Nomad. +
    + +
    Method
    +
    GET
    + +
    URL
    +
    `/v1/nodes`
    + +
    Parameters
    +
    + None +
    + +
    Returns
    +
    + + ```javascript + [ + { + "ID": "c9972143-861d-46e6-df73-1d8287bc3e66", + "Datacenter": "dc1", + "Name": "web-8e40e308", + "NodeClass": "", + "Drain": false, + "Status": "ready", + "StatusDescription": "", + "CreateIndex": 3, + "ModifyIndex": 4 + }, + ... + ] + ``` + +
    +
    + + diff --git a/website/source/layouts/http.erb b/website/source/layouts/http.erb index e2de19061..1de0f8888 100644 --- a/website/source/layouts/http.erb +++ b/website/source/layouts/http.erb @@ -28,12 +28,12 @@ > Nodes From 34751085eec623944734795b37b1dcc380463a52 Mon Sep 17 00:00:00 2001 From: Armon Dadgar Date: Sun, 20 Sep 2015 17:54:42 -0700 Subject: [PATCH 12/17] website: reordering docs --- website/source/docs/http/job.html.md | 70 ++++++++++++++-------------- 1 file changed, 35 insertions(+), 35 deletions(-) diff --git a/website/source/docs/http/job.html.md b/website/source/docs/http/job.html.md index 2d79cb264..e50685f1d 100644 --- a/website/source/docs/http/job.html.md +++ b/website/source/docs/http/job.html.md @@ -216,41 +216,6 @@ region is used; another region can be specified using the `?region=` query param -# /v1/job/\/evaluate -## PUT / POST - -
    -
    Description
    -
    - Creates a new evaluation for the given job. This can be used to force - run the scheduling logic if necessary. -
    - -
    Method
    -
    PUT or POST
    - -
    URL
    -
    `/v1/job//evaluate`
    - -
    Parameters
    -
    - None -
    - -
    Returns
    -
    - - ```javascript - { - "EvalID": "d092fdc0-e1fd-2536-67d8-43af8ca798ac", - "EvalCreateIndex": 35, - "JobModifyIndex": 34, - } - ``` - -
    -
    - # /v1/job/\/allocations ## GET @@ -297,6 +262,41 @@ region is used; another region can be specified using the `?region=` query param +# /v1/job/\/evaluate +## PUT / POST + +
    +
    Description
    +
    + Creates a new evaluation for the given job. This can be used to force + run the scheduling logic if necessary. +
    + +
    Method
    +
    PUT or POST
    + +
    URL
    +
    `/v1/job//evaluate`
    + +
    Parameters
    +
    + None +
    + +
    Returns
    +
    + + ```javascript + { + "EvalID": "d092fdc0-e1fd-2536-67d8-43af8ca798ac", + "EvalCreateIndex": 35, + "JobModifyIndex": 34, + } + ``` + +
    +
    + # /v1/job/\/evaluations ## GET From 9925b0d19968a725de5bf34f7061a6a9af60c35d Mon Sep 17 00:00:00 2001 From: Armon Dadgar Date: Sun, 20 Sep 2015 17:59:57 -0700 Subject: [PATCH 13/17] website: Alloc API docs --- website/source/docs/http/alloc.html.md | 188 ++++++++++++++++++++++++ website/source/docs/http/allocs.html.md | 59 ++++++++ website/source/layouts/http.erb | 8 +- 3 files changed, 251 insertions(+), 4 deletions(-) create mode 100644 website/source/docs/http/alloc.html.md create mode 100644 website/source/docs/http/allocs.html.md diff --git a/website/source/docs/http/alloc.html.md b/website/source/docs/http/alloc.html.md new file mode 100644 index 000000000..8889f55ab --- /dev/null +++ b/website/source/docs/http/alloc.html.md @@ -0,0 +1,188 @@ +--- +layout: "http" +page_title: "HTTP API: /v1/allocation" +sidebar_current: "docs-http-alloc-" +description: |- + The '/1/allocation' endpoint is used to query a specific allocation. +--- + +# /v1/allocation + +The `allocation` endpoint is used to query the a specific allocation. +By default, the agent's local region is used; another region can +be specified using the `?region=` query parameter. + +## GET + +
    +
    Description
    +
    + Query a specific allocation. +
    + +
    Method
    +
    GET
    + +
    URL
    +
    `/v1/allocation/`
    + +
    Parameters
    +
    + None +
    + +
    Returns
    +
    + + ```javascript + { + "ID": "3575ba9d-7a12-0c96-7b28-add168c67984", + "EvalID": "151accaa-1ac6-90fe-d427-313e70ccbb88", + "Name": "binstore-storagelocker.binsl[3]", + "NodeID": "", + "JobID": "binstore-storagelocker", + "Job": { + "Region": "global", + "ID": "binstore-storagelocker", + "Name": "binstore-storagelocker", + "Type": "service", + "Priority": 50, + "AllAtOnce": false, + "Datacenters": [ + "us2", + "eu1" + ], + "Constraints": [ + { + "Hard": false, + "LTarget": "kernel.os", + "RTarget": "windows", + "Operand": "=", + "Weight": 0 + } + ], + "TaskGroups": [ + { + "Name": "binsl", + "Count": 5, + "Constraints": [ + { + "Hard": false, + "LTarget": "kernel.os", + "RTarget": "linux", + "Operand": "=", + "Weight": 0 + } + ], + "Tasks": [ + { + "Name": "binstore", + "Driver": "docker", + "Config": { + "image": "hashicorp/binstore" + }, + "Constraints": null, + "Resources": { + "CPU": 500, + "MemoryMB": 0, + "DiskMB": 0, + "IOPS": 0, + "Networks": [ + { + "Device": "", + "CIDR": "", + "IP": "", + "MBits": 100, + "ReservedPorts": null, + "DynamicPorts": 0 + } + ] + }, + "Meta": null + }, + { + "Name": "storagelocker", + "Driver": "java", + "Config": { + "image": "hashicorp/storagelocker" + }, + "Constraints": [ + { + "Hard": false, + "LTarget": "kernel.arch", + "RTarget": "amd64", + "Operand": "=", + "Weight": 0 + } + ], + "Resources": { + "CPU": 500, + "MemoryMB": 0, + "DiskMB": 0, + "IOPS": 0, + "Networks": null + }, + "Meta": null + } + ], + "Meta": { + "elb_checks": "3", + "elb_interval": "10", + "elb_mode": "tcp" + } + } + ], + "Update": { + "Stagger": 0, + "MaxParallel": 0 + }, + "Meta": { + "foo": "bar" + }, + "Status": "", + "StatusDescription": "", + "CreateIndex": 14, + "ModifyIndex": 14 + }, + "TaskGroup": "binsl", + "Resources": { + "CPU": 1000, + "MemoryMB": 0, + "DiskMB": 0, + "IOPS": 0, + "Networks": [ + { + "Device": "", + "CIDR": "", + "IP": "", + "MBits": 100, + "ReservedPorts": null, + "DynamicPorts": 0 + } + ] + }, + "TaskResources": null, + "Metrics": { + "NodesEvaluated": 0, + "NodesFiltered": 0, + "ClassFiltered": null, + "ConstraintFiltered": null, + "NodesExhausted": 0, + "ClassExhausted": null, + "DimensionExhaused": null, + "Scores": null, + "AllocationTime": 9408, + "CoalescedFailures": 4 + }, + "DesiredStatus": "failed", + "DesiredDescription": "failed to find a node for placement", + "ClientStatus": "failed", + "ClientDescription": "", + "CreateIndex": 16, + "ModifyIndex": 16 + } + ``` + +
    +
    + diff --git a/website/source/docs/http/allocs.html.md b/website/source/docs/http/allocs.html.md new file mode 100644 index 000000000..44ad8aa7e --- /dev/null +++ b/website/source/docs/http/allocs.html.md @@ -0,0 +1,59 @@ +--- +layout: "http" +page_title: "HTTP API: /v1/allocations" +sidebar_current: "docs-http-allocs" +description: |- + The '/1/allocations' endpoint is used to list the allocations. +--- + +# /v1/allocations + +The `allocations` endpoint is used to query the status of allocations. +By default, the agent's local region is used; another region can +be specified using the `?region=` query parameter. + +## GET + +
    +
    Description
    +
    + Lists all the allocations. +
    + +
    Method
    +
    GET
    + +
    URL
    +
    `/v1/allocations`
    + +
    Parameters
    +
    + None +
    + +
    Returns
    +
    + + ```javascript + [ + { + "ID": "3575ba9d-7a12-0c96-7b28-add168c67984", + "EvalID": "151accaa-1ac6-90fe-d427-313e70ccbb88", + "Name": "binstore-storagelocker.binsl[3]", + "NodeID": "c9972143-861d-46e6-df73-1d8287bc3e66", + "JobID": "binstore-storagelocker", + "TaskGroup": "binsl", + "DesiredStatus": "run", + "DesiredDescription": "", + "ClientStatus": "running", + "ClientDescription": "", + "CreateIndex": 16, + "ModifyIndex": 16 + }, + ... + ] + ``` + +
    +
    + diff --git a/website/source/layouts/http.erb b/website/source/layouts/http.erb index 1de0f8888..b65cfd712 100644 --- a/website/source/layouts/http.erb +++ b/website/source/layouts/http.erb @@ -41,12 +41,12 @@ > Allocations From 7cdc7323e7bc9e00551ed6f85a30ea1081500a0f Mon Sep 17 00:00:00 2001 From: Armon Dadgar Date: Sun, 20 Sep 2015 18:05:42 -0700 Subject: [PATCH 14/17] website: adding Eval API docs --- website/source/docs/http/eval.html.md | 105 +++++++++++++++++++++++++ website/source/docs/http/evals.html.md | 62 +++++++++++++++ website/source/layouts/http.erb | 8 +- 3 files changed, 171 insertions(+), 4 deletions(-) create mode 100644 website/source/docs/http/eval.html.md create mode 100644 website/source/docs/http/evals.html.md diff --git a/website/source/docs/http/eval.html.md b/website/source/docs/http/eval.html.md new file mode 100644 index 000000000..cba43900c --- /dev/null +++ b/website/source/docs/http/eval.html.md @@ -0,0 +1,105 @@ +--- +layout: "http" +page_title: "HTTP API: /v1/evaluation" +sidebar_current: "docs-http-eval-" +description: |- + The '/1/evaluation' endpoint is used to query a specific evaluation. +--- + +# /v1/evaluation + +The `evaluation` endpoint is used to query a specific evaluations. +By default, the agent's local region is used; another region can +be specified using the `?region=` query parameter. + +## GET + +
    +
    Description
    +
    + Lists all the evaluations. +
    + +
    Method
    +
    GET
    + +
    URL
    +
    `/v1/evaluations`
    + +
    Parameters
    +
    + None +
    + +
    Returns
    +
    + + ```javascript + { + "ID": "151accaa-1ac6-90fe-d427-313e70ccbb88", + "Priority": 50, + "Type": "service", + "TriggeredBy": "job-register", + "JobID": "binstore-storagelocker", + "JobModifyIndex": 14, + "NodeID": "", + "NodeModifyIndex": 0, + "Status": "complete", + "StatusDescription": "", + "Wait": 0, + "NextEval": "", + "PreviousEval": "", + "CreateIndex": 15, + "ModifyIndex": 17 + } + ``` + +
    +
    + +# /v1/evaluation/\/allocations +## GET + +
    +
    Description
    +
    + Query the allocations created or modified by an evaluation. +
    + +
    Method
    +
    GET
    + +
    URL
    +
    `/v1/evaluation//allocations`
    + +
    Parameters
    +
    + None +
    + +
    Returns
    +
    + + ```javascript + [ + { + "ID": "3575ba9d-7a12-0c96-7b28-add168c67984", + "EvalID": "151accaa-1ac6-90fe-d427-313e70ccbb88", + "Name": "binstore-storagelocker.binsl[0]", + "NodeID": "a703c3ca-5ff8-11e5-9213-970ee8879d1b", + "JobID": "binstore-storagelocker", + "TaskGroup": "binsl", + "DesiredStatus": "run", + "DesiredDescription": "", + "ClientStatus": "running", + "ClientDescription": "", + "CreateIndex": 16, + "ModifyIndex": 16 + }, + ... + ] + ``` + +
    +
    + diff --git a/website/source/docs/http/evals.html.md b/website/source/docs/http/evals.html.md new file mode 100644 index 000000000..3bc22da8f --- /dev/null +++ b/website/source/docs/http/evals.html.md @@ -0,0 +1,62 @@ +--- +layout: "http" +page_title: "HTTP API: /v1/evaluations" +sidebar_current: "docs-http-evals" +description: |- + The '/1/evaluations' endpoint is used to list the evaluations. +--- + +# /v1/evaluations + +The `evaluations` endpoint is used to query the status of evaluations. +By default, the agent's local region is used; another region can +be specified using the `?region=` query parameter. + +## GET + +
    +
    Description
    +
    + Lists all the evaluations. +
    + +
    Method
    +
    GET
    + +
    URL
    +
    `/v1/evaluations`
    + +
    Parameters
    +
    + None +
    + +
    Returns
    +
    + + ```javascript + [ + { + "ID": "151accaa-1ac6-90fe-d427-313e70ccbb88", + "Priority": 50, + "Type": "service", + "TriggeredBy": "job-register", + "JobID": "binstore-storagelocker", + "JobModifyIndex": 14, + "NodeID": "", + "NodeModifyIndex": 0, + "Status": "complete", + "StatusDescription": "", + "Wait": 0, + "NextEval": "", + "PreviousEval": "", + "CreateIndex": 15, + "ModifyIndex": 17 + }, + ... + ] + ``` + +
    +
    + diff --git a/website/source/layouts/http.erb b/website/source/layouts/http.erb index b65cfd712..3e6da507e 100644 --- a/website/source/layouts/http.erb +++ b/website/source/layouts/http.erb @@ -54,12 +54,12 @@ > Evaluations From c13ac2036ee63f11ffbcade9ea7c3fca082cb6c3 Mon Sep 17 00:00:00 2001 From: Armon Dadgar Date: Sun, 20 Sep 2015 19:08:02 -0700 Subject: [PATCH 15/17] website: agent self docs --- website/source/docs/http/agent-self.html.md | 165 ++++++++++++++++++++ website/source/layouts/http.erb | 29 +++- 2 files changed, 192 insertions(+), 2 deletions(-) create mode 100644 website/source/docs/http/agent-self.html.md diff --git a/website/source/docs/http/agent-self.html.md b/website/source/docs/http/agent-self.html.md new file mode 100644 index 000000000..db280b293 --- /dev/null +++ b/website/source/docs/http/agent-self.html.md @@ -0,0 +1,165 @@ +--- +layout: "http" +page_title: "HTTP API: /v1/agent/self" +sidebar_current: "docs-http-agent-self" +description: |- + The '/1/agent/self' endpoint is used to query the state of the agent. +--- + +# /v1/agent/self + +The `self` endpoint is used to query the state of the target agent. + +## GET + +
    +
    Description
    +
    + Lists all the evaluations. +
    + +
    Method
    +
    GET
    + +
    URL
    +
    `/v1/evaluations`
    + +
    Parameters
    +
    + None +
    + +
    Returns
    +
    + + ```javascript + { + "config": { + "Region": "global", + "Datacenter": "dc1", + "NodeName": "", + "DataDir": "", + "LogLevel": "DEBUG", + "BindAddr": "127.0.0.1", + "EnableDebug": true, + "Ports": { + "HTTP": 4646, + "RPC": 4647, + "Serf": 4648 + }, + "Addresses": { + "HTTP": "", + "RPC": "", + "Serf": "" + }, + "AdvertiseAddrs": { + "RPC": "", + "Serf": "" + }, + "Client": { + "Enabled": true, + "StateDir": "", + "AllocDir": "", + "Servers": null, + "NodeID": "", + "NodeClass": "", + "Meta": null + }, + "Server": { + "Enabled": true, + "Bootstrap": false, + "BootstrapExpect": 0, + "DataDir": "", + "ProtocolVersion": 0, + "NumSchedulers": 0, + "EnabledSchedulers": null + }, + "Telemetry": null, + "LeaveOnInt": false, + "LeaveOnTerm": false, + "EnableSyslog": false, + "SyslogFacility": "", + "DisableUpdateCheck": false, + "DisableAnonymousSignature": true, + "Revision": "", + "Version": "0.1.0", + "VersionPrerelease": "dev", + "DevMode": true, + "Atlas": null + }, + "member": { + "Name": "Armons-MacBook-Air.local.global", + "Addr": "127.0.0.1", + "Port": 4648, + "Tags": { + "bootstrap": "1", + "build": "0.1.0dev", + "dc": "dc1", + "port": "4647", + "region": "global", + "role": "nomad", + "vsn": "1", + "vsn_max": "1", + "vsn_min": "1" + }, + "Status": "alive", + "ProtocolMin": 1, + "ProtocolMax": 3, + "ProtocolCur": 2, + "DelegateMin": 2, + "DelegateMax": 4, + "DelegateCur": 4 + }, + "stats": { + "client": { + "heartbeat_ttl": "19116443712", + "known_servers": "0", + "last_heartbeat": "8222075779", + "num_allocations": "0" + }, + "nomad": { + "bootstrap": "false", + "known_regions": "1", + "leader": "true", + "server": "true" + }, + "raft": { + "applied_index": "91", + "commit_index": "91", + "fsm_pending": "0", + "last_contact": "never", + "last_log_index": "91", + "last_log_term": "1", + "last_snapshot_index": "0", + "last_snapshot_term": "0", + "num_peers": "0", + "state": "Leader", + "term": "1" + }, + "runtime": { + "arch": "amd64", + "cpu_count": "4", + "goroutines": "58", + "kernel.name": "darwin", + "max_procs": "1", + "version": "go1.4.2" + }, + "serf": { + "encrypted": "false", + "event_queue": "0", + "event_time": "1", + "failed": "0", + "intent_queue": "0", + "left": "0", + "member_time": "1", + "members": "1", + "query_queue": "0", + "query_time": "1" + } + } + } + ``` + +
    +
    + diff --git a/website/source/layouts/http.erb b/website/source/layouts/http.erb index 3e6da507e..ebe451935 100644 --- a/website/source/layouts/http.erb +++ b/website/source/layouts/http.erb @@ -64,11 +64,36 @@
+ > + Status + + + > Agent From 71817ffbbaef38cbac21682077a9c9b9123e2a15 Mon Sep 17 00:00:00 2001 From: Armon Dadgar Date: Sun, 20 Sep 2015 19:18:37 -0700 Subject: [PATCH 16/17] website: agent API docs --- .../docs/http/agent-force-leave.html.md | 47 +++++++++++++ website/source/docs/http/agent-join.html.md | 53 +++++++++++++++ .../source/docs/http/agent-members.html.md | 67 +++++++++++++++++++ website/source/docs/http/agent-self.html.md | 4 +- 4 files changed, 169 insertions(+), 2 deletions(-) create mode 100644 website/source/docs/http/agent-force-leave.html.md create mode 100644 website/source/docs/http/agent-join.html.md create mode 100644 website/source/docs/http/agent-members.html.md diff --git a/website/source/docs/http/agent-force-leave.html.md b/website/source/docs/http/agent-force-leave.html.md new file mode 100644 index 000000000..8fcd62e27 --- /dev/null +++ b/website/source/docs/http/agent-force-leave.html.md @@ -0,0 +1,47 @@ +--- +layout: "http" +page_title: "HTTP API: /v1/agent/force-leave" +sidebar_current: "docs-http-agent-force-leave" +description: |- + The '/1/agent/force-leave' endpoint is force a gossip member to leave. +--- + +# /v1/agent/force-leave + +The `foce-leave` endpoint is used to force a member of the gossip pool from +the "failed" state into the "left" state. This allows the consensus protocol to +remove the peer and stop attempting replication. This is only applicable for +servers. + +## PUT / POST + +
+
Description
+
+ Force a failed gossip member into the left state. +
+ +
Method
+
PUT or POST
+ +
URL
+
`/v1/agent/force-leave`
+ +
Parameters
+
+
    +
  • + node + required + The name of the node to force leave. +
    • +
+
+ +
Returns
+
+ + A `200` status code on success. +
+
+ diff --git a/website/source/docs/http/agent-join.html.md b/website/source/docs/http/agent-join.html.md new file mode 100644 index 000000000..c2ead7df3 --- /dev/null +++ b/website/source/docs/http/agent-join.html.md @@ -0,0 +1,53 @@ +--- +layout: "http" +page_title: "HTTP API: /v1/agent/join" +sidebar_current: "docs-http-agent-join" +description: |- + The '/1/agent/join' endpoint is used to cluster the Nomad servers. +--- + +# /v1/agent/join + +The `join` endpoint is used to cluster the Nomad servers using a gossip pool. +The servers participate in a peer-to-peer gossip, and `join` is used to introduce +a member to the pool. This is only applicable for servers. + +## PUT / POST + +
+
Description
+
+ Initiate a join between the agent and target peers. +
+ +
Method
+
PUT or POST
+ +
URL
+
`/v1/agent/join`
+ +
Parameters
+
+
    +
  • + address + required + The address to join. Can be provided multiple times + to attempt joining multiple peers. +
    • +
+
+ +
Returns
+
+ + ```javascript + { + "num_joined": 1, + "error": "" + } + ``` + +
+
+ diff --git a/website/source/docs/http/agent-members.html.md b/website/source/docs/http/agent-members.html.md new file mode 100644 index 000000000..f56b5f922 --- /dev/null +++ b/website/source/docs/http/agent-members.html.md @@ -0,0 +1,67 @@ +--- +layout: "http" +page_title: "HTTP API: /v1/agent/members" +sidebar_current: "docs-http-agent-members" +description: |- + The '/1/agent/members' endpoint is used to query the gossip peers. +--- + +# /v1/agent/members + +The `members` endpoint is used to query the agent for the known peers in +the gossip pool. This is only applicable to servers. + +## GET + +
+
Description
+
+ Lists the known members of the gossip pool. +
+ +
Method
+
GET
+ +
URL
+
`/v1/agent/members`
+ +
Parameters
+
+ None +
+ +
Returns
+
+ + ```javascript + [ + { + "Name": "Armons-MacBook-Air.local.global", + "Addr": "127.0.0.1", + "Port": 4648, + "Tags": { + "bootstrap": "1", + "build": "0.1.0dev", + "dc": "dc1", + "port": "4647", + "region": "global", + "role": "nomad", + "vsn": "1", + "vsn_max": "1", + "vsn_min": "1" + }, + "Status": "alive", + "ProtocolMin": 1, + "ProtocolMax": 3, + "ProtocolCur": 2, + "DelegateMin": 2, + "DelegateMax": 4, + "DelegateCur": 4 + }, + ... + ] + ``` + +
+
+ diff --git a/website/source/docs/http/agent-self.html.md b/website/source/docs/http/agent-self.html.md index db280b293..a7a03debc 100644 --- a/website/source/docs/http/agent-self.html.md +++ b/website/source/docs/http/agent-self.html.md @@ -15,14 +15,14 @@ The `self` endpoint is used to query the state of the target agent.
Description
- Lists all the evaluations. + Query the state of the target agent.
Method
GET
URL
-
`/v1/evaluations`
+
`/v1/agent/self`
Parameters
From a06dce3dbaa43146cc28da90b8813d9adf6ae8d1 Mon Sep 17 00:00:00 2001 From: Armon Dadgar Date: Sun, 20 Sep 2015 19:23:58 -0700 Subject: [PATCH 17/17] website: adding status API endpoints --- website/source/docs/http/status.html.md | 77 +++++++++++++++++++++++++ website/source/layouts/http.erb | 18 ++---- 2 files changed, 82 insertions(+), 13 deletions(-) create mode 100644 website/source/docs/http/status.html.md diff --git a/website/source/docs/http/status.html.md b/website/source/docs/http/status.html.md new file mode 100644 index 000000000..797d8875a --- /dev/null +++ b/website/source/docs/http/status.html.md @@ -0,0 +1,77 @@ +--- +layout: "http" +page_title: "HTTP API: /v1/status/" +sidebar_current: "docs-http-status" +description: |- + The '/1/status/' endpoints are used to query the system status. +--- + +# /v1/status/leader + +By default, the agent's local region is used; another region can +be specified using the `?region=` query parameter. + +## GET + +
+
Description
+
+ Returns the address of the current leader in the region. +
+ +
Method
+
GET
+ +
URL
+
`/v1/status/leader`
+ +
Parameters
+
+ None +
+ +
Returns
+
+ + ```javascript + "127.0.0.1:4647" + ``` + +
+
+ +# /v1/status/peers + +## GET + +
+
Description
+
+ Returns the set of raft peers in the region. +
+ +
Method
+
GET
+ +
URL
+
`/v1/status/peers`
+ +
Parameters
+
+ None +
+ +
Returns
+
+ + ```javascript + [ + "127.0.0.1:4647", + ... + ] + ``` + +
+
+ + diff --git a/website/source/layouts/http.erb b/website/source/layouts/http.erb index ebe451935..957b571f1 100644 --- a/website/source/layouts/http.erb +++ b/website/source/layouts/http.erb @@ -64,19 +64,6 @@ - > - Status - - - > Agent
    @@ -97,6 +84,11 @@
+ + > + Status + + <% end %>