kemko/nomad
1
0
Fork 0
mirror of https://github.com/kemko/nomad.git synced 2026-01-07 19:05:42 +03:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'f-docs'

Browse Source
This commit is contained in:
Armon Dadgar
2015-09-20 19:25:25 -07:00
parent 81321bbbd7 a06dce3dba
commit d13f03175f
27 changed files with 1867 additions and 478 deletions
Download Patch File Download Diff File Expand all files Collapse all files

16
client/client.go
View File

@@ -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)

3
command/agent/job_endpoint.go
View File

@@ -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")
}

9
nomad/structs/structs.go
View File

@@ -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()

15
website/source/docs/drivers/custom.html.md
View File

@@ -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.

14
website/source/docs/drivers/docker.html.md Normal file
View File

@@ -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

358
website/source/docs/drivers/docker/index.html.md
View File

@@ -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
<dl class="api">
<dt>Description</dt>
<dd>
Configures the root IAM credentials used.
This is a root protected endpoint.
</dd>
<dt>Method</dt>
<dd>POST</dd>
<dt>URL</dt>
<dd>`/aws/config/root`</dd>
<dt>Parameters</dt>
<dd>
<ul>
<li>
<span class="param">access_key</span>
<span class="param-flags">required</span>
The AWS Access Key
</li>
<li>
<span class="param">secret_key</span>
<span class="param-flags">required</span>
The AWS Secret Key
</li>
<li>
<span class="param">region</span>
<span class="param-flags">required</span>
The AWS region for API calls
</li>
</ul>
</dd>
<dt>Returns</dt>
<dd>
A `204` response code.
</dd>
</dl>
### /aws/config/lease
#### POST
<dl class="api">
<dt>Description</dt>
<dd>
Configures the lease settings for generated credentials.
This is a root protected endpoint.
</dd>
<dt>Method</dt>
<dd>POST</dd>
<dt>URL</dt>
<dd>`/aws/config/lease`</dd>
<dt>Parameters</dt>
<dd>
<ul>
<li>
<span class="param">lease</span>
<span class="param-flags">required</span>
The lease value provided as a string duration
with time suffix. Hour is the largest suffix.
</li>
<li>
<span class="param">lease_max</span>
<span class="param-flags">required</span>
The maximum lease value provided as a string duration
with time suffix. Hour is the largest suffix.
</li>
</ul>
</dd>
<dt>Returns</dt>
<dd>
A `204` response code.
</dd>
</dl>
### /aws/roles/
#### POST
<dl class="api">
<dt>Description</dt>
<dd>
Creates or updates a named role.
</dd>
<dt>Method</dt>
<dd>POST</dd>
<dt>URL</dt>
<dd>`/aws/roles/<name>`</dd>
<dt>Parameters</dt>
<dd>
<ul>
<li>
<span class="param">policy</span>
<span class="param-flags">required</span>
The IAM policy in JSON format.
</li>
</ul>
</dd>
<dt>Returns</dt>
<dd>
A `204` response code.
</dd>
</dl>
#### GET
<dl class="api">
<dt>Description</dt>
<dd>
Queries a named role.
</dd>
<dt>Method</dt>
<dd>GET</dd>
<dt>URL</dt>
<dd>`/aws/roles/<name>`</dd>
<dt>Parameters</dt>
<dd>
None
</dd>
<dt>Returns</dt>
<dd>
```javascript
{
"data": {
"policy": "..."
}
}
```
</dd>
</dl>
#### DELETE
<dl class="api">
<dt>Description</dt>
<dd>
Deletes a named role.
</dd>
<dt>Method</dt>
<dd>DELETE</dd>
<dt>URL</dt>
<dd>`/aws/roles/<name>`</dd>
<dt>Parameters</dt>
<dd>
None
</dd>
<dt>Returns</dt>
<dd>
A `204` response code.
</dd>
</dl>
### /aws/creds/
#### GET
<dl class="api">
<dt>Description</dt>
<dd>
Generates a dynamic IAM credential based on the named role.
</dd>
<dt>Method</dt>
<dd>GET</dd>
<dt>URL</dt>
<dd>`/aws/creds/<name>`</dd>
<dt>Parameters</dt>
<dd>
None
</dd>
<dt>Returns</dt>
<dd>
```javascript
{
"data": {
"access_key": "...",
"secret_key": "..."
}
}
```
</dd>
</dl>

50
website/source/docs/drivers/exec.html.md Normal file
View File

@@ -0,0 +1,50 @@
---
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`
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.

79
website/source/docs/drivers/index.html.md
View File

@@ -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](/docs/jobspec/index.html),
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/<name>`, it looks up an IAM policy named `<name>` 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.

14
website/source/docs/drivers/java.html.md Normal file
View File

@@ -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

14
website/source/docs/drivers/qemu.html.md Normal file
View File

@@ -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

47
website/source/docs/http/agent-force-leave.html.md Normal file
View File

@@ -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
<dl>
<dt>Description</dt>
<dd>
Force a failed gossip member into the left state.
</dd>
<dt>Method</dt>
<dd>PUT or POST</dd>
<dt>URL</dt>
<dd>`/v1/agent/force-leave`</dd>
<dt>Parameters</dt>
<dd>
<ul>
<li>
<span class="param">node</span>
<span class="param-flags">required</span>
The name of the node to force leave.
</li>
</ul>
</dd>
<dt>Returns</dt>
<dd>
A `200` status code on success.
</dd>
</dl>

53
website/source/docs/http/agent-join.html.md Normal file
View File

@@ -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
<dl>
<dt>Description</dt>
<dd>
Initiate a join between the agent and target peers.
</dd>
<dt>Method</dt>
<dd>PUT or POST</dd>
<dt>URL</dt>
<dd>`/v1/agent/join`</dd>
<dt>Parameters</dt>
<dd>
<ul>
<li>
<span class="param">address</span>
<span class="param-flags">required</span>
The address to join. Can be provided multiple times
to attempt joining multiple peers.
</li>
</ul>
</dd>
<dt>Returns</dt>
<dd>
```javascript
{
"num_joined": 1,
"error": ""
}
```
</dd>
</dl>

67
website/source/docs/http/agent-members.html.md Normal file
View File

@@ -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
<dl>
<dt>Description</dt>
<dd>
Lists the known members of the gossip pool.
</dd>
<dt>Method</dt>
<dd>GET</dd>
<dt>URL</dt>
<dd>`/v1/agent/members`</dd>
<dt>Parameters</dt>
<dd>
None
</dd>
<dt>Returns</dt>
<dd>
```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
},
...
]
```
</dd>
</dl>

165
website/source/docs/http/agent-self.html.md Normal file
View File

@@ -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
<dl>
<dt>Description</dt>
<dd>
Query the state of the target agent.
</dd>
<dt>Method</dt>
<dd>GET</dd>
<dt>URL</dt>
<dd>`/v1/agent/self`</dd>
<dt>Parameters</dt>
<dd>
None
</dd>
<dt>Returns</dt>
<dd>
```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"
}
}
}
```
</dd>
</dl>

188
website/source/docs/http/alloc.html.md Normal file
View File

@@ -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
<dl>
<dt>Description</dt>
<dd>
Query a specific allocation.
</dd>
<dt>Method</dt>
<dd>GET</dd>
<dt>URL</dt>
<dd>`/v1/allocation/<ID>`</dd>
<dt>Parameters</dt>
<dd>
None
</dd>
<dt>Returns</dt>
<dd>
```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
}
```
</dd>
</dl>

59
website/source/docs/http/allocs.html.md Normal file
View File

@@ -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
<dl>
<dt>Description</dt>
<dd>
Lists all the allocations.
</dd>
<dt>Method</dt>
<dd>GET</dd>
<dt>URL</dt>
<dd>`/v1/allocations`</dd>
<dt>Parameters</dt>
<dd>
None
</dd>
<dt>Returns</dt>
<dd>
```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
},
...
]
```
</dd>
</dl>

105
website/source/docs/http/eval.html.md Normal file
View File

@@ -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
<dl>
<dt>Description</dt>
<dd>
Lists all the evaluations.
</dd>
<dt>Method</dt>
<dd>GET</dd>
<dt>URL</dt>
<dd>`/v1/evaluations`</dd>
<dt>Parameters</dt>
<dd>
None
</dd>
<dt>Returns</dt>
<dd>
```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
}
```
</dd>
</dl>
# /v1/evaluation/\<ID\>/allocations
## GET
<dl>
<dt>Description</dt>
<dd>
Query the allocations created or modified by an evaluation.
</dd>
<dt>Method</dt>
<dd>GET</dd>
<dt>URL</dt>
<dd>`/v1/evaluation/<id>/allocations`</dd>
<dt>Parameters</dt>
<dd>
None
</dd>
<dt>Returns</dt>
<dd>
```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
},
...
]
```
</dd>
</dl>

62
website/source/docs/http/evals.html.md Normal file
View File

@@ -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
<dl>
<dt>Description</dt>
<dd>
Lists all the evaluations.
</dd>
<dt>Method</dt>
<dd>GET</dd>
<dt>URL</dt>
<dd>`/v1/evaluations`</dd>
<dt>Parameters</dt>
<dd>
None
</dd>
<dt>Returns</dt>
<dd>
```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
},
...
]
```
</dd>
</dl>

90
website/source/docs/http/index.html.md
View File

@@ -3,13 +3,93 @@ 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 and API Layout
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 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.
TODO: Document Nomand API

348
website/source/docs/http/job.html.md Normal file
View File

@@ -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/\<ID\>
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
<dl>
<dt>Description</dt>
<dd>
Query a single job for its specification and status.
</dd>
<dt>Method</dt>
<dd>GET</dd>
<dt>URL</dt>
<dd>`/v1/job/<id>`</dd>
<dt>Parameters</dt>
<dd>
None
</dd>
<dt>Returns</dt>
<dd>
```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
}
```
</dd>
</dl>
## PUT / POST
<dl>
<dt>Description</dt>
<dd>
Registers a new job or updates an existing job
</dd>
<dt>Method</dt>
<dd>PUT or POST</dd>
<dt>URL</dt>
<dd>`/v1/job/<ID>`</dd>
<dt>Parameters</dt>
<dd>
<ul>
<li>
<span class="param">Job</span>
<span class="param-flags">required</span>
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.
</li>
</ul>
</dd>
<dt>Returns</dt>
<dd>
```javascript
{
"EvalID": "d092fdc0-e1fd-2536-67d8-43af8ca798ac",
"EvalCreateIndex": 35,
"JobModifyIndex": 34,
}
```
</dd>
</dl>
## DELETE
<dl>
<dt>Description</dt>
<dd>
Deregisters a job, and stops all allocations part of it.
</dd>
<dt>Method</dt>
<dd>DELETE</dd>
<dt>URL</dt>
<dd>`/v1/job/<ID>`</dd>
<dt>Parameters</dt>
<dd>
None
</dd>
<dt>Returns</dt>
<dd>
```javascript
{
"EvalID": "d092fdc0-e1fd-2536-67d8-43af8ca798ac",
"EvalCreateIndex": 35,
"JobModifyIndex": 34,
}
```
</dd>
</dl>
# /v1/job/\<ID\>/allocations
## GET
<dl>
<dt>Description</dt>
<dd>
Query the allocations belonging to a single job.
</dd>
<dt>Method</dt>
<dd>GET</dd>
<dt>URL</dt>
<dd>`/v1/job/<id>/allocations`</dd>
<dt>Parameters</dt>
<dd>
None
</dd>
<dt>Returns</dt>
<dd>
```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
},
...
]
```
</dd>
</dl>
# /v1/job/\<ID\>/evaluate
## PUT / POST
<dl>
<dt>Description</dt>
<dd>
Creates a new evaluation for the given job. This can be used to force
run the scheduling logic if necessary.
</dd>
<dt>Method</dt>
<dd>PUT or POST</dd>
<dt>URL</dt>
<dd>`/v1/job/<ID>/evaluate`</dd>
<dt>Parameters</dt>
<dd>
None
</dd>
<dt>Returns</dt>
<dd>
```javascript
{
"EvalID": "d092fdc0-e1fd-2536-67d8-43af8ca798ac",
"EvalCreateIndex": 35,
"JobModifyIndex": 34,
}
```
</dd>
</dl>
# /v1/job/\<ID\>/evaluations
## GET
<dl>
<dt>Description</dt>
<dd>
Query the evaluations belonging to a single job.
</dd>
<dt>Method</dt>
<dd>GET</dd>
<dt>URL</dt>
<dd>`/v1/job/<id>/evaluations`</dd>
<dt>Parameters</dt>
<dd>
None
</dd>
<dt>Returns</dt>
<dd>
```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
},
...
]
```
</dd>
</dl>

96
website/source/docs/http/jobs.html.md Normal file
View File

@@ -0,0 +1,96 @@
---
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
<dl>
<dt>Description</dt>
<dd>
Lists all the jobs registered with Nomad.
</dd>
<dt>Method</dt>
<dd>GET</dd>
<dt>URL</dt>
<dd>`/v1/jobs`</dd>
<dt>Parameters</dt>
<dd>
None
</dd>
<dt>Returns</dt>
<dd>
```javascript
[
{
"ID": "binstore-storagelocker",
"Name": "binstore-storagelocker",
"Type": "service",
"Priority": 50,
"Status": "",
"StatusDescription": "",
"CreateIndex": 14,
"ModifyIndex": 14
},
...
]
```
</dd>
</dl>
## PUT / POST
<dl>
<dt>Description</dt>
<dd>
Registers a new job.
</dd>
<dt>Method</dt>
<dd>PUT or POST</dd>
<dt>URL</dt>
<dd>`/v1/jobs`</dd>
<dt>Parameters</dt>
<dd>
<ul>
<li>
<span class="param">Job</span>
<span class="param-flags">required</span>
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/<ID>`](/docs/http/job.html).
</li>
</ul>
</dd>
<dt>Returns</dt>
<dd>
```javascript
{
"EvalID": "d092fdc0-e1fd-2536-67d8-43af8ca798ac",
"EvalCreateIndex": 35,
"JobModifyIndex": 34,
}
```
</dd>
</dl>

208
website/source/docs/http/node.html.md Normal file
View File

@@ -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
<dl>
<dt>Description</dt>
<dd>
Query the status of a client node registered with Nomad.
</dd>
<dt>Method</dt>
<dd>GET</dd>
<dt>URL</dt>
<dd>`/v1/node/<ID>`</dd>
<dt>Parameters</dt>
<dd>
None
</dd>
<dt>Returns</dt>
<dd>
```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
}
```
</dd>
</dl>
# /v1/node/\<ID\>/allocations
## GET
<dl>
<dt>Description</dt>
<dd>
Query the allocations belonging to a single node.
</dd>
<dt>Method</dt>
<dd>GET</dd>
<dt>URL</dt>
<dd>`/v1/node/<id>/allocations`</dd>
<dt>Parameters</dt>
<dd>
None
</dd>
<dt>Returns</dt>
<dd>
```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
},
...
]
```
</dd>
</dl>
# /v1/node/\<ID\>/evaluate
## PUT / POST
<dl>
<dt>Description</dt>
<dd>
Creates a new evaluation for the given node. This can be used to force
run the scheduling logic if necessary.
</dd>
<dt>Method</dt>
<dd>PUT or POST</dd>
<dt>URL</dt>
<dd>`/v1/node/<ID>/evaluate`</dd>
<dt>Parameters</dt>
<dd>
None
</dd>
<dt>Returns</dt>
<dd>
```javascript
{
"EvalIDs": ["d092fdc0-e1fd-2536-67d8-43af8ca798ac"],
"EvalCreateIndex": 35,
"NodeModifyIndex": 34,
}
```
</dd>
</dl>
# /v1/node/\<ID\>/drain
## PUT / POST
<dl>
<dt>Description</dt>
<dd>
Toggle the drain mode of the node. When enabled, no further
allocations will be assigned and existing allocations will be
migrated.
</dd>
<dt>Method</dt>
<dd>PUT or POSt</dd>
<dt>URL</dt>
<dd>`/v1/node/<ID>/drain`</dd>
<dt>Parameters</dt>
<dd>
<ul>
<li>
<span class="param">enable</span>
<span class="param-flags">required</span>
Boolean value provided as a query parameter to either set
enabled to true or false.
</li>
</ul>
</dd>
<dt>Returns</dt>
<dd>
```javascript
{
"EvalID": "d092fdc0-e1fd-2536-67d8-43af8ca798ac",
"EvalCreateIndex": 35,
"NodeModifyIndex": 34,
}
```
</dd>
</dl>

57
website/source/docs/http/nodes.html.md Normal file
View File

@@ -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
<dl>
<dt>Description</dt>
<dd>
Lists all the client nodes registered with Nomad.
</dd>
<dt>Method</dt>
<dd>GET</dd>
<dt>URL</dt>
<dd>`/v1/nodes`</dd>
<dt>Parameters</dt>
<dd>
None
</dd>
<dt>Returns</dt>
<dd>
```javascript
[
{
"ID": "c9972143-861d-46e6-df73-1d8287bc3e66",
"Datacenter": "dc1",
"Name": "web-8e40e308",
"NodeClass": "",
"Drain": false,
"Status": "ready",
"StatusDescription": "",
"CreateIndex": 3,
"ModifyIndex": 4
},
...
]
```
</dd>
</dl>

77
website/source/docs/http/status.html.md Normal file
View File

@@ -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
<dl>
<dt>Description</dt>
<dd>
Returns the address of the current leader in the region.
</dd>
<dt>Method</dt>
<dd>GET</dd>
<dt>URL</dt>
<dd>`/v1/status/leader`</dd>
<dt>Parameters</dt>
<dd>
None
</dd>
<dt>Returns</dt>
<dd>
```javascript
"127.0.0.1:4647"
```
</dd>
</dl>
# /v1/status/peers
## GET
<dl>
<dt>Description</dt>
<dd>
Returns the set of raft peers in the region.
</dd>
<dt>Method</dt>
<dd>GET</dd>
<dt>URL</dt>
<dd>`/v1/status/peers`</dd>
<dt>Parameters</dt>
<dd>
None
</dd>
<dt>Returns</dt>
<dd>
```javascript
[
"127.0.0.1:4647",
...
]
```
</dd>
</dl>

10
website/source/docs/jobspec/index.html.md
View File

@@ -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:
<td>cpu.numcores</td>
<td>Number of CPU cores on the client</td>
</tr>
<tr>
<td>driver.\<key\></td>
<td>See the [task drivers](/docs/drivers/index.html) for attribute documentation</td>
</tr>
<tr>
<td>hostname</td>
<td>Hostname of the client</td>

61
website/source/layouts/docs.erb
View File

@@ -33,11 +33,40 @@
<li<%= sidebar_current("docs-install") %>>
<a href="/docs/install/index.html">Installation</a>
</li>
</li>
<hr>
<li<%= sidebar_current("docs-jobspec") %>>
<a href="/docs/jobspec/index.html">Job Specification</a>
</li>
</li>
<li<%= sidebar_current("docs-drivers") %>>
<a href="/docs/drivers/index.html">Task Drivers</a>
<ul class="nav">
<li<%= sidebar_current("docs-drivers-docker") %>>
<a href="/docs/drivers/docker.html">Docker</a>
</li>
<li<%= sidebar_current("docs-drivers-exec") %>>
<a href="/docs/drivers/exec.html">Fork/Exec</a>
</li>
<li<%= sidebar_current("docs-drivers-java") %>>
<a href="/docs/drivers/java.html">Java</a>
</li>
<li<%= sidebar_current("docs-drivers-qeumu") %>>
<a href="/docs/drivers/qemu.html">Qemu</a>
</li>
<li<%= sidebar_current("docs-drivers-custom") %>>
<a href="/docs/drivers/custom.html">Custom</a>
</li>
</ul>
</li>
<hr>
<li<%= sidebar_current("docs-commands") %>>
<a href="/docs/commands/index.html">Commands (CLI)</a>
@@ -90,34 +119,6 @@
<li<%= sidebar_current("docs-http") %>>
<a href="/docs/http/index.html">HTTP API</a>
</li>
<hr>
<li<%= sidebar_current("docs-drivers") %>>
<a href="/docs/drivers/index.html">Drivers</a>
<ul class="nav">
<li<%= sidebar_current("docs-drivers-docker") %>>
<a href="/docs/drivers/docker/index.html">Docker</a>
</li>
<li<%= sidebar_current("docs-drivers-exec") %>>
<a href="/docs/drivers/exec/index.html">Fork/Exec</a>
</li>
<li<%= sidebar_current("docs-drivers-java") %>>
<a href="/docs/drivers/java/index.html">Java</a>
</li>
<li<%= sidebar_current("docs-drivers-qeumu") %>>
<a href="/docs/drivers/qemu/index.html">Qemu</a>
</li>
<li<%= sidebar_current("docs-drivers-custom") %>>
<a href="/docs/drivers/custom.html">Custom</a>
</li>
</ul>
</li>
</ul>
</div>
<% end %>

80
website/source/layouts/http.erb
View File

@@ -10,7 +10,85 @@
<li<%= sidebar_current("docs-http-overview") %>>
<a href="/docs/http/index.html">Overview</a>
</li>
</li>
<li<%= sidebar_current("docs-http-job") %>>
<a href="#">Jobs</a>
<ul class="nav nav-visible">
<li<%= sidebar_current("docs-http-jobs") %>>
<a href="/docs/http/jobs.html">/v1/jobs</a>
</li>
<li<%= sidebar_current("docs-http-job-") %>>
<a href="/docs/http/job.html">/v1/job</a>
</li>
</ul>
</li>
<li<%= sidebar_current("docs-http-node") %>>
<a href="#">Nodes</a>
<ul class="nav nav-visible">
<li<%= sidebar_current("docs-http-nodes") %>>
<a href="/docs/http/nodes.html">/v1/nodes</a>
</li>
<li<%= sidebar_current("docs-http-node-") %>>
<a href="/docs/http/node.html">/v1/node</a>
</li>
</ul>
</li>
<li<%= sidebar_current("docs-http-alloc") %>>
<a href="#">Allocations</a>
<ul class="nav nav-visible">
<li<%= sidebar_current("docs-http-allocs") %>>
<a href="/docs/http/allocs.html">/v1/allocations</a>
</li>
<li<%= sidebar_current("docs-http-alloc-") %>>
<a href="/docs/http/alloc.html">/v1/allocation</a>
</li>
</ul>
</li>
<li<%= sidebar_current("docs-http-eval") %>>
<a href="#">Evaluations</a>
<ul class="nav nav-visible">
<li<%= sidebar_current("docs-http-evals") %>>
<a href="/docs/http/evals.html">/v1/evaluations</a>
</li>
<li<%= sidebar_current("docs-http-eval-") %>>
<a href="/docs/http/eval.html">/v1/evaluation</a>
</li>
</ul>
</li>
<li<%= sidebar_current("docs-http-agent") %>>
<a href="#">Agent</a>
<ul class="nav nav-visible">
<li<%= sidebar_current("docs-http-agent-self") %>>
<a href="/docs/http/agent-self.html">/v1/agent/self</a>
</li>
<li<%= sidebar_current("docs-http-agent-join") %>>
<a href="/docs/http/agent-join.html">/v1/agent/join</a>
</li>
<li<%= sidebar_current("docs-http-agent-members") %>>
<a href="/docs/http/agent-members.html">/v1/agent/members</a>
</li>
<li<%= sidebar_current("docs-http-agent-force-leave") %>>
<a href="/docs/http/agent-force-leave.html">/v1/agent/force-leave</a>
</li>
</ul>
</li>
<li<%= sidebar_current("docs-http-status") %>>
<a href="/docs/http/status.html">Status</a>
</li>
</ul>
</div>
<% end %>