diff --git a/website/Gemfile b/website/Gemfile index 405a8c992..efb257727 100644 --- a/website/Gemfile +++ b/website/Gemfile @@ -1,3 +1,3 @@ source "https://rubygems.org" -gem "middleman-hashicorp", "0.3.22" +gem "middleman-hashicorp", "0.3.25" diff --git a/website/Gemfile.lock b/website/Gemfile.lock index 229218ac9..10f5c5078 100644 --- a/website/Gemfile.lock +++ b/website/Gemfile.lock @@ -6,7 +6,7 @@ GEM minitest (~> 5.1) thread_safe (~> 0.3, >= 0.3.4) tzinfo (~> 1.1) - autoprefixer-rails (6.7.7.1) + autoprefixer-rails (7.1.1) execjs bootstrap-sass (3.3.7) autoprefixer-rails (>= 5.2.1) @@ -42,14 +42,15 @@ GEM eventmachine (1.2.3) execjs (2.7.0) ffi (1.9.18) - haml (4.0.7) + haml (5.0.1) + temple (>= 0.8.0) tilt hike (1.2.3) hooks (0.4.1) uber (~> 0.0.14) http_parser.rb (0.6.0) i18n (0.7.0) - json (2.0.3) + json (2.1.0) kramdown (1.13.2) listen (3.0.8) rb-fsevent (~> 0.9, >= 0.9.4) @@ -77,7 +78,7 @@ GEM rack (>= 1.4.5, < 2.0) thor (>= 0.15.2, < 2.0) tilt (~> 1.4.1, < 2.0) - middleman-hashicorp (0.3.22) + middleman-hashicorp (0.3.25) bootstrap-sass (~> 3.3) builder (~> 3.2) middleman (~> 3.4) @@ -101,9 +102,9 @@ GEM mime-types-data (~> 3.2015) mime-types-data (3.2016.0521) mini_portile2 (2.1.0) - minitest (5.10.1) + minitest (5.10.2) multi_json (1.12.1) - nokogiri (1.7.1) + nokogiri (1.7.2) mini_portile2 (~> 2.1.0) padrino-helpers (0.12.8.1) i18n (~> 0.6, >= 0.6.7) @@ -111,7 +112,7 @@ GEM tilt (~> 1.4.1) padrino-support (0.12.8.1) activesupport (>= 3.1) - rack (1.6.5) + rack (1.6.8) rack-livereload (0.3.16) rack rack-test (0.6.3) @@ -121,7 +122,7 @@ GEM ffi (>= 0.5.0) redcarpet (3.4.0) rouge (2.0.7) - sass (3.4.23) + sass (3.4.24) sprockets (2.12.4) hike (~> 1.2) multi_json (~> 1.0) @@ -132,26 +133,27 @@ GEM sprockets-sass (1.3.1) sprockets (~> 2.0) tilt (~> 1.1) + temple (0.8.0) thor (0.19.4) thread_safe (0.3.6) tilt (1.4.1) turbolinks (5.0.1) turbolinks-source (~> 5) - turbolinks-source (5.0.0) + turbolinks-source (5.0.3) tzinfo (1.2.3) thread_safe (~> 0.1) uber (0.0.15) uglifier (2.7.2) execjs (>= 0.3.0) json (>= 1.8.0) - xpath (2.0.0) + xpath (2.1.0) nokogiri (~> 1.3) PLATFORMS ruby DEPENDENCIES - middleman-hashicorp (= 0.3.22) + middleman-hashicorp (= 0.3.25) BUNDLED WITH - 1.14.6 + 1.15.0 diff --git a/website/Makefile b/website/Makefile index d7620d1c2..3bb8b83bf 100644 --- a/website/Makefile +++ b/website/Makefile @@ -1,4 +1,4 @@ -VERSION?="0.3.22" +VERSION?="0.3.25" build: @echo "==> Starting build in Docker..." diff --git a/website/packer.json b/website/packer.json index 35de63232..4184097c0 100644 --- a/website/packer.json +++ b/website/packer.json @@ -8,7 +8,7 @@ "builders": [ { "type": "docker", - "image": "hashicorp/middleman-hashicorp:0.3.22", + "image": "hashicorp/middleman-hashicorp:0.3.25", "discard": "true", "run_command": ["-d", "-i", "-t", "{{ .Image }}", "/bin/sh"] } diff --git a/website/redirects.txt b/website/redirects.txt new file mode 100644 index 000000000..52d173514 --- /dev/null +++ b/website/redirects.txt @@ -0,0 +1,86 @@ +# +# REDIRECTS FILE +# +# This is a sample redirect file. Redirects allow individual projects to add +# their own redirect rules in a declarative manner using Fastly edge +# dictionaries. +# +# FORMAT +# +# Redirects are in the format. There must be at least one space between the +# original path and the new path, and there must be exactly two entries per +# line. +# +# /original-path /new-path +# +# GLOB MATCHING +# +# Because of the way lookup tables work, there is no support for glob matching. +# Fastly does not provide a way to iterate through the lookup table, so it is +# not possible to run through the table and find anything that matches. As such +# URLs must match directly. +# +# More complex redirects are possible, but must be added directly to the +# configuration. Please contact the release engineering team for assistance. +# +# DELETING +# +# Deleting items is not supported at this time. To delete an item, contact the +# release engineering team and they will delete the dictionary item. +# +# MISC +# +# - Blank lines are ignored +# - Comments are hash-style +# - URLs are limited to 256 characters +# - Items are case-sensitive (please use all lowercase) +# + +# Docs +/docs/agent/config.html /docs/agent/configuration/index.html +/docs/jobops /docs/operating-a-job/index.html +/docs/jobops/ /docs/operating-a-job/index.html +/docs/jobops/index.html /docs/operating-a-job/index.html +/docs/jobops/taskconfig.html /docs/operating-a-job/configuring-tasks.html +/docs/jobops/inspecting.html /docs/operating-a-job/inspecting-state.html +/docs/jobops/resources.html /docs/operating-a-job/resource-utilization.html +/docs/jobops/servicediscovery.html /docs/service-discovery/index.html +/docs/jobops/logs.html /docs/operating-a-job/accessing-logs.html +/docs/jobops/updating.html /docs/operating-a-job/update-strategies/index.html +/docs/jobspec /docs/job-specification/index.html +/docs/jobspec/ /docs/job-specification/index.html +/docs/jobspec/index.html /docs/job-specification/index.html +/docs/jobspec/interpreted.html /docs/runtime/interpolation.html +/docs/jobspec/json.html /api/json-jobs.html +/docs/jobspec/environment.html /docs/runtime/environment.html +/docs/jobspec/schedulers.html /docs/runtime/schedulers.html +/docs/jobspec/servicediscovery.html /docs/job-specification/service.html +/docs/jobspec/networking.html /docs/job-specification/network.html +/docs/cluster/automatic.html /guides/cluster/automatic.html +/docs/cluster/manual.html /guides/cluster/manual.html +/docs/cluster/federation.html /guides/cluster/federation.html +/docs/cluster/requirements.html /guides/cluster/requirements.html + +# API +/docs/http/index.html /api/index.html +/docs/http/json-jobs.html /api/json-jobs.html +/docs/http/job.html /api/jobs.html +/docs/http/jobs.html /api/jobs.html +/docs/http/node.html /api/nodes.html +/docs/http/nodes.html /api/nodes.html +/docs/http/alloc.html /api/allocations.html +/docs/http/allocs.html /api/allocations.html +/docs/http/eval.html /api/evaluations.html +/docs/http/evals.html /api/evaluations.html +/docs/http/agent-self.html /api/agent.html +/docs/http/agent-join.html /api/agent.html +/docs/http/agent-members.html /api/agent.html +/docs/http/agent-force-leave.html /api/agent.html +/docs/http/agent-servers.html /api/agent.html +/docs/http/client-fs.html /api/client.html +/docs/http/client-stats.html /api/client.html +/docs/http/client-allocation-stats.html /api/client.html +/docs/http/regions.html /api/regions.html +/docs/http/status.html /api/status.html +/docs/http/operator.html /api/operator.html +/docs/http/system.html /api/system.html diff --git a/website/scripts/deploy.sh b/website/scripts/deploy.sh index 4a38f4e04..1780079b7 100755 --- a/website/scripts/deploy.sh +++ b/website/scripts/deploy.sh @@ -4,6 +4,7 @@ set -e PROJECT="nomad" PROJECT_URL="www.nomadproject.io" FASTLY_SERVICE_ID="7GrxRJP3PVBuqQbyxYQ0MV" +FASTLY_DICTIONARY_ID="4OEpQ4S6HbEu7wkfTvrWUG" # Ensure the proper AWS environment variables are set if [ -z "$AWS_ACCESS_KEY_ID" ]; then @@ -93,6 +94,71 @@ if [ -z "$NO_UPLOAD" ]; then modify "s3://hc-sites/$PROJECT/latest/" fi +# Add redirects if they exist +if [ -z "$NO_REDIRECTS" ] || [ ! test -f "$DIR/redirects.txt" ]; then + echo "Adding redirects..." + fields=() + while read -r line; do + [[ "$line" =~ ^#.* ]] && continue + [[ -z "$line" ]] && continue + + # Read fields + IFS=" " read -ra parts <<<"$line" + fields+=("${parts[@]}") + done < "$DIR/redirects.txt" + + # Check we have pairs + if [ $((${#fields[@]} % 2)) -ne 0 ]; then + echo "Bad redirects (not an even number)!" + exit 1 + fi + + # Check we don't have more than 1000 entries (yes, it says 2000 below, but that + # is because we've split into multiple lines). + if [ "${#fields}" -gt 2000 ]; then + echo "More than 1000 entries!" + exit 1 + fi + + # Validations + for field in "${fields[@]}"; do + if [ "${#field}" -gt 256 ]; then + echo "'$field' is > 256 characters!" + exit 1 + fi + + if [ "${field:0:1}" != "/" ]; then + echo "'$field' does not start with /!" + exit 1 + fi + done + + # Build the payload for single-request updates. + jq_args=() + jq_query="." + for (( i=0; i<${#fields[@]}; i+=2 )); do + original="${fields[i]}" + redirect="${fields[i+1]}" + echo "Redirecting ${original} -> ${redirect}" + jq_args+=(--arg "key$((i/2))" "${original}") + jq_args+=(--arg "value$((i/2))" "${redirect}") + jq_query+="| .items |= (. + [{op: \"upsert\", item_key: \$key$((i/2)), item_value: \$value$((i/2))}])" + done + json="$(jq "${jq_args[@]}" "${jq_query}" <<<'{"items": []}')" + + # Post the JSON body + curl \ + --fail \ + --silent \ + --output /dev/null \ + --request "PATCH" \ + --header "Fastly-Key: $FASTLY_API_KEY" \ + --header "Content-type: application/json" \ + --header "Accept: application/json" \ + --data "$json"\ + "https://api.fastly.com/service/$FASTLY_SERVICE_ID/dictionary/$FASTLY_DICTIONARY_ID/items" +fi + # Perform a purge of the surrogate key. if [ -z "$NO_PURGE" ]; then echo "Purging Fastly cache..." diff --git a/website/source/api/agent.html.md b/website/source/api/agent.html.md new file mode 100644 index 000000000..a762233ff --- /dev/null +++ b/website/source/api/agent.html.md @@ -0,0 +1,462 @@ +--- +layout: api +page_title: Agent - HTTP API +sidebar_current: api-agent +description: |- + The /agent endpoints interact with the local Nomad agent to interact with + members and servers. +--- + +# Agent HTTP API + +The `/agent` endpoints are used to interact with the local Nomad agent. + +## List Members + +This endpoint queries the agent for the known peers in the gossip pool. This +endpoint is only applicable to servers. Due to the nature of gossip, this is +eventually consistent. + +| Method | Path | Produces | +| ------ | ---------------------------- | -------------------------- | +| `GET` | `/agent/members` | `application/json` | + +The table below shows this endpoint's support for +[blocking queries](/api/index.html#blocking-queries) and +[required ACLs](/api/index.html#acls). + +| Blocking Queries | ACL Required | +| ---------------- | ------------ | +| `NO` | `none` | + +### Sample Request + +```text +$ curl \ + https://nomad.rocks/v1/agent/members +``` + +### Sample Response + +```json +{ + "ServerName": "bacon-mac", + "ServerRegion": "global", + "ServerDC": "dc1", + "Members": [ + { + "Name": "bacon-mac.global", + "Addr": "127.0.0.1", + "Port": 4648, + "Tags": { + "mvn": "1", + "build": "0.5.5dev", + "port": "4647", + "bootstrap": "1", + "role": "nomad", + "region": "global", + "dc": "dc1", + "vsn": "1" + }, + "Status": "alive", + "ProtocolMin": 1, + "ProtocolMax": 5, + "ProtocolCur": 2, + "DelegateMin": 2, + "DelegateMax": 4, + "DelegateCur": 4 + } + ] +} +``` + +## List Servers + +This endpoint lists the known server nodes. The `servers` endpoint is used to +query an agent in client mode for its list of known servers. Client nodes +register themselves with these server addresses so that they may dequeue work. +The servers endpoint can be used to keep this configuration up to date if there +are changes in the cluster. + +| Method | Path | Produces | +| ------ | ---------------------------- | -------------------------- | +| `GET` | `/agent/servers` | `application/json` | + +The table below shows this endpoint's support for +[blocking queries](/api/index.html#blocking-queries) and +[required ACLs](/api/index.html#acls). + +| Blocking Queries | ACL Required | +| ---------------- | ------------ | +| `NO` | `none` | + +### Sample Request + +```text +$ curl \ + https://nomad.rocks/v1/agent/servers +``` + +### Sample Response + +```json +[ + "127.0.0.1:4647" +] +``` + +## Update Servers + +This endpoint updates the list of known servers to the provided list. This +**replaces** all previous server addresses with the new list. + +| Method | Path | Produces | +| ------ | ---------------------------- | -------------------------- | +| `POST` | `/agent/servers` | `(empty body)` | + +The table below shows this endpoint's support for +[blocking queries](/api/index.html#blocking-queries) and +[required ACLs](/api/index.html#acls). + +| Blocking Queries | ACL Required | +| ---------------- | ------------ | +| `NO` | `none` | + +### Parameters + +- `address` `(string: )` - Specifies the list of addresses in the + format `ip:port`. This is specified as a query string! + +### Sample Request + +```text +$ curl \ + --request POST \ + https://nomad.rocks/v1/agent/servers?address=1.2.3.4:4647&addres=5.6.7.8:4647 +``` + +## Query Self + +This endpoint queries the state of the target agent (self). + +| Method | Path | Produces | +| ------ | ---------------------------- | -------------------------- | +| `POST` | `/agent/self` | `application/json` | + +The table below shows this endpoint's support for +[blocking queries](/api/index.html#blocking-queries) and +[required ACLs](/api/index.html#acls). + +| Blocking Queries | Consistency Modes | ACL Required | +| ---------------- | ----------------- | ------------ | +| `NO` | `none` | `none` | + +### Sample Request + +```text +$ curl \ + https://nomad.rocks/v1/agent/self +``` + +### Sample Response + +```json +{ + "config": { + "Addresses": { + "HTTP": "127.0.0.1", + "RPC": "127.0.0.1", + "Serf": "127.0.0.1" + }, + "AdvertiseAddrs": { + "HTTP": "127.0.0.1:4646", + "RPC": "127.0.0.1:4647", + "Serf": "127.0.0.1:4648" + }, + "Atlas": { + "Endpoint": "", + "Infrastructure": "", + "Join": false + }, + "BindAddr": "127.0.0.1", + "Client": { + "AllocDir": "", + "ChrootEnv": {}, + "ClientMaxPort": 14512, + "ClientMinPort": 14000, + "Enabled": true, + "GCDiskUsageThreshold": 99, + "GCInodeUsageThreshold": 99, + "GCInterval": 600000000000, + "MaxKillTimeout": "30s", + "Meta": {}, + "NetworkInterface": "lo0", + "NetworkSpeed": 0, + "NodeClass": "", + "Options": { + "driver.docker.volumes": "true" + }, + "Reserved": { + "CPU": 0, + "DiskMB": 0, + "IOPS": 0, + "MemoryMB": 0, + "ParsedReservedPorts": null, + "ReservedPorts": "" + }, + "Servers": null, + "StateDir": "" + }, + "Consul": { + "Addr": "", + "Auth": "", + "AutoAdvertise": true, + "CAFile": "", + "CertFile": "", + "ChecksUseAdvertise": false, + "ClientAutoJoin": true, + "ClientServiceName": "nomad-client", + "EnableSSL": false, + "KeyFile": "", + "ServerAutoJoin": true, + "ServerServiceName": "nomad", + "Timeout": 5000000000, + "Token": "", + "VerifySSL": false + }, + "DataDir": "", + "Datacenter": "dc1", + "DevMode": true, + "DisableAnonymousSignature": true, + "DisableUpdateCheck": false, + "EnableDebug": true, + "EnableSyslog": false, + "Files": null, + "HTTPAPIResponseHeaders": {}, + "LeaveOnInt": false, + "LeaveOnTerm": false, + "LogLevel": "DEBUG", + "NodeName": "", + "Ports": { + "HTTP": 4646, + "RPC": 4647, + "Serf": 4648 + }, + "Region": "global", + "Revision": "f551dcb83e3ac144c9dbb90583b6e82d234662e9", + "Server": { + "BootstrapExpect": 0, + "DataDir": "", + "Enabled": true, + "EnabledSchedulers": null, + "HeartbeatGrace": "", + "NodeGCThreshold": "", + "NumSchedulers": 0, + "ProtocolVersion": 0, + "RejoinAfterLeave": false, + "RetryInterval": "30s", + "RetryJoin": [], + "RetryMaxAttempts": 0, + "StartJoin": [] + }, + "SyslogFacility": "LOCAL0", + "TLSConfig": { + "CAFile": "", + "CertFile": "", + "EnableHTTP": false, + "EnableRPC": false, + "KeyFile": "", + "VerifyServerHostname": false + }, + "Telemetry": { + "CirconusAPIApp": "", + "CirconusAPIToken": "", + "CirconusAPIURL": "", + "CirconusBrokerID": "", + "CirconusBrokerSelectTag": "", + "CirconusCheckDisplayName": "", + "CirconusCheckForceMetricActivation": "", + "CirconusCheckID": "", + "CirconusCheckInstanceID": "", + "CirconusCheckSearchTag": "", + "CirconusCheckSubmissionURL": "", + "CirconusCheckTags": "", + "CirconusSubmissionInterval": "", + "CollectionInterval": "1s", + "DataDogAddr": "", + "DisableHostname": false, + "PublishAllocationMetrics": false, + "PublishNodeMetrics": false, + "StatsdAddr": "", + "StatsiteAddr": "", + "UseNodeName": false + }, + "Vault": { + "Addr": "https://vault.service.consul:8200", + "AllowUnauthenticated": true, + "ConnectionRetryIntv": 30000000000, + "Enabled": null, + "Role": "", + "TLSCaFile": "", + "TLSCaPath": "", + "TLSCertFile": "", + "TLSKeyFile": "", + "TLSServerName": "", + "TLSSkipVerify": null, + "TaskTokenTTL": "", + "Token": "root" + }, + "Version": "0.5.5", + "VersionPrerelease": "dev" + }, + "member": { + "Addr": "127.0.0.1", + "DelegateCur": 4, + "DelegateMax": 4, + "DelegateMin": 2, + "Name": "bacon-mac.global", + "Port": 4648, + "ProtocolCur": 2, + "ProtocolMax": 5, + "ProtocolMin": 1, + "Status": "alive", + "Tags": { + "role": "nomad", + "region": "global", + "dc": "dc1", + "vsn": "1", + "mvn": "1", + "build": "0.5.5dev", + "port": "4647", + "bootstrap": "1" + } + }, + "stats": { + "runtime": { + "cpu_count": "8", + "kernel.name": "darwin", + "arch": "amd64", + "version": "go1.8", + "max_procs": "7", + "goroutines": "79" + }, + "nomad": { + "server": "true", + "leader": "true", + "leader_addr": "127.0.0.1:4647", + "bootstrap": "false", + "known_regions": "1" + }, + "raft": { + "num_peers": "0", + "fsm_pending": "0", + "last_snapshot_index": "0", + "last_log_term": "2", + "commit_index": "144", + "term": "2", + "last_log_index": "144", + "protocol_version_max": "3", + "snapshot_version_max": "1", + "latest_configuration_index": "1", + "latest_configuration": "[{Suffrage:Voter ID:127.0.0.1:4647 Address:127.0.0.1:4647}]", + "last_contact": "never", + "applied_index": "144", + "protocol_version": "1", + "protocol_version_min": "0", + "snapshot_version_min": "0", + "state": "Leader", + "last_snapshot_term": "0" + }, + "client": { + "heartbeat_ttl": "17.79568937s", + "node_id": "fb2170a8-257d-3c64-b14d-bc06cc94e34c", + "known_servers": "127.0.0.1:4647", + "num_allocations": "0", + "last_heartbeat": "10.107423052s" + }, + "serf": { + "event_time": "1", + "event_queue": "0", + "encrypted": "false", + "member_time": "1", + "query_time": "1", + "intent_queue": "0", + "query_queue": "0", + "members": "1", + "failed": "0", + "left": "0", + "health_score": "0" + } + } +} +``` + +## Join Agent + +This endpoint introduces a new member to the gossip pool. This endpoint is only +eligible for servers. + +| Method | Path | Produces | +| ------ | ---------------------------- | -------------------------- | +| `POST` | `/agent/join` | `application/json` | + +The table below shows this endpoint's support for +[blocking queries](/api/index.html#blocking-queries) and +[required ACLs](/api/index.html#acls). + +| Blocking Queries | ACL Required | +| ---------------- | ------------ | +| `NO` | `none` | + +### Parameters + +- `address` `(string: )` - Specifies the address to join in the + `ip:port` format. This is provided as a query parameter and may be specified + multiple times to join multiple servers. + +### Sample Request + +```text +$ curl \ + --request POST \ + https://nomad.rocks/v1/agent/join?address=1.2.3.4&address=5.6.7.8 +``` + +### Sample Response + +```json +{ + "error": "", + "num_joined": 2 +} +``` + +## Force Leave Agent + +This endpoint forces a member of the gossip pool from the `"failed"` state to +the `"left"` state. This allows the consensus protocol to remove the peer and +stop attempting replication. This is only applicable for servers. + +| Method | Path | Produces | +| ------ | ---------------------------- | -------------------------- | +| `POST` | `/agent/force-leave` | `application/json` | + +The table below shows this endpoint's support for +[blocking queries](/api/index.html#blocking-queries) and +[required ACLs](/api/index.html#acls). + +| Blocking Queries | ACL Required | +| ---------------- | ------------ | +| `NO` | `none` | + +### Parameters + +- `node` `(string: )` - Specifies the name of the node to force leave. + +### Sample Request + +```text +$ curl \ + --request POST \ + https://nomad.rocks/v1/agent/force-leave?node=client-ab2e23dc +``` diff --git a/website/source/api/allocations.html.md b/website/source/api/allocations.html.md new file mode 100644 index 000000000..ee321f8b4 --- /dev/null +++ b/website/source/api/allocations.html.md @@ -0,0 +1,524 @@ +--- +layout: api +page_title: Allocations - HTTP API +sidebar_current: api-allocations +description: |- + The /allocation endpoints are used to query for and interact with allocations. +--- + +# Allocations HTTP API + +The `/allocation` endpoints are used to query for and interact with allocations. + +## List Allocations + +This endpoint lists all allocations. + +| Method | Path | Produces | +| ------ | ------------------------- | -------------------------- | +| `GET` | `/v1/allocations` | `application/json` | + +The table below shows this endpoint's support for +[blocking queries](/api/index.html#blocking-queries) and +[required ACLs](/api/index.html#acls). + +| Blocking Queries | ACL Required | +| ---------------- | ------------ | +| `YES` | `none` | + +### Parameters + +- `prefix` `(string: "")`- Specifies a string to filter allocations on based on + an index prefix. This is specified as a querystring parameter. + +### Sample Request + +```text +$ curl \ + https://nomad.rocks/v1/allocations +``` + +```text +$ curl \ + https://nomad.rocks/v1/allocations?prefix=a8198d79 +``` + +### Sample Response + +```json +[ + { + "ID": "a8198d79-cfdb-6593-a999-1e9adabcba2e", + "EvalID": "5456bd7a-9fc0-c0dd-6131-cbee77f57577", + "Name": "example.cache[0]", + "NodeID": "fb2170a8-257d-3c64-b14d-bc06cc94e34c", + "JobID": "example", + "TaskGroup": "cache", + "DesiredStatus": "run", + "DesiredDescription": "", + "ClientStatus": "running", + "ClientDescription": "", + "TaskStates": { + "redis": { + "State": "running", + "Failed": false, + "Events": [ + { + "Type": "Received", + "Time": 1495747371795703800, + "FailsTask": false, + "RestartReason": "", + "SetupError": "", + "DriverError": "", + "ExitCode": 0, + "Signal": 0, + "Message": "", + "KillTimeout": 0, + "KillError": "", + "KillReason": "", + "StartDelay": 0, + "DownloadError": "", + "ValidationError": "", + "DiskLimit": 0, + "FailedSibling": "", + "VaultError": "", + "TaskSignalReason": "", + "TaskSignal": "", + "DriverMessage": "" + }, + { + "Type": "Driver", + "Time": 1495747371798867200, + "FailsTask": false, + "RestartReason": "", + "SetupError": "", + "DriverError": "", + "ExitCode": 0, + "Signal": 0, + "Message": "", + "KillTimeout": 0, + "KillError": "", + "KillReason": "", + "StartDelay": 0, + "DownloadError": "", + "ValidationError": "", + "DiskLimit": 0, + "FailedSibling": "", + "VaultError": "", + "TaskSignalReason": "", + "TaskSignal": "", + "DriverMessage": "Downloading image redis:3.2" + }, + { + "Type": "Started", + "Time": 1495747379525667800, + "FailsTask": false, + "RestartReason": "", + "SetupError": "", + "DriverError": "", + "ExitCode": 0, + "Signal": 0, + "Message": "", + "KillTimeout": 0, + "KillError": "", + "KillReason": "", + "StartDelay": 0, + "DownloadError": "", + "ValidationError": "", + "DiskLimit": 0, + "FailedSibling": "", + "VaultError": "", + "TaskSignalReason": "", + "TaskSignal": "", + "DriverMessage": "" + } + ] + } + }, + "CreateIndex": 54, + "ModifyIndex": 57, + "CreateTime": 1495747371794276400 + } +] +``` + +## Read Allocation + +This endpoint reads information about a specific allocation. + +| Method | Path | Produces | +| ------ | -------------------------- | -------------------------- | +| `GET` | `/v1/allocation/:alloc_id` | `application/json` | + +The table below shows this endpoint's support for +[blocking queries](/api/index.html#blocking-queries) and +[required ACLs](/api/index.html#acls). + +| Blocking Queries | ACL Required | +| ---------------- | ------------ | +| `YES` | `none` | + +### Parameters + +- `:alloc_id` `(string: )`- Specifies the UUID of the allocation. This + must be the full UUID, not the short 8-character one. This is specified as + part of the path. + +### Sample Request + +```text +$ curl \ + https://nomad.rocks/v1/allocation/5456bd7a-9fc0-c0dd-6131-cbee77f57577 +``` + +### Sample Response + +```json +{ + "ID": "a8198d79-cfdb-6593-a999-1e9adabcba2e", + "EvalID": "5456bd7a-9fc0-c0dd-6131-cbee77f57577", + "Name": "example.cache[0]", + "NodeID": "fb2170a8-257d-3c64-b14d-bc06cc94e34c", + "JobID": "example", + "Job": { + "Region": "global", + "ID": "example", + "ParentID": "", + "Name": "example", + "Type": "service", + "Priority": 50, + "AllAtOnce": false, + "Datacenters": [ + "dc1" + ], + "Constraints": null, + "TaskGroups": [ + { + "Name": "cache", + "Count": 1, + "Constraints": null, + "RestartPolicy": { + "Attempts": 10, + "Interval": 300000000000, + "Delay": 25000000000, + "Mode": "delay" + }, + "Tasks": [ + { + "Name": "redis", + "Driver": "docker", + "User": "", + "Config": { + "port_map": [ + { + "db": 6379 + } + ], + "image": "redis:3.2" + }, + "Env": null, + "Services": [ + { + "Name": "global-redis-check", + "PortLabel": "db", + "Tags": [ + "global", + "cache" + ], + "Checks": [ + { + "Name": "alive", + "Type": "tcp", + "Command": "", + "Args": null, + "Path": "", + "Protocol": "", + "PortLabel": "", + "Interval": 10000000000, + "Timeout": 2000000000, + "InitialStatus": "" + } + ] + } + ], + "Vault": null, + "Templates": null, + "Constraints": null, + "Resources": { + "CPU": 500, + "MemoryMB": 10, + "DiskMB": 0, + "IOPS": 0, + "Networks": [ + { + "Device": "", + "CIDR": "", + "IP": "", + "MBits": 10, + "ReservedPorts": null, + "DynamicPorts": [ + { + "Label": "db", + "Value": 0 + } + ] + } + ] + }, + "DispatchPayload": null, + "Meta": null, + "KillTimeout": 5000000000, + "LogConfig": { + "MaxFiles": 10, + "MaxFileSizeMB": 10 + }, + "Artifacts": null, + "Leader": false + } + ], + "EphemeralDisk": { + "Sticky": false, + "SizeMB": 300, + "Migrate": false + }, + "Meta": null + } + ], + "Update": { + "Stagger": 10000000000, + "MaxParallel": 0 + }, + "Periodic": null, + "ParameterizedJob": null, + "Payload": null, + "Meta": null, + "VaultToken": "", + "Status": "pending", + "StatusDescription": "", + "CreateIndex": 52, + "ModifyIndex": 52, + "JobModifyIndex": 52 + }, + "TaskGroup": "cache", + "Resources": { + "CPU": 500, + "MemoryMB": 10, + "DiskMB": 300, + "IOPS": 0, + "Networks": [ + { + "Device": "lo0", + "CIDR": "", + "IP": "127.0.0.1", + "MBits": 10, + "ReservedPorts": null, + "DynamicPorts": [ + { + "Label": "db", + "Value": 23116 + } + ] + } + ] + }, + "SharedResources": { + "CPU": 0, + "MemoryMB": 0, + "DiskMB": 300, + "IOPS": 0, + "Networks": null + }, + "TaskResources": { + "redis": { + "CPU": 500, + "MemoryMB": 10, + "DiskMB": 0, + "IOPS": 0, + "Networks": [ + { + "Device": "lo0", + "CIDR": "", + "IP": "127.0.0.1", + "MBits": 10, + "ReservedPorts": null, + "DynamicPorts": [ + { + "Label": "db", + "Value": 23116 + } + ] + } + ] + } + }, + "Metrics": { + "NodesEvaluated": 1, + "NodesFiltered": 0, + "NodesAvailable": { + "dc1": 1 + }, + "ClassFiltered": null, + "ConstraintFiltered": null, + "NodesExhausted": 0, + "ClassExhausted": null, + "DimensionExhausted": null, + "Scores": { + "fb2170a8-257d-3c64-b14d-bc06cc94e34c.binpack": 0.6205732522109244 + }, + "AllocationTime": 31729, + "CoalescedFailures": 0 + }, + "DesiredStatus": "run", + "DesiredDescription": "", + "ClientStatus": "running", + "ClientDescription": "", + "TaskStates": { + "redis": { + "State": "running", + "Failed": false, + "Events": [ + { + "Type": "Received", + "Time": 1495747371795703800, + "FailsTask": false, + "RestartReason": "", + "SetupError": "", + "DriverError": "", + "ExitCode": 0, + "Signal": 0, + "Message": "", + "KillTimeout": 0, + "KillError": "", + "KillReason": "", + "StartDelay": 0, + "DownloadError": "", + "ValidationError": "", + "DiskLimit": 0, + "FailedSibling": "", + "VaultError": "", + "TaskSignalReason": "", + "TaskSignal": "", + "DriverMessage": "" + }, + { + "Type": "Driver", + "Time": 1495747371798867200, + "FailsTask": false, + "RestartReason": "", + "SetupError": "", + "DriverError": "", + "ExitCode": 0, + "Signal": 0, + "Message": "", + "KillTimeout": 0, + "KillError": "", + "KillReason": "", + "StartDelay": 0, + "DownloadError": "", + "ValidationError": "", + "DiskLimit": 0, + "FailedSibling": "", + "VaultError": "", + "TaskSignalReason": "", + "TaskSignal": "", + "DriverMessage": "Downloading image redis:3.2" + }, + { + "Type": "Started", + "Time": 1495747379525667800, + "FailsTask": false, + "RestartReason": "", + "SetupError": "", + "DriverError": "", + "ExitCode": 0, + "Signal": 0, + "Message": "", + "KillTimeout": 0, + "KillError": "", + "KillReason": "", + "StartDelay": 0, + "DownloadError": "", + "ValidationError": "", + "DiskLimit": 0, + "FailedSibling": "", + "VaultError": "", + "TaskSignalReason": "", + "TaskSignal": "", + "DriverMessage": "" + } + ] + } + }, + "PreviousAllocation": "", + "CreateIndex": 54, + "ModifyIndex": 57, + "AllocModifyIndex": 54, + "CreateTime": 1495747371794276400 +} +``` + +#### Field Reference + +- `TaskStates` - A map of tasks to their current state and the latest events + that have effected the state. + + A task can be in the following states: + + - `TaskStatePending` - The task is waiting to be run, either for the first + time or due to a restart. + + - `TaskStateRunning` - The task is currently running. + + - `TaskStateDead` - The task is dead and will not run again. + + Further the state contains the `StartedAt` and `FinishedAt` times of the + task. `StartedAt` can be updated multiple times if the task restarts but + `FinishedAt` is set only when the task transitions to `TaskStateDead` + +- `Events` - An event contains metadata about the event. The latest 10 events + are stored per task. Each event is timestamped (unix nano-seconds) and has one + of the following types: + + - `Setup Failure` - The task could not be started because there was a + failure setting up the task prior to it running. + + - `Driver Failure` - The task could not be started due to a failure in the + driver. + + - `Started` - The task was started; either for the first time or due to a + restart. + + - `Terminated` - The task was started and exited. + + - `Killing` - The task has been sent the kill signal. + + - `Killed` - The task was killed by an user. + + - `Received` - The task has been pulled by the client at the given timestamp. + + - `Failed Validation` - The task was invalid and as such it didn't run. + + - `Restarting` - The task terminated and is being restarted. + + - `Not Restarting` - the task has failed and is not being restarted because + it has exceeded its restart policy. + + - `Downloading Artifacts` - The task is downloading the artifact(s) + - specified in the task. + + - `Failed Artifact Download` - Artifact(s) specified in the task failed to + download. + + - `Restart Signaled` - The task was singled to be restarted. + + - `Signaling` - The task was is being sent a signal. + + - `Sibling Task Failed` - A task in the same task group failed. + + - `Leader Task Dead` - The group's leader task is dead. + + - `Driver` - A message from the driver. + + - `Task Setup` - Task setup messages. + + Depending on the type the event will have applicable annotations. diff --git a/website/source/api/client.html.md b/website/source/api/client.html.md new file mode 100644 index 000000000..dda6d4d4d --- /dev/null +++ b/website/source/api/client.html.md @@ -0,0 +1,562 @@ +--- +layout: api +page_title: Client - HTTP API +sidebar_current: api-client +description: |- + The /client endpoints interact with the local Nomad agent to interact with + client members. +--- + +# Client HTTP API + +The `/client` endpoints are used to interact with the Nomad clients. The API +endpoints are hosted by the Nomad client and requests have to be made to the +Client where the particular allocation was placed. + +## Read Stats + +This endpoint queries the actual resources consumed on a node. The API endpoint +is hosted by the Nomad client and requests have to be made to the nomad client +whose resource usage metrics are of interest. + +| Method | Path | Produces | +| ------ | ---------------------------- | -------------------------- | +| `GET` | `/client/stats` | `application/json` | + +The table below shows this endpoint's support for +[blocking queries](/api/index.html#blocking-queries) and +[required ACLs](/api/index.html#acls). + +| Blocking Queries | ACL Required | +| ---------------- | ------------ | +| `NO` | `none` | + +### Sample Request + +```text +$ curl \ + https://nomad.rocks/v1/client/stats +``` + +### Sample Response + +```json +{ + "AllocDirStats": { + "Available": 142943150080, + "Device": "", + "InodesUsedPercent": 0.05312946180421879, + "Mountpoint": "", + "Size": 249783500800, + "Used": 106578206720, + "UsedPercent": 42.668233241448746 + }, + "CPU": [ + { + "CPU": "cpu0", + "Idle": 80, + "System": 11, + "Total": 20, + "User": 9 + }, + { + "CPU": "cpu1", + "Idle": 99, + "System": 0, + "Total": 1, + "User": 1 + }, + { + "CPU": "cpu2", + "Idle": 89, + "System": 7.000000000000001, + "Total": 11, + "User": 4 + }, + { + "CPU": "cpu3", + "Idle": 100, + "System": 0, + "Total": 0, + "User": 0 + }, + { + "CPU": "cpu4", + "Idle": 92.92929292929293, + "System": 4.040404040404041, + "Total": 7.07070707070707, + "User": 3.0303030303030303 + }, + { + "CPU": "cpu5", + "Idle": 99, + "System": 1, + "Total": 1, + "User": 0 + }, + { + "CPU": "cpu6", + "Idle": 92.07920792079209, + "System": 4.9504950495049505, + "Total": 7.920792079207921, + "User": 2.9702970297029703 + }, + { + "CPU": "cpu7", + "Idle": 99, + "System": 0, + "Total": 1, + "User": 1 + } + ], + "CPUTicksConsumed": 1126.8044804480448, + "DiskStats": [ + { + "Available": 142943150080, + "Device": "/dev/disk1", + "InodesUsedPercent": 0.05312946180421879, + "Mountpoint": "/", + "Size": 249783500800, + "Used": 106578206720, + "UsedPercent": 42.668233241448746 + } + ], + "Memory": { + "Available": 6232244224, + "Free": 470618112, + "Total": 17179869184, + "Used": 10947624960 + }, + "Timestamp": 1495743032992498200, + "Uptime": 193520 +} +``` + +## Read Allocation + +The client `allocation` endpoint is used to query the actual resources consumed +by an allocation. The API endpoint is hosted by the Nomad client and requests +have to be made to the nomad client whose resource usage metrics are of +interest. + +| Method | Path | Produces | +| ------ | ------------------------------------ | -------------------------- | +| `GET` | `/client/allocation/:alloc_id/stats` | `application/json` | + +The table below shows this endpoint's support for +[blocking queries](/api/index.html#blocking-queries) and +[required ACLs](/api/index.html#acls). + +| Blocking Queries | ACL Required | +| ---------------- | ------------ | +| `NO` | `none` | + +### Parameters + +- `:alloc_id` `(string: )` - Specifies the allocation ID to query. + This is specified as part of the URL. Note, this must be the _full_ allocation + ID, not the short 8-character one. This is specified as part of the path. + +### Sample Request + +```text +$ curl \ + https://nomad.rocks/v1/client/allocation/5fc98185-17ff-26bc-a802-0c74fa471c99/stats +``` + +### Sample Response + +```json +{ + "ResourceUsage": { + "CpuStats": { + "Measured": [ + "Throttled Periods", + "Throttled Time", + "Percent" + ], + "Percent": 0.14159538847117795, + "SystemMode": 0, + "ThrottledPeriods": 0, + "ThrottledTime": 0, + "TotalTicks": 3.256693934837093, + "UserMode": 0 + }, + "MemoryStats": { + "Cache": 1744896, + "KernelMaxUsage": 0, + "KernelUsage": 0, + "MaxUsage": 4710400, + "Measured": [ + "RSS", + "Cache", + "Swap", + "Max Usage" + ], + "RSS": 1486848, + "Swap": 0 + } + }, + "Tasks": { + "redis": { + "Pids": null, + "ResourceUsage": { + "CpuStats": { + "Measured": [ + "Throttled Periods", + "Throttled Time", + "Percent" + ], + "Percent": 0.14159538847117795, + "SystemMode": 0, + "ThrottledPeriods": 0, + "ThrottledTime": 0, + "TotalTicks": 3.256693934837093, + "UserMode": 0 + }, + "MemoryStats": { + "Cache": 1744896, + "KernelMaxUsage": 0, + "KernelUsage": 0, + "MaxUsage": 4710400, + "Measured": [ + "RSS", + "Cache", + "Swap", + "Max Usage" + ], + "RSS": 1486848, + "Swap": 0 + } + }, + "Timestamp": 1495743243970720000 + } + }, + "Timestamp": 1495743243970720000 +} +``` + +## Read File + +This endpoint reads the contents of a file in an allocation directory. + +| Method | Path | Produces | +| ------ | ---------------------------- | -------------------------- | +| `GET` | `/client/fs/cat/:alloc_id` | `text/plain` | + +The table below shows this endpoint's support for +[blocking queries](/api/index.html#blocking-queries) and +[required ACLs](/api/index.html#acls). + +| Blocking Queries | ACL Required | +| ---------------- | ------------ | +| `NO` | `none` | + +### Parameters + +- `:alloc_id` `(string: )` - Specifies the allocation ID to query. + This is specified as part of the URL. Note, this must be the _full_ allocation + ID, not the short 8-character one. This is specified as part of the path. + +- `path` `(string: "/")` - Specifies the path of the file to read, relative to + the root of the allocation directory. + +### Sample Request + +```text +$ curl \ + https://nomad.rocks/v1/client/fs/cat/5fc98185-17ff-26bc-a802-0c74fa471c99 +``` + +```text +$ curl \ + https://nomad.rocks/v1/client/fs/cat/5fc98185-17ff-26bc-a802-0c74fa471c99?path=alloc/file.json +``` + +### Sample Response + +```text +(whatever was in the file...) +``` + + +## Read File at Offset + +This endpoint reads the contents of a file in an allocation directory at a +particular offset and limit. + +| Method | Path | Produces | +| ------ | ----------------------------- | -------------------------- | +| `GET` | `/client/fs/readat/:alloc_id` | `text/plain` | + +The table below shows this endpoint's support for +[blocking queries](/api/index.html#blocking-queries) and +[required ACLs](/api/index.html#acls). + +| Blocking Queries | ACL Required | +| ---------------- | ------------ | +| `NO` | `none` | + +### Parameters + +- `:alloc_id` `(string: )` - Specifies the allocation ID to query. + This is specified as part of the URL. Note, this must be the _full_ allocation + ID, not the short 8-character one. This is specified as part of the path. + +- `path` `(string: "/")` - Specifies the path of the file to read, relative to + the root of the allocation directory. + +- `offset` `(int: )` - Specifies the byte offset from where content + will be read. + +- `limit` `(int: )` - Specifies the number of bytes to read from the + offset. + +### Sample Request + +```text +$ curl \ + https://nomad.rocks/v1/client/fs/readat/5fc98185-17ff-26bc-a802-0c74fa471c99?path=/alloc/foo&offset=1323&limit=19303 +``` + +### Sample Response + +```text +(whatever was in the file, starting from offset, up to limit bytes...) +``` + +## Stream File + +This endpoint streams the contents of a file in an allocation directory. + +| Method | Path | Produces | +| ------ | ----------------------------- | -------------------------- | +| `GET` | `/client/fs/stream/:alloc_id` | `text/plain` | + +The table below shows this endpoint's support for +[blocking queries](/api/index.html#blocking-queries) and +[required ACLs](/api/index.html#acls). + +| Blocking Queries | ACL Required | +| ---------------- | ------------ | +| `NO` | `none` | + +### Parameters + +- `:alloc_id` `(string: )` - Specifies the allocation ID to query. + This is specified as part of the URL. Note, this must be the _full_ allocation + ID, not the short 8-character one. This is specified as part of the path. + +- `path` `(string: "/")` - Specifies the path of the file to read, relative to + the root of the allocation directory. + +- `offset` `(int: )` - Specifies the byte offset from where content + will be read. + +- `origin` `(string: "start|end")` - Applies the relative offset to either the + start or end of the file. + +### Sample Request + +```text +$ curl \ + https://nomad.rocks/v1/client/fs/stream/5fc98185-17ff-26bc-a802-0c74fa471c99?path=/alloc/logs/redis.log +``` + +### Sample Response + +```json +{ + "File": "alloc/logs/redis.log", + "Offset": 3604480, + "Data": "NTMxOTMyCjUzMTkzMwo1MzE5MzQKNTMx..." +}, +{ + "File": "alloc/logs/redis.log", + "FileEvent": "file deleted" +} +``` + +#### Field Reference + +The return value is a stream of frames. These frames contain the following +fields: + +- `Data` - A base64 encoding of the bytes being streamed. + +- `FileEvent` - An event that could cause a change in the streams position. The + possible values are "file deleted" and "file truncated". + +- `Offset` - Offset is the offset into the stream. + +- `File` - The name of the file being streamed. + +## Stream Logs + +This endpoint streams a task's stderr/stdout logs. + +| Method | Path | Produces | +| ------ | ---------------------------- | -------------------------- | +| `GET` | `/client/fs/logs/:alloc_id` | `text/plain` | + +The table below shows this endpoint's support for +[blocking queries](/api/index.html#blocking-queries) and +[required ACLs](/api/index.html#acls). + +| Blocking Queries | ACL Required | +| ---------------- | ------------ | +| `NO` | `none` | + +### Parameters + +- `:alloc_id` `(string: )` - Specifies the allocation ID to query. + This is specified as part of the URL. Note, this must be the _full_ allocation + ID, not the short 8-character one. This is specified as part of the path. + +- `task` `(string: )` - Specifies the name of the task inside the + allocation to stream logs from. + +- `follow` `(bool: false)`- Specifies whether to tail the logs. + +- `type` `(string: "stderr|stdout")` - Specifies the stream to stream. + +- `offset` `(int: 0)` - Specifies the offset to start streaming from. + +- `origin` `(string: "start|end")` - Specifies either "start" or "end" and + applies the offset relative to either the start or end of the logs + respectively. Defaults to "start". + +- `plain` `(bool: false)` - Return just the plain text without framing. This can + be useful when viewing logs in a browser. + +### Sample Request + +```text +$ curl \ + https://nomad.rocks/v1/client/fs/logs/5fc98185-17ff-26bc-a802-0c74fa471c99 +``` + +### Sample Response + +```json +{ + "File": "alloc/logs/redis.stdout.0", + "Offset": 3604480, + "Data": "NTMxOTMyCjUzMTkzMwo1MzE5MzQKNTMx..." +}, +{ + "File": "alloc/logs/redis.stdout.0", + "FileEvent": "file deleted" +} +``` + +#### Field Reference + +The return value is a stream of frames. These frames contain the following +fields: + +- `Data` - A base64 encoding of the bytes being streamed. + +- `FileEvent` - An event that could cause a change in the streams position. The + possible values are "file deleted" and "file truncated". + +- `Offset` - Offset is the offset into the stream. + +- `File` - The name of the file being streamed. + +## List Files + +This endpoint lists files in an allocation directory. + +| Method | Path | Produces | +| ------ | ---------------------------- | -------------------------- | +| `GET` | `/client/fs/ls/:alloc_id` | `text/plain` | + +The table below shows this endpoint's support for +[blocking queries](/api/index.html#blocking-queries) and +[required ACLs](/api/index.html#acls). + +| Blocking Queries | ACL Required | +| ---------------- | ------------ | +| `NO` | `none` | + +### Parameters + +- `:alloc_id` `(string: )` - Specifies the allocation ID to query. + This is specified as part of the URL. Note, this must be the _full_ allocation + ID, not the short 8-character one. This is specified as part of the path. + +- `path` `(string: "/")` - Specifies the path of the file to read, relative to + the root of the allocation directory. + +### Sample Request + +```text +$ curl \ + https://nomad.rocks/v1/client/fs/ls/5fc98185-17ff-26bc-a802-0c74fa471c99 +``` + +### Sample Response + +```json +[ + { + "Name": "alloc", + "IsDir": true, + "Size": 4096, + "FileMode": "drwxrwxr-x", + "ModTime": "2016-03-15T15:40:00.414236712-07:00" + }, + { + "Name": "redis", + "IsDir": true, + "Size": 4096, + "FileMode": "drwxrwxr-x", + "ModTime": "2016-03-15T15:40:56.810238153-07:00" + } +] +``` + +## Stat File + +This endpoint stats a file in an allocation. + +| Method | Path | Produces | +| ------ | ---------------------------- | -------------------------- | +| `GET` | `/client/fs/stat/:alloc_id` | `text/plain` | + +The table below shows this endpoint's support for +[blocking queries](/api/index.html#blocking-queries) and +[required ACLs](/api/index.html#acls). + +| Blocking Queries | ACL Required | +| ---------------- | ------------ | +| `NO` | `none` | + +### Parameters + +- `:alloc_id` `(string: )` - Specifies the allocation ID to query. + This is specified as part of the URL. Note, this must be the _full_ allocation + ID, not the short 8-character one. This is specified as part of the path. + +- `path` `(string: "/")` - Specifies the path of the file to read, relative to + the root of the allocation directory. + +### Sample Request + +```text +$ curl \ + https://nomad.rocks/v1/client/fs/stat/5fc98185-17ff-26bc-a802-0c74fa471c99 +``` + +### Sample Response + +```json +{ + "Name": "redis-syslog-collector.out", + "IsDir": false, + "Size": 96, + "FileMode": "-rw-rw-r--", + "ModTime": "2016-03-15T15:40:56.822238153-07:00" +} +``` diff --git a/website/source/api/evaluations.html.md b/website/source/api/evaluations.html.md new file mode 100644 index 000000000..e80dd9da5 --- /dev/null +++ b/website/source/api/evaluations.html.md @@ -0,0 +1,266 @@ +--- +layout: api +page_title: Evaluations - HTTP API +sidebar_current: api-evaluations +description: |- + The /evaluation are used to query for and interact with evaluations. +--- + +# Evaluations HTTP API + +The `/evaluation` endpoints are used to query for and interact with evaluations. + +## List Evaluations + +This endpoint lists all evaluations. + +| Method | Path | Produces | +| ------ | ------------------------ | -------------------------- | +| `GET` | `/v1/evaluations` | `application/json` | + +The table below shows this endpoint's support for +[blocking queries](/api/index.html#blocking-queries) and +[required ACLs](/api/index.html#acls). + +| Blocking Queries | ACL Required | +| ---------------- | ------------ | +| `YES` | `none` | + +### Parameters + +- `prefix` `(string: "")`- Specifies a string to filter evaluations on based on + an index prefix. This is specified as a querystring parameter. + +### Sample Request + +```text +$ curl \ + https://nomad.rocks/v1/evaluations +``` + +```text +$ curl \ + https://nomad.rocks/v1/evaluations?prefix=25ba81c +``` + +### Sample Response + +```json +[ + { + "ID": "5456bd7a-9fc0-c0dd-6131-cbee77f57577", + "Priority": 50, + "Type": "service", + "TriggeredBy": "job-register", + "JobID": "example", + "JobModifyIndex": 52, + "NodeID": "", + "NodeModifyIndex": 0, + "Status": "complete", + "StatusDescription": "", + "Wait": 0, + "NextEval": "", + "PreviousEval": "", + "BlockedEval": "", + "FailedTGAllocs": null, + "ClassEligibility": null, + "EscapedComputedClass": false, + "AnnotatePlan": false, + "SnapshotIndex": 53, + "QueuedAllocations": { + "cache": 0 + }, + "CreateIndex": 53, + "ModifyIndex": 55 + } +] +``` + +## Read Evaluation + +This endpoint reads information about a specific evaluation by ID. + +| Method | Path | Produces | +| ------ | ------------------------- | -------------------------- | +| `GET` | `/v1/evaluation/:eval_id` | `application/json` | + +The table below shows this endpoint's support for +[blocking queries](/api/index.html#blocking-queries) and +[required ACLs](/api/index.html#acls). + +| Blocking Queries | ACL Required | +| ---------------- | ------------ | +| `YES` | `none` | + +### Parameters + +- `:eval_id` `(string: )`- Specifies the UUID of the evaluation. This + must be the full UUID, not the short 8-character one. This is specified as + part of the path. + +### Sample Request + +```text +$ curl \ + https://nomad.rocks/v1/evaluation/5456bd7a-9fc0-c0dd-6131-cbee77f57577 +``` + +### Sample Response + +```json +{ + "ID": "5456bd7a-9fc0-c0dd-6131-cbee77f57577", + "Priority": 50, + "Type": "service", + "TriggeredBy": "job-register", + "JobID": "example", + "JobModifyIndex": 52, + "NodeID": "", + "NodeModifyIndex": 0, + "Status": "complete", + "StatusDescription": "", + "Wait": 0, + "NextEval": "", + "PreviousEval": "", + "BlockedEval": "", + "FailedTGAllocs": null, + "ClassEligibility": null, + "EscapedComputedClass": false, + "AnnotatePlan": false, + "SnapshotIndex": 53, + "QueuedAllocations": { + "cache": 0 + }, + "CreateIndex": 53, + "ModifyIndex": 55 +} +``` + +## List Allocations for Evaluation + +This endpoint lists the allocations created or modified for the given +evaluation. + +| Method | Path | Produces | +| ------ | ------------------------------------- | -------------------------- | +| `GET` | `/v1/evaluation/:eval_id/allocations` | `application/json` | + +The table below shows this endpoint's support for +[blocking queries](/api/index.html#blocking-queries) and +[required ACLs](/api/index.html#acls). + +| Blocking Queries | ACL Required | +| ---------------- | ------------ | +| `YES` | `none` | + +### Parameters + +- `:eval_id` `(string: )`- Specifies the UUID of the evaluation. This + must be the full UUID, not the short 8-character one. This is specified as + part of the path. + +### Sample Request + +```text +$ curl \ + https://nomad.rocks/v1/evaluation/5456bd7a-9fc0-c0dd-6131-cbee77f57577/allocations +``` + +### Sample Response + +```json +[ + { + "ID": "a8198d79-cfdb-6593-a999-1e9adabcba2e", + "EvalID": "5456bd7a-9fc0-c0dd-6131-cbee77f57577", + "Name": "example.cache[0]", + "NodeID": "fb2170a8-257d-3c64-b14d-bc06cc94e34c", + "JobID": "example", + "TaskGroup": "cache", + "DesiredStatus": "run", + "DesiredDescription": "", + "ClientStatus": "running", + "ClientDescription": "", + "TaskStates": { + "redis": { + "State": "running", + "Failed": false, + "Events": [ + { + "Type": "Received", + "Time": 1495747371795703800, + "FailsTask": false, + "RestartReason": "", + "SetupError": "", + "DriverError": "", + "ExitCode": 0, + "Signal": 0, + "Message": "", + "KillTimeout": 0, + "KillError": "", + "KillReason": "", + "StartDelay": 0, + "DownloadError": "", + "ValidationError": "", + "DiskLimit": 0, + "FailedSibling": "", + "VaultError": "", + "TaskSignalReason": "", + "TaskSignal": "", + "DriverMessage": "" + }, + { + "Type": "Driver", + "Time": 1495747371798867200, + "FailsTask": false, + "RestartReason": "", + "SetupError": "", + "DriverError": "", + "ExitCode": 0, + "Signal": 0, + "Message": "", + "KillTimeout": 0, + "KillError": "", + "KillReason": "", + "StartDelay": 0, + "DownloadError": "", + "ValidationError": "", + "DiskLimit": 0, + "FailedSibling": "", + "VaultError": "", + "TaskSignalReason": "", + "TaskSignal": "", + "DriverMessage": "Downloading image redis:3.2" + }, + { + "Type": "Started", + "Time": 1495747379525667800, + "FailsTask": false, + "RestartReason": "", + "SetupError": "", + "DriverError": "", + "ExitCode": 0, + "Signal": 0, + "Message": "", + "KillTimeout": 0, + "KillError": "", + "KillReason": "", + "StartDelay": 0, + "DownloadError": "", + "ValidationError": "", + "DiskLimit": 0, + "FailedSibling": "", + "VaultError": "", + "TaskSignalReason": "", + "TaskSignal": "", + "DriverMessage": "" + } + ] + } + }, + "CreateIndex": 54, + "ModifyIndex": 57, + "CreateTime": 1495747371794276400 + } +] +``` diff --git a/website/source/api/index.html.md b/website/source/api/index.html.md new file mode 100644 index 000000000..c2e3fabd1 --- /dev/null +++ b/website/source/api/index.html.md @@ -0,0 +1,186 @@ +--- +layout: api +page_title: HTTP API +sidebar_current: api-overview +description: |- + Nomad exposes a RESTful HTTP API to control almost every aspect of the + Nomad agent. +--- + +# HTTP API + +The main interface to Nomad is a RESTful HTTP API. The API can query the current +state of the system as well as modify the state of the system. The Nomad CLI +actually invokes Nomad's HTTP for many commands. + +## Version Prefix + +All API routes are prefixed with `/v1/`. + +This documentation is only for the v1 API. + +~> **Backwards compatibility:** At the current version, Nomad does not yet +promise backwards compatibility even with the v1 prefix. We'll remove this +warning when this policy changes. We expect to reach API stability by Nomad +1.0. + +## Addressing & Ports + +Nomad binds to a specific set of addresses and ports. The HTTP API is served via +the `http` address and port. This `address:port` must be accessible locally. If +you bind to `127.0.0.1:4646`, the API is only available _from that host_. If you +bind to a private internal IP, the API will be available from within that +network. If you bind to a public IP, the API will be available from the public +Internet (not recommended). + +The default port for the Nomad HTTP API is `4646`. This can be overridden via +the Nomad configuration block. Here is an example curl request to query a Nomad +server with the default configuration: + +```text +$ curl http://127.0.0.1:4646/v1/agent/members +``` + +The conventions used in the API documentation do not list a port and use the +standard URL `nomad.rocks`. Be sure to replace this with your Nomad agent URL +when using the examples. + +## Data Model and Layout + +There are four primary nouns in Nomad: + +- jobs +- nodes +- allocations +- 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. + +## ACLs + +The Nomad API does not support ACLs at this time. + +## Authentication + +The Nomad API does not support authentication at this time. + +## Blocking Queries + +Many endpoints in Nomad support a feature known as "blocking queries". A +blocking query is used to wait for a potential change using long polling. Not +all endpoints support blocking, but each endpoint uniquely documents its support +for blocking queries in the documentation. + +Endpoints that support blocking queries return an HTTP header named +`X-Nomad-Index`. This is 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. + +When this is provided, the HTTP request will "hang" until a change in the system +occurs, or the maximum timeout is reached. 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. + +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 small random amount of additional wait time is added +to the supplied maximum `wait` time to spread out the wake up time of any +concurrent requests. This adds up to `wait / 16` additional time to the maximum +duration. + +## 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 requests. + +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 will default to the region on which the +machine is servicing the request. If the agent runs in "region1", the request +will query the region "region1". A target region can be explicitly request using +the `?region` query parameter. The request will be transparently forwarded and +serviced by a server in the requested region. + +## Compressed Responses + +The HTTP API will gzip the response if the HTTP request denotes that the client +accepts gzip compression. This is achieved by passing the accept encoding: + +``` +$ curl \ + --header "Accept-Encoding: gzip" \ + https://nomad.rocks/v1/... +``` + +## 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. + +In general, clients should prefer a client-side parser like `jq` instead of +server-formatted data. Asking the server to format the data takes away +processing cycles from more important tasks. + +``` +$ curl https://nomad.rocks/v1/page?pretty +``` + +## HTTP Methods + +Nomad's API aims to be RESTful, although there are some exceptions. The API +responds to the standard HTTP verbs GET, PUT, and DELETE. Each API method will +clearly document the verb(s) it responds to and the generated response. The same +path with different verbs may trigger different behavior. For example: + +```text +PUT /v1/jobs +GET /v1/jobs +``` + +Even though these share a path, the `PUT` operation creates a new job whereas +the `GET` operation reads all jobs. diff --git a/website/source/api/jobs.html.md b/website/source/api/jobs.html.md new file mode 100644 index 000000000..7d4af5be5 --- /dev/null +++ b/website/source/api/jobs.html.md @@ -0,0 +1,1236 @@ +--- +layout: api +page_title: Jobs - HTTP API +sidebar_current: api-jobs +description: |- + The /jobs endpoints are used to query for and interact with jobs. +--- + +# Jobs HTTP API + +The `/jobs` endpoints are used to query for and interact with jobs. + +## List Jobs + +This endpoint lists all known jobs in the system registered with Nomad. + +| Method | Path | Produces | +| ------ | ------------------------- | -------------------------- | +| `GET` | `/v1/jobs` | `application/json` | + +The table below shows this endpoint's support for +[blocking queries](/api/index.html#blocking-queries) and +[required ACLs](/api/index.html#acls). + +| Blocking Queries | ACL Required | +| ---------------- | ------------ | +| `YES` | `none` | + +### Parameters + +- `prefix` `(string: "")`- Specifies a string to filter jobs on based on + an index prefix. This is specified as a querystring parameter. + +### Sample Request + +```text +$ curl \ + https://nomad.rocks/v1/jobs +``` + +```text +$ curl \ + https://nomad.rocks/v1/jobs?prefix=team +``` + +### Sample Response + +```json +[ + { + "ID": "example", + "ParentID": "", + "Name": "example", + "Type": "service", + "Priority": 50, + "Status": "pending", + "StatusDescription": "", + "JobSummary": { + "JobID": "example", + "Summary": { + "cache": { + "Queued": 1, + "Complete": 1, + "Failed": 0, + "Running": 0, + "Starting": 0, + "Lost": 0 + } + }, + "Children": { + "Pending": 0, + "Running": 0, + "Dead": 0 + }, + "CreateIndex": 52, + "ModifyIndex": 96 + }, + "CreateIndex": 52, + "ModifyIndex": 93, + "JobModifyIndex": 52 + } +] +``` + +## Create Job + +This endpoint creates (aka "registers") a new job in the system. + +| Method | Path | Produces | +| ------- | ------------------------- | -------------------------- | +| `POST` | `/v1/jobs` | `application/json` | + +The table below shows this endpoint's support for +[blocking queries](/api/index.html#blocking-queries) and +[required ACLs](/api/index.html#acls). + +| Blocking Queries | ACL Required | +| ---------------- | ------------ | +| `NO` | `none` | + +### Parameters + +There are no parameters, but the request _body_ contains the entire job file. + +### Sample Payload + +```text +(any valid nomad job IN JSON FORMAT) +``` + +### Sample Request + +```text +$ curl \ + --request POST \ + --data @my-job.nomad \ + https://nomad.rocks/v1/jobs +``` + +### Sample Response + +```json +{ + "EvalID": "", + "EvalCreateIndex": 0, + "JobModifyIndex": 109, + "Index": 0, + "LastContact": 0, + "KnownLeader": false +} +``` + +## Read Job + +This endpoint reads information about a single job for its specification and +status. + +| Method | Path | Produces | +| ------ | ------------------------- | -------------------------- | +| `GET` | `/v1/job/:job_id` | `application/json` | + +The table below shows this endpoint's support for +[blocking queries](/api/index.html#blocking-queries) and +[required ACLs](/api/index.html#acls). + +| Blocking Queries | ACL Required | +| ---------------- | ------------ | +| `YES` | `none` | + +### Parameters + +- `:job_id` `(string: )`- Specifies the ID of the job (as specified in + the job file during submission). This is specified as part of the path. + +### Sample Request + +```text +$ curl \ + https://nomad.rocks/v1/job/my-job +``` + +### Sample Response + +```json +{ + "Region": "global", + "ID": "example", + "ParentID": "", + "Name": "example", + "Type": "batch", + "Priority": 50, + "AllAtOnce": false, + "Datacenters": [ + "dc1" + ], + "Constraints": [ + { + "LTarget": "${attr.kernel.name}", + "RTarget": "linux", + "Operand": "=" + } + ], + "TaskGroups": [ + { + "Name": "cache", + "Count": 1, + "Constraints": [ + { + "LTarget": "${attr.os.signals}", + "RTarget": "SIGUSR1", + "Operand": "set_contains" + } + ], + "RestartPolicy": { + "Attempts": 10, + "Interval": 300000000000, + "Delay": 25000000000, + "Mode": "delay" + }, + "Tasks": [ + { + "Name": "redis", + "Driver": "docker", + "User": "foo-user", + "Config": { + "image": "redis:latest", + "port_map": [ + { + "db": 6379 + } + ] + }, + "Env": { + "foo": "bar", + "baz": "pipe" + }, + "Services": [ + { + "Name": "cache-redis", + "PortLabel": "db", + "Tags": [ + "global", + "cache" + ], + "Checks": [ + { + "Name": "alive", + "Type": "tcp", + "Command": "", + "Args": null, + "Path": "", + "Protocol": "", + "PortLabel": "", + "Interval": 10000000000, + "Timeout": 2000000000, + "InitialStatus": "" + } + ] + } + ], + "Vault": null, + "Templates": [ + { + "SourcePath": "local/config.conf.tpl", + "DestPath": "local/config.conf", + "EmbeddedTmpl": "", + "ChangeMode": "signal", + "ChangeSignal": "SIGUSR1", + "Splay": 5000000000, + "Perms": "" + } + ], + "Constraints": null, + "Resources": { + "CPU": 500, + "MemoryMB": 256, + "DiskMB": 0, + "IOPS": 0, + "Networks": [ + { + "Device": "", + "CIDR": "", + "IP": "", + "MBits": 10, + "ReservedPorts": [ + { + "Label": "rpc", + "Value": 25566 + } + ], + "DynamicPorts": [ + { + "Label": "db", + "Value": 0 + } + ] + } + ] + }, + "DispatchPayload": { + "File": "config.json" + }, + "Meta": { + "foo": "bar", + "baz": "pipe" + }, + "KillTimeout": 5000000000, + "LogConfig": { + "MaxFiles": 10, + "MaxFileSizeMB": 10 + }, + "Artifacts": [ + { + "GetterSource": "http://foo.com/artifact.tar.gz", + "GetterOptions": { + "checksum": "md5:c4aa853ad2215426eb7d70a21922e794" + }, + "RelativeDest": "local/" + } + ], + "Leader": false + } + ], + "EphemeralDisk": { + "Sticky": false, + "SizeMB": 300, + "Migrate": false + }, + "Meta": { + "foo": "bar", + "baz": "pipe" + } + } + ], + "Update": { + "Stagger": 10000000000, + "MaxParallel": 1 + }, + "Periodic": { + "Enabled": true, + "Spec": "* * * * *", + "SpecType": "cron", + "ProhibitOverlap": true + }, + "ParameterizedJob": { + "Payload": "required", + "MetaRequired": [ + "foo" + ], + "MetaOptional": [ + "bar" + ] + }, + "Payload": null, + "Meta": { + "foo": "bar", + "baz": "pipe" + }, + "VaultToken": "", + "Status": "running", + "StatusDescription": "", + "CreateIndex": 7, + "ModifyIndex": 7, + "JobModifyIndex": 7 +} +``` + +## List Job Versions + +This endpoint reads information about all versions of a job. + +| Method | Path | Produces | +| ------ | -------------------------- | -------------------------- | +| `GET` | `/v1/job/:job_id/versions` | `application/json` | + +The table below shows this endpoint's support for +[blocking queries](/api/index.html#blocking-queries) and +[required ACLs](/api/index.html#acls). + +| Blocking Queries | ACL Required | +| ---------------- | ------------ | +| `YES` | `none` | + +### Parameters + +- `:job_id` `(string: )`- Specifies the ID of the job (as specified in + the job file during submission). This is specified as part of the path. + +### Sample Request + +```text +$ curl \ + https://nomad.rocks/v1/job/my-job/versions +``` + +### Sample Response + +```json +[ + { + "Stop": false, + "Region": "global", + "ID": "example", + "ParentID": "", + "Name": "example", + "Type": "service", + "Priority": 50, + "AllAtOnce": false, + "Datacenters": [ + "dc1" + ], + "Constraints": null, + "TaskGroups": [ + { + "Name": "cache", + "Count": 1, + "Update": { + "Stagger": 0, + "MaxParallel": 1, + "HealthCheck": "checks", + "MinHealthyTime": 10000000000, + "HealthyDeadline": 300000000000, + "AutoRevert": false, + "Canary": 0 + }, + "Constraints": null, + "RestartPolicy": { + "Attempts": 10, + "Interval": 300000000000, + "Delay": 25000000000, + "Mode": "delay" + }, + "Tasks": [ + { + "Name": "redis", + "Driver": "docker", + "User": "", + "Config": { + "image": "redis:3.2", + "port_map": [ + { + "db": 6379 + } + ] + }, + "Env": null, + "Services": [ + { + "Name": "global-redis-check", + "PortLabel": "db", + "Tags": [ + "global", + "cache" + ], + "Checks": [ + { + "Name": "alive", + "Type": "tcp", + "Command": "", + "Args": null, + "Path": "", + "Protocol": "", + "PortLabel": "", + "Interval": 10000000000, + "Timeout": 2000000000, + "InitialStatus": "", + "TLSSkipVerify": false + } + ] + } + ], + "Vault": null, + "Templates": null, + "Constraints": null, + "Resources": { + "CPU": 500, + "MemoryMB": 256, + "DiskMB": 0, + "IOPS": 0, + "Networks": [ + { + "Device": "", + "CIDR": "", + "IP": "", + "MBits": 10, + "ReservedPorts": null, + "DynamicPorts": [ + { + "Label": "db", + "Value": 0 + } + ] + } + ] + }, + "DispatchPayload": null, + "Meta": null, + "KillTimeout": 5000000000, + "LogConfig": { + "MaxFiles": 10, + "MaxFileSizeMB": 10 + }, + "Artifacts": null, + "Leader": false + } + ], + "EphemeralDisk": { + "Sticky": false, + "SizeMB": 300, + "Migrate": false + }, + "Meta": null + } + ], + "Update": { + "Stagger": 10000000000, + "MaxParallel": 1, + "HealthCheck": "", + "MinHealthyTime": 0, + "HealthyDeadline": 0, + "AutoRevert": false, + "Canary": 0 + }, + "Periodic": null, + "ParameterizedJob": null, + "Payload": null, + "Meta": null, + "VaultToken": "", + "Status": "pending", + "StatusDescription": "", + "Stable": false, + "Version": 0, + "CreateIndex": 7, + "ModifyIndex": 7, + "JobModifyIndex": 7 + } +] +``` + +## List Job Allocations + +This endpoint reads information about a single job's allocations. + +| Method | Path | Produces | +| ------ | ----------------------------- | -------------------------- | +| `GET` | `/v1/job/:job_id/allocations` | `application/json` | + +The table below shows this endpoint's support for +[blocking queries](/api/index.html#blocking-queries) and +[required ACLs](/api/index.html#acls). + +| Blocking Queries | ACL Required | +| ---------------- | ------------ | +| `YES` | `none` | + +### Parameters + +- `:job_id` `(string: )`- Specifies the ID of the job (as specified in + the job file during submission). This is specified as part of the path. + +### Sample Request + +```text +$ curl \ + https://nomad.rocks/v1/job/my-job/allocations +``` + +### Sample Response + +```json +[ + { + "ID": "ed344e0a-7290-d117-41d3-a64f853ca3c2", + "EvalID": "a9c5effc-2242-51b2-f1fe-054ee11ab189", + "Name": "example.cache[0]", + "NodeID": "cb1f6030-a220-4f92-57dc-7baaabdc3823", + "JobID": "example", + "TaskGroup": "cache", + "DesiredStatus": "run", + "DesiredDescription": "", + "ClientStatus": "running", + "ClientDescription": "", + "TaskStates": { + "redis": { + "State": "running", + "Failed": false, + "StartedAt": "2017-05-25T23:41:23.240184101Z", + "FinishedAt": "0001-01-01T00:00:00Z", + "Events": [ + { + "Type": "Received", + "Time": 1495755675956923000, + "FailsTask": false, + "RestartReason": "", + "SetupError": "", + "DriverError": "", + "ExitCode": 0, + "Signal": 0, + "Message": "", + "KillTimeout": 0, + "KillError": "", + "KillReason": "", + "StartDelay": 0, + "DownloadError": "", + "ValidationError": "", + "DiskLimit": 0, + "FailedSibling": "", + "VaultError": "", + "TaskSignalReason": "", + "TaskSignal": "", + "DriverMessage": "" + }, + { + "Type": "Task Setup", + "Time": 1495755675957466400, + "FailsTask": false, + "RestartReason": "", + "SetupError": "", + "DriverError": "", + "ExitCode": 0, + "Signal": 0, + "Message": "Building Task Directory", + "KillTimeout": 0, + "KillError": "", + "KillReason": "", + "StartDelay": 0, + "DownloadError": "", + "ValidationError": "", + "DiskLimit": 0, + "FailedSibling": "", + "VaultError": "", + "TaskSignalReason": "", + "TaskSignal": "", + "DriverMessage": "" + }, + { + "Type": "Driver", + "Time": 1495755675970286800, + "FailsTask": false, + "RestartReason": "", + "SetupError": "", + "DriverError": "", + "ExitCode": 0, + "Signal": 0, + "Message": "", + "KillTimeout": 0, + "KillError": "", + "KillReason": "", + "StartDelay": 0, + "DownloadError": "", + "ValidationError": "", + "DiskLimit": 0, + "FailedSibling": "", + "VaultError": "", + "TaskSignalReason": "", + "TaskSignal": "", + "DriverMessage": "Downloading image redis:3.2" + }, + { + "Type": "Started", + "Time": 1495755683227522000, + "FailsTask": false, + "RestartReason": "", + "SetupError": "", + "DriverError": "", + "ExitCode": 0, + "Signal": 0, + "Message": "", + "KillTimeout": 0, + "KillError": "", + "KillReason": "", + "StartDelay": 0, + "DownloadError": "", + "ValidationError": "", + "DiskLimit": 0, + "FailedSibling": "", + "VaultError": "", + "TaskSignalReason": "", + "TaskSignal": "", + "DriverMessage": "" + } + ] + } + }, + "CreateIndex": 9, + "ModifyIndex": 13, + "CreateTime": 1495755675944527600 + } +] +``` + +## List Job Evaluations + +This endpoint reads information about a single job's evaluations + +| Method | Path | Produces | +| ------ | ----------------------------- | -------------------------- | +| `GET` | `/v1/job/:job_id/evaluations` | `application/json` | + +The table below shows this endpoint's support for +[blocking queries](/api/index.html#blocking-queries) and +[required ACLs](/api/index.html#acls). + +| Blocking Queries | ACL Required | +| ---------------- | ------------ | +| `YES` | `none` | + +### Parameters + +- `:job_id` `(string: )`- Specifies the ID of the job (as specified in + the job file during submission). This is specified as part of the path. + +### Sample Request + +```text +$ curl \ + https://nomad.rocks/v1/job/my-job/evaluations +``` + +### Sample Response + +```json +[ + { + "ID": "a9c5effc-2242-51b2-f1fe-054ee11ab189", + "Priority": 50, + "Type": "service", + "TriggeredBy": "job-register", + "JobID": "example", + "JobModifyIndex": 7, + "NodeID": "", + "NodeModifyIndex": 0, + "Status": "complete", + "StatusDescription": "", + "Wait": 0, + "NextEval": "", + "PreviousEval": "", + "BlockedEval": "", + "FailedTGAllocs": null, + "ClassEligibility": null, + "EscapedComputedClass": false, + "AnnotatePlan": false, + "QueuedAllocations": { + "cache": 0 + }, + "SnapshotIndex": 8, + "CreateIndex": 8, + "ModifyIndex": 10 + } +] +``` + +## Read Job Summary + +This endpoint reads summary information about a job. + +| Method | Path | Produces | +| ------ | -------------------------- | -------------------------- | +| `GET` | `/v1/job/:job_id/summary` | `application/json` | + +The table below shows this endpoint's support for +[blocking queries](/api/index.html#blocking-queries) and +[required ACLs](/api/index.html#acls). + +| Blocking Queries | ACL Required | +| ---------------- | ------------ | +| `YES` | `none` | + +### Parameters + +- `:job_id` `(string: )`- Specifies the ID of the job (as specified in + the job file during submission). This is specified as part of the path. + +### Sample Request + +```text +$ curl \ + https://nomad.rocks/v1/job/my-job/summary +``` + +### Sample Response + +```json +{ + "JobID": "example", + "Summary": { + "cache": { + "Queued": 0, + "Complete": 0, + "Failed": 0, + "Running": 1, + "Starting": 0, + "Lost": 0 + } + }, + "Children": { + "Pending": 0, + "Running": 0, + "Dead": 0 + }, + "CreateIndex": 7, + "ModifyIndex": 13 +} +``` + +## Update Existing Job + +This endpoint registers a new job or updates an existing job. + +| Method | Path | Produces | +| ------- | -------------------------- | -------------------------- | +| `POST` | `/v1/job/:job_id` | `application/json` | + +The table below shows this endpoint's support for +[blocking queries](/api/index.html#blocking-queries) and +[required ACLs](/api/index.html#acls). + +| Blocking Queries | ACL Required | +| ---------------- | ------------ | +| `NO` | `none` | + +### Parameters + +- `:job_id` `(string: )`- Specifies the ID of the job (as specified in + the job file during submission). This is specified as part of the path. + +- `Job` `(Job: )` - Specifies the JSON definition of the job. + +- `EnforceIndex` `(int: 0)` - If set, the job will only be registered if the + passed `JobModifyIndex` matches the current job's index. If the index is zero, + the register only occurs if the job is new. This paradigm allows check-and-set + style job updating. + +- `JobModifyIndex` `(int: 0)` - Specifies the `JobModifyIndex` to enforce the + current job is at. + +### Sample Payload + +```javascript +{ + "Job": { + // ... + }, + "EnforceIndex": 1, + "JobModifyIndex": 4 +} +``` + +### Sample Request + +```text +$ curl \ + --request POST \ + --data @payload.json \ + https://nomad.rocks/v1/job/my-job +``` + +### Sample Response + +```json +{ + "EvalID": "d092fdc0-e1fd-2536-67d8-43af8ca798ac", + "EvalCreateIndex": 35, + "JobModifyIndex": 34, +} +``` + +## Dispatch Job + +This endpoint dispatches a new instance of a parameterized job. + +| Method | Path | Produces | +| ------- | -------------------------- | -------------------------- | +| `POST` | `/v1/job/:job_id/dispatch` | `application/json` | + +The table below shows this endpoint's support for +[blocking queries](/api/index.html#blocking-queries) and +[required ACLs](/api/index.html#acls). + +| Blocking Queries | ACL Required | +| ---------------- | ------------ | +| `NO` | `none` | + +### Parameters + +- `:job_id` `(string: )`- Specifies the ID of the job (as specified in + the job file during submission). This is specified as part of the path. + +- `Payload` `(string: "")` - Specifies a base64 encoded string containing the + payload. This is limited to 15 KB. + +- `Meta` `(meta: nil)` - Specifies arbitrary metadata to pass to + the job. + +### Sample Payload + +```json +{ + "Payload": "A28C3==", + "Meta": { + "key": "Value" + } +} +``` + +### Sample Request + +```text +$ curl \ + https://nomad.rocks/v1/job/my-job/summary +``` + +### Sample Response + +```json +{ + "Index": 13, + "JobCreateIndex": 12, + "EvalCreateIndex": 13, + "EvalID": "e5f55fac-bc69-119d-528a-1fc7ade5e02c", + "DispatchedJobID": "example/dispatch-1485408778-81644024" +} +``` + + +## Create Job Evaluation + +This endpoint creates a new evaluation for the given job. This can be used to +force run the scheduling logic if necessary. + +| Method | Path | Produces | +| ------- | -------------------------- | -------------------------- | +| `POST` | `/v1/job/:job_id/evaluate` | `application/json` | + +The table below shows this endpoint's support for +[blocking queries](/api/index.html#blocking-queries) and +[required ACLs](/api/index.html#acls). + +| Blocking Queries | ACL Required | +| ---------------- | ------------ | +| `NO` | `none` | + +### Parameters + +- `:job_id` `(string: )`- Specifies the ID of the job (as specified in + the job file during submission). This is specified as part of the path. + +### Sample Request + +```text +$ curl \ + --request POST \ + https://nomad.rocks/v1/job/my-job/evaluate +``` + +### Sample Response + +```json +{ + "EvalID": "d092fdc0-e1fd-2536-67d8-43af8ca798ac", + "EvalCreateIndex": 35, + "JobModifyIndex": 34, +} +``` + +## Create Job Plan + +This endpoint invokes a dry-run of the scheduler for the job. + +| Method | Path | Produces | +| ------- | -------------------------- | -------------------------- | +| `POST` | `/v1/job/:job_id/plan` | `application/json` | + +The table below shows this endpoint's support for +[blocking queries](/api/index.html#blocking-queries) and +[required ACLs](/api/index.html#acls). + +| Blocking Queries | ACL Required | +| ---------------- | ------------ | +| `NO` | `none` | + +### Parameters + +- `:job_id` `(string: )`- Specifies the ID of the job (as specified in +- the job file during submission). This is specified as part of the path. + +- `Job` `(string: )` - Specifies the JSON definition of the job. + +- `Diff` `(bool: false)` - Specifies whether the diff structure between the + submitted and server side version of the job should be included in the + response. + +### Sample Payload + +```json +{ + "Job": "...", + "Diff": true +} +``` + +### Sample Request + +```text +$ curl \ + --request POST \ + --payload @payload.json \ + https://nomad.rocks/v1/job/my-job/plan +``` + +### Sample Response + +```json +{ + "Index": 0, + "NextPeriodicLaunch": "0001-01-01T00:00:00Z", + "Diff": { + "Type": "Added", + "TaskGroups": [ + { + "Updates": { + "create": 1 + }, + "Type": "Added", + "Tasks": [ + { + "Type": "Added", + "Objects": [ + "..." + ], + "Name": "redis", + "Fields": [ + { + "Type": "Added", + "Old": "", + "New": "docker", + "Name": "Driver", + "Annotations": null + }, + { + "Type": "Added", + "Old": "", + "New": "5000000000", + "Name": "KillTimeout", + "Annotations": null + } + ], + "Annotations": [ + "forces create" + ] + } + ], + "Objects": [ + "..." + ], + "Name": "cache", + "Fields": [ + "..." + ] + } + ], + "Objects": [ + { + "Type": "Added", + "Objects": null, + "Name": "Datacenters", + "Fields": [ + "..." + ] + }, + { + "Type": "Added", + "Objects": null, + "Name": "Constraint", + "Fields": [ + "..." + ] + }, + { + "Type": "Added", + "Objects": null, + "Name": "Update", + "Fields": [ + "..." + ] + } + ], + "ID": "example", + "Fields": [ + "..." + ] + }, + "CreatedEvals": [ + { + "ModifyIndex": 0, + "CreateIndex": 0, + "SnapshotIndex": 0, + "AnnotatePlan": false, + "EscapedComputedClass": false, + "NodeModifyIndex": 0, + "NodeID": "", + "JobModifyIndex": 0, + "JobID": "example", + "TriggeredBy": "job-register", + "Type": "batch", + "Priority": 50, + "ID": "312e6a6d-8d01-0daf-9105-14919a66dba3", + "Status": "blocked", + "StatusDescription": "created to place remaining allocations", + "Wait": 0, + "NextEval": "", + "PreviousEval": "80318ae4-7eda-e570-e59d-bc11df134817", + "BlockedEval": "", + "FailedTGAllocs": null, + "ClassEligibility": { + "v1:7968290453076422024": true + } + } + ], + "JobModifyIndex": 0, + "FailedTGAllocs": { + "cache": { + "CoalescedFailures": 3, + "AllocationTime": 46415, + "Scores": null, + "NodesEvaluated": 1, + "NodesFiltered": 0, + "NodesAvailable": { + "dc1": 1 + }, + "ClassFiltered": null, + "ConstraintFiltered": null, + "NodesExhausted": 1, + "ClassExhausted": null, + "DimensionExhausted": { + "cpu exhausted": 1 + } + } + }, + "Annotations": { + "DesiredTGUpdates": { + "cache": { + "DestructiveUpdate": 0, + "InPlaceUpdate": 0, + "Stop": 0, + "Migrate": 0, + "Place": 11, + "Ignore": 0 + } + } + } +} +``` + +#### Field Reference + +- `Diff` - A diff structure between the submitted job and the server side + version. The top-level object is a Job Diff which contains Task Group Diffs, + which in turn contain Task Diffs. Each of these objects then has Object and + Field Diff structures embedded. + +- `NextPeriodicLaunch`- If the job being planned is periodic, this field will + include the next launch time for the job. + +- `CreatedEvals` - A set of evaluations that were created as a result of the + dry-run. These evaluations can signify a follow-up rolling update evaluation + or a blocked evaluation. + +- `JobModifyIndex`- The `JobModifyIndex` of the server side version of this job. + +- `FailedTGAllocs` - A set of metrics to understand any allocation failures that + occurred for the Task Group. + +- `Annotations` - Annotations include the `DesiredTGUpdates`, which tracks what +- the scheduler would do given enough resources for each Task Group. + + +## Force New Periodic Instance + +This endpoint forces a new instance of the periodic job. A new instance will be +created even if it violates the job's +[`prohibit_overlap`](/docs/job-specification/periodic.html#prohibit_overlap) +settings. As such, this should be only used to immediately run a periodic job. + +| Method | Path | Produces | +| ------- | -------------------------------- | -------------------------- | +| `POST` | `/v1/job/:job_id/periodic/force` | `application/json` | + +The table below shows this endpoint's support for +[blocking queries](/api/index.html#blocking-queries) and +[required ACLs](/api/index.html#acls). + +| Blocking Queries | ACL Required | +| ---------------- | ------------ | +| `NO` | `none` | + +### Parameters + +- `:job_id` `(string: )`- Specifies the ID of the job (as specified in + the job file during submission). This is specified as part of the path. + +### Sample Request + +```text +$ curl \ + --request POST \ + https://nomad.rocks/v1/job/my-job/periodic/force +``` + +### Sample Response + +```json +{ + "EvalCreateIndex": 7, + "EvalID": "57983ddd-7fcf-3e3a-fd24-f699ccfb36f4" +} +``` + +## Delete a Job + +This endpoint deregisters a job, and stops all allocations part of it. + +| Method | Path | Produces | +| -------- | -------------------------- | -------------------------- | +| `DELETE` | `/v1/job/:job_id` | `application/json` | + +The table below shows this endpoint's support for +[blocking queries](/api/index.html#blocking-queries) and +[required ACLs](/api/index.html#acls). + +| Blocking Queries | ACL Required | +| ---------------- | ------------ | +| `NO` | `none` | + +### Parameters + +- `:job_id` `(string: )`- Specifies the ID of the job (as specified in + the job file during submission). This is specified as part of the path. + +### Sample Request + +```text +$ curl \ + --request DELETE \ + https://nomad.rocks/v1/job/my-job +``` + +### Sample Response + +```json +{ + "EvalID": "d092fdc0-e1fd-2536-67d8-43af8ca798ac", + "EvalCreateIndex": 35, + "JobModifyIndex": 34, +} +``` diff --git a/website/source/docs/http/json-jobs.html.md b/website/source/api/json-jobs.html.md similarity index 67% rename from website/source/docs/http/json-jobs.html.md rename to website/source/api/json-jobs.html.md index 69c8f34ee..d8c4098d8 100644 --- a/website/source/docs/http/json-jobs.html.md +++ b/website/source/api/json-jobs.html.md @@ -1,124 +1,129 @@ --- -layout: "http" -page_title: "HTTP API: JSON Job Specification" -sidebar_current: "docs-http-json-jobs" +layout: api +page_title: JSON Job Specification - HTTP API +sidebar_current: api-jobs description: |- Jobs can also be specified via the HTTP API using a JSON format. This guide discusses the job specification in JSON format. --- -# Job Specification +# JSON Job Specification This guide covers the JSON syntax for submitting jobs to Nomad. A useful command -for generating valid JSON versions of HCL jobs is -`nomad run -output ` which will emit a JSON version of the job. +for generating valid JSON versions of HCL jobs is: -## JSON Syntax +```shell +$ nomad run -output my-job.nomad +``` + +## Syntax Below is an example of a JSON object that submits a `periodic` job to Nomad: ```json { - "Job":{ - "Region":"global", - "ID":"example", - "Name":"example", - "Type":"batch", - "Priority":50, - "AllAtOnce":false, - "Datacenters":[ + "Job": { + "Region": "global", + "ID": "example", + "Name": "example", + "Type": "batch", + "Priority": 50, + "AllAtOnce": false, + "Datacenters": [ "dc1" ], - "Constraints":[ + "Constraints": [ { - "LTarget":"${attr.kernel.name}", - "RTarget":"linux", - "Operand":"=" + "LTarget": "${attr.kernel.name}", + "RTarget": "linux", + "Operand": "=" } ], - "TaskGroups":[ + "TaskGroups": [ { - "Name":"cache", - "Count":1, - "Constraints":null, - "Tasks":[ + "Name": "cache", + "Count": 1, + "Constraints": null, + "Tasks": [ { - "Name":"redis", - "Driver":"docker", - "User":"foo-user", - "Config":{ - "image":"redis:latest", - "port_map":[ + "Name": "redis", + "Driver": "docker", + "User": "foo-user", + "Config": { + "image": "redis:latest", + "port_map": [ { - "db":6379 + "db": 6379 } ] }, - "Constraints":null, - "Env":{ - "foo":"bar", - "baz":"pipe" + "Constraints": null, + "Env": { + "foo": "bar", + "baz": "pipe" }, - "Services":[ + "Services": [ { - "Name":"cache-redis", - "Tags":[ + "Name": "cache-redis", + "Tags": [ "global", "cache" ], - "PortLabel":"db", - "Checks":[ + "PortLabel": "db", + "Checks": [ { - "Id":"", - "Name":"alive", - "Type":"tcp", - "Command":"", - "Args":null, - "Path":"", - "Protocol":"", - "Interval":10000000000, - "Timeout":2000000000 + "Id": "", + "Name": "alive", + "Type": "tcp", + "Command": "", + "Args": null, + "Path": "", + "Protocol": "", + "Interval": 10000000000, + "Timeout": 2000000000 } ] } ], "Vault": { - "Policies": ["policy-name"], + "Policies": [ + "policy-name" + ], "Env": true, "ChangeMode": "restart", "ChangeSignal": "" }, - "Resources":{ - "CPU":500, - "MemoryMB":256, - "IOPS":0, - "Networks":[ + "Resources": { + "CPU": 500, + "MemoryMB": 256, + "IOPS": 0, + "Networks": [ { - "ReservedPorts":[ + "ReservedPorts": [ { - "Label":"rpc", - "Value":25566 + "Label": "rpc", + "Value": 25566 } ], - "DynamicPorts":[ + "DynamicPorts": [ { - "Label":"db" + "Label": "db" } ], - "MBits":10 + "MBits": 10 } ] }, - "Meta":{ - "foo":"bar", - "baz":"pipe" + "Meta": { + "foo": "bar", + "baz": "pipe" }, - "KillTimeout":5000000000, - "LogConfig":{ - "MaxFiles":10, - "MaxFileSizeMB":10 + "KillTimeout": 5000000000, + "LogConfig": { + "MaxFiles": 10, + "MaxFileSizeMB": 10 }, - "Templates":[ + "Templates": [ { "SourcePath": "local/config.conf.tpl", "DestPath": "local/config.conf", @@ -128,13 +133,13 @@ Below is an example of a JSON object that submits a `periodic` job to Nomad: "Splay": 5000000000 } ], - "Artifacts":[ + "Artifacts": [ { - "GetterSource":"http://foo.com/artifact.tar.gz", - "GetterOptions":{ - "checksum":"md5:c4aa853ad2215426eb7d70a21922e794" + "GetterSource": "http://foo.com/artifact.tar.gz", + "GetterOptions": { + "checksum": "md5:c4aa853ad2215426eb7d70a21922e794" }, - "RelativeDest":"local/" + "RelativeDest": "local/" } ], "DispatchPayload": { @@ -142,31 +147,31 @@ Below is an example of a JSON object that submits a `periodic` job to Nomad: } } ], - "RestartPolicy":{ - "Interval":300000000000, - "Attempts":10, - "Delay":25000000000, - "Mode":"delay" + "RestartPolicy": { + "Interval": 300000000000, + "Attempts": 10, + "Delay": 25000000000, + "Mode": "delay" }, - "Meta":{ - "foo":"bar", - "baz":"pipe" + "Meta": { + "foo": "bar", + "baz": "pipe" } } ], - "Update":{ - "Stagger":10000000000, - "MaxParallel":1 + "Update": { + "Stagger": 10000000000, + "MaxParallel": 1 }, - "Periodic":{ - "Enabled":true, - "Spec":"* * * * *", - "SpecType":"cron", - "ProhibitOverlap":true + "Periodic": { + "Enabled": true, + "Spec": "- *", + "SpecType": "cron", + "ProhibitOverlap": true }, - "Meta":{ - "foo":"bar", - "baz":"pipe" + "Meta": { + "foo": "bar", + "baz": "pipe" }, "ParameterizedJob": { "Payload": "required", @@ -175,7 +180,7 @@ Below is an example of a JSON object that submits a `periodic` job to Nomad: ], "MetaOptional": [ "bar" - ] + ] }, "Payload": null } @@ -184,65 +189,65 @@ Below is an example of a JSON object that submits a `periodic` job to Nomad: ## Syntax Reference -Following is a syntax reference for the possible keys that are supported -and their default values if any for each type of object. +Following is a syntax reference for the possible keys that are supported and +their default values if any for each type of object. ### Job The `Job` object supports the following keys: -* `AllAtOnce` - Controls if the entire set of tasks in the job must +- `AllAtOnce` - Controls if the entire set of tasks in the job must be placed atomically or if they can be scheduled incrementally. This should only be used for special circumstances. Defaults to `false`. -* `Constraints` - A list to define additional constraints where a job can be +- `Constraints` - A list to define additional constraints where a job can be run. See the constraint reference for more details. -* `Datacenters` - A list of datacenters in the region which are eligible +- `Datacenters` - A list of datacenters in the region which are eligible for task placement. This must be provided, and does not have a default. -* `TaskGroups` - A list to define additional task groups. See the task group +- `TaskGroups` - A list to define additional task groups. See the task group reference for more details. -* `Meta` - Annotates the job with opaque metadata. +- `Meta` - Annotates the job with opaque metadata. -* `ParameterizedJob` - Specifies the job as a paramterized job such that it can +- `ParameterizedJob` - Specifies the job as a paramterized job such that it can be dispatched against. The `ParamaterizedJob` object supports the following attributes: - * `MetaOptional` - Specifies the set of metadata keys that may be provided + - `MetaOptional` - Specifies the set of metadata keys that may be provided when dispatching against the job as a string array. - * `MetaRequired` - Specifies the set of metadata keys that must be provided + - `MetaRequired` - Specifies the set of metadata keys that must be provided when dispatching against the job as a string array. - * `Payload` - Specifies the requirement of providing a payload when + - `Payload` - Specifies the requirement of providing a payload when dispatching against the parameterized job. The options for this field are "optional", "required" and "forbidden". The default value is "optional". -* `Payload` - The payload may not be set when submitting a job but may appear in +- `Payload` - The payload may not be set when submitting a job but may appear in a dispatched job. The `Payload` will be a base64 encoded string containing the payload that the job was dispatched with. The `payload` has a **maximum size of 16 KiB**. -* `Priority` - Specifies the job priority which is used to prioritize +- `Priority` - Specifies the job priority which is used to prioritize scheduling and access to resources. Must be between 1 and 100 inclusively, and defaults to 50. -* `Region` - The region to run the job in, defaults to "global". +- `Region` - The region to run the job in, defaults to "global". -* `Type` - Specifies the job type and switches which scheduler +- `Type` - Specifies the job type and switches which scheduler is used. Nomad provides the `service`, `system` and `batch` schedulers, and defaults to `service`. To learn more about each scheduler type visit [here](/docs/runtime/schedulers.html) -* `Update` - Specifies the task's update strategy. When omitted, rolling +- `Update` - Specifies the task's update strategy. When omitted, rolling updates are disabled. The `Update` object supports the following attributes: - * `MaxParallel` - `MaxParallel` is given as an integer value and specifies + - `MaxParallel` - `MaxParallel` is given as an integer value and specifies the number of tasks that can be updated at the same time. - * `Stagger` - `Stagger` introduces a delay between sets of task updates and + - `Stagger` - `Stagger` introduces a delay between sets of task updates and is given in nanoseconds. An example `Update` block: @@ -256,29 +261,29 @@ The `Job` object supports the following keys: } ``` -* `Periodic` - `Periodic` allows the job to be scheduled at fixed times, dates +- `Periodic` - `Periodic` allows the job to be scheduled at fixed times, dates or intervals. The periodic expression is always evaluated in the UTC timezone to ensure consistent evaluation when Nomad Servers span multiple time zones. The `Periodic` object is optional and supports the following attributes: - * `Enabled` - `Enabled` determines whether the periodic job will spawn child + - `Enabled` - `Enabled` determines whether the periodic job will spawn child jobs. - * `time_zone` - Specifies the time zone to evaluate the next launch interval + - `time_zone` - Specifies the time zone to evaluate the next launch interval against. This is useful when wanting to account for day light savings in various time zones. The time zone must be parsable by Golang's [LoadLocation](https://golang.org/pkg/time/#LoadLocation). The default is UTC. - * `SpecType` - `SpecType` determines how Nomad is going to interpret the + - `SpecType` - `SpecType` determines how Nomad is going to interpret the periodic expression. `cron` is the only supported `SpecType` currently. - * `Spec` - A cron expression configuring the interval the job is launched + - `Spec` - A cron expression configuring the interval the job is launched at. Supports predefined expressions such as "@daily" and "@weekly" See [here](https://github.com/gorhill/cronexpr#implementation) for full documentation of supported cron specs and the predefined expressions. - * `ProhibitOverlap` - `ProhibitOverlap` can + - `ProhibitOverlap` - `ProhibitOverlap` can be set to true to enforce that the periodic job doesn't spawn a new instance of the job if any of the previous jobs are still running. It is defaulted to false. @@ -288,7 +293,7 @@ The `Job` object supports the following keys: ```json { "Periodic": { - "Spec": "*/15 * * * * *" + "Spec": "*/15 - *" "SpecType": "cron", "Enabled": true, "ProhibitOverlap": true @@ -301,51 +306,51 @@ The `Job` object supports the following keys: `TaskGroups` is a list of `TaskGroup` objects, each supports the following attributes: -* `Constraints` - This is a list of `Constraint` objects. See the constraint +- `Constraints` - This is a list of `Constraint` objects. See the constraint reference for more details. -* `Count` - Specifies the number of the task groups that should +- `Count` - Specifies the number of the task groups that should be running. Must be non-negative, defaults to one. -* `Meta` - A key-value map that annotates the task group with opaque metadata. +- `Meta` - A key-value map that annotates the task group with opaque metadata. -* `Name` - The name of the task group. Must be specified. +- `Name` - The name of the task group. Must be specified. -* `RestartPolicy` - Specifies the restart policy to be applied to tasks in this group. +- `RestartPolicy` - Specifies the restart policy to be applied to tasks in this group. If omitted, a default policy for batch and non-batch jobs is used based on the job type. See the [restart policy reference](#restart_policy) for more details. -* `EphemeralDisk` - Specifies the group's ephemeral disk requirements. See the +- `EphemeralDisk` - Specifies the group's ephemeral disk requirements. See the [ephemeral disk reference](#ephemeral_disk) for more details. -* `Tasks` - A list of `Task` object that are part of the task group. +- `Tasks` - A list of `Task` object that are part of the task group. ### Task The `Task` object supports the following keys: -* `Artifacts` - `Artifacts` is a list of `Artifact` objects which define +- `Artifacts` - `Artifacts` is a list of `Artifact` objects which define artifacts to be downloaded before the task is run. See the artifacts reference for more details. -* `Config` - A map of key-value configuration passed into the driver +- `Config` - A map of key-value configuration passed into the driver to start the task. The details of configurations are specific to each driver. -* `Constraints` - This is a list of `Constraint` objects. See the constraint +- `Constraints` - This is a list of `Constraint` objects. See the constraint reference for more details. - `DispatchPayload` - Configures the task to have access to dispatch payloads. The `DispatchPayload` object supports the following attributes: - * `File` - Specifies the file name to write the content of dispatch payload + - `File` - Specifies the file name to write the content of dispatch payload to. The file is written relative to the task's local directory. -* `Driver` - Specifies the task driver that should be used to run the +- `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`. -* `Env` - A map of key-value representing environment variables that +- `Env` - A map of key-value representing environment variables that will be passed along to the running process. Nomad variables are interpreted when set in the environment variable values. See the table of interpreted variables [here](/docs/runtime/interpolation.html). @@ -360,34 +365,34 @@ The `Task` object supports the following keys: } ``` -* `KillTimeout` - `KillTimeout` is a time duration in nanoseconds. It can be +- `KillTimeout` - `KillTimeout` is a time duration in nanoseconds. It can be used to configure the time between signaling a task it will be killed and actually killing it. Drivers first sends a task the `SIGINT` signal and then sends `SIGTERM` if the task doesn't die after the `KillTimeout` duration has elapsed. The default `KillTimeout` is 5 seconds. -* `leader` - Specifies whether the task is the leader task of the task group. If +- `leader` - Specifies whether the task is the leader task of the task group. If set to true, when the leader task completes, all other tasks within the task group will be gracefully shutdown. -* `LogConfig` - This allows configuring log rotation for the `stdout` and `stderr` +- `LogConfig` - This allows configuring log rotation for the `stdout` and `stderr` buffers of a Task. See the log rotation reference below for more details. -* `Meta` - Annotates the task group with opaque metadata. +- `Meta` - Annotates the task group with opaque metadata. -* `Name` - The name of the task. This field is required. +- `Name` - The name of the task. This field is required. -* `Resources` - Provides the resource requirements of the task. +- `Resources` - Provides the resource requirements of the task. See the resources reference for more details. -* `Services` - `Services` is a list of `Service` objects. Nomad integrates with +- `Services` - `Services` is a list of `Service` objects. Nomad integrates with Consul for service discovery. A `Service` object represents a routable and discoverable service on the network. Nomad automatically registers when a task is started and de-registers it when the task transitions to the dead state. [Click here](/docs/service-discovery/index.html) to learn more about services. Below is the fields in the `Service` object: - * `Name`: An explicit name for the Service. Nomad will replace `${JOB}`, + - `Name`: An explicit name for the Service. Nomad will replace `${JOB}`, `${TASKGROUP}` and `${TASK}` by the name of the job, task group or task, respectively. `${BASE}` expands to the equivalent of `${JOB}-${TASKGROUP}-${TASK}`, and is the default name for a Service. @@ -398,78 +403,78 @@ The `Task` object supports the following keys: limited to alphanumeric and hyphen characters (i.e. `[a-z0-9\-]`), and be less than 64 characters in length. - * `Tags`: A list of string tags associated with this Service. String + - `Tags`: A list of string tags associated with this Service. String interpolation is supported in tags. - * `PortLabel`: `PortLabel` is an optional string and is used to associate + - `PortLabel`: `PortLabel` is an optional string and is used to associate a port with the service. If specified, the port label must match one defined in the resources block. This could be a label of either a dynamic or a static port. - * `Checks`: `Checks` is an array of check objects. A check object defines a + - `Checks`: `Checks` is an array of check objects. A check object defines a health check associated with the service. Nomad supports the `script`, `http` and `tcp` Consul Checks. Script checks are not supported for the qemu driver since the Nomad client doesn't have access to the file system of a task using the Qemu driver. - * `Type`: This indicates the check types supported by Nomad. Valid + - `Type`: This indicates the check types supported by Nomad. Valid options are currently `script`, `http` and `tcp`. - * `Name`: The name of the health check. + - `Name`: The name of the health check. - * `Interval`: This indicates the frequency of the health checks that + - `Interval`: This indicates the frequency of the health checks that Consul will perform. - * `Timeout`: This indicates how long Consul will wait for a health + - `Timeout`: This indicates how long Consul will wait for a health check query to succeed. - * `Path`: The path of the http endpoint which Consul will query to query + - `Path`: The path of the http endpoint which Consul will query to query the health of a service if the type of the check is `http`. Nomad will add the IP of the service and the port, users are only required to add the relative URL of the health check endpoint. - * `Protocol`: This indicates the protocol for the http checks. Valid + - `Protocol`: This indicates the protocol for the http checks. Valid options are `http` and `https`. We default it to `http`. - * `Command`: This is the command that the Nomad client runs for doing + - `Command`: This is the command that the Nomad client runs for doing script based health check. - * `Args`: Additional arguments to the `command` for script based health + - `Args`: Additional arguments to the `command` for script based health checks. - * `TLSSkipVerify`: If true, Consul will not attempt to verify the + - `TLSSkipVerify`: If true, Consul will not attempt to verify the certificate when performing HTTPS checks. Requires Consul >= 0.7.2. -* `Templates` - Specifies the set of [`Template`](#template) objects to render for the task. +- `Templates` - Specifies the set of [`Template`](#template) objects to render for the task. Templates can be used to inject both static and dynamic configuration with data populated from environment variables, Consul and Vault. -* `User` - Set the user that will run the task. It defaults to the same user +- `User` - Set the user that will run the task. It defaults to the same user the Nomad client is being run as. This can only be set on Linux platforms. ### Resources The `Resources` object supports the following keys: -* `CPU` - The CPU required in MHz. +- `CPU` - The CPU required in MHz. -* `IOPS` - The number of IOPS required given as a weight between 10-1000. +- `IOPS` - The number of IOPS required given as a weight between 10-1000. -* `MemoryMB` - The memory required in MB. +- `MemoryMB` - The memory required in MB. -* `Networks` - A list of network objects. +- `Networks` - A list of network objects. The Network object supports the following keys: -* `MBits` - The number of MBits in bandwidth required. +- `MBits` - The number of MBits in bandwidth required. Nomad can allocate two types of ports to a task - Dynamic and Static/Reserved ports. A network object allows the user to specify a list of `DynamicPorts` and `ReservedPorts`. Each object supports the following attributes: -* `Value` - The port number for static ports. If the port is dynamic, then this +- `Value` - The port number for static ports. If the port is dynamic, then this attribute is ignored. -* `Label` - The label to annotate a port so that it can be referred in the +- `Label` - The label to annotate a port so that it can be referred in the service discovery block or environment variables. @@ -478,14 +483,14 @@ ports. A network object allows the user to specify a list of `DynamicPorts` and The `EphemeralDisk` object supports the following keys: -* `Migrate` - Specifies that the Nomad client should make a best-effort attempt +- `Migrate` - Specifies that the Nomad client should make a best-effort attempt to migrate the data from a remote machine if placement cannot be made on the original node. During data migration, the task will block starting until the data migration has completed. Value is a boolean and the default is false. -* `SizeMB` - Specifies the size of the ephemeral disk in MB. Default is 300. +- `SizeMB` - Specifies the size of the ephemeral disk in MB. Default is 300. -* `Sticky` - Specifies that Nomad should make a best-effort attempt to place the +- `Sticky` - Specifies that Nomad should make a best-effort attempt to place the updated allocation on the same machine. This will move the `local/` and `alloc/data` directories to the new allocation. Value is a boolean and the default is false. @@ -496,45 +501,45 @@ The `EphemeralDisk` object supports the following keys: The `RestartPolicy` object supports the following keys: -* `Attempts` - `Attempts` is the number of restarts allowed in an `Interval`. +- `Attempts` - `Attempts` is the number of restarts allowed in an `Interval`. -* `Interval` - `Interval` is a time duration that is specified in nanoseconds. +- `Interval` - `Interval` is a time duration that is specified in nanoseconds. The `Interval` begins when the first task starts and ensures that only `Attempts` number of restarts happens within it. If more than `Attempts` number of failures happen, behavior is controlled by `Mode`. -* `Delay` - A duration to wait before restarting a task. It is specified in +- `Delay` - A duration to wait before restarting a task. It is specified in nanoseconds. A random jitter of up to 25% is added to the delay. -* `Mode` - `Mode` is given as a string and controls the behavior when the task +- `Mode` - `Mode` is given as a string and controls the behavior when the task fails more than `Attempts` times in an `Interval`. Possible values are listed below: - * `delay` - `delay` will delay the next restart until the next `Interval` is + - `delay` - `delay` will delay the next restart until the next `Interval` is reached. - * `fail` - `fail` will not restart the task again. + - `fail` - `fail` will not restart the task again. ### Constraint The `Constraint` object supports the following keys: -* `LTarget` - Specifies the attribute to examine for the +- `LTarget` - Specifies the attribute to examine for the constraint. See the table of attributes [here](/docs/runtime/interpolation.html#interpreted_node_vars). -* `RTarget` - Specifies the value to compare the attribute against. +- `RTarget` - Specifies the value to compare the attribute against. This can be a literal value, another attribute or a regular expression if the `Operator` is in "regexp" mode. -* `Operand` - Specifies the test to be performed on the two targets. It takes on the +- `Operand` - Specifies the test to be performed on the two targets. It takes on the following values: - * `regexp` - Allows the `RTarget` to be a regular expression to be matched. + - `regexp` - Allows the `RTarget` to be a regular expression to be matched. - * `set_contains` - Allows the `RTarget` to be a comma separated list of values + - `set_contains` - Allows the `RTarget` to be a comma separated list of values that should be contained in the LTarget's value. - * `distinct_host` - If set, the scheduler will not co-locate any task groups on the same + - `distinct_host` - If set, the scheduler will not co-locate any task groups on the same machine. This can be specified as a job constraint which applies the constraint to all task groups in the job, or as a task group constraint which scopes the effect to just that group. The constraint may not be @@ -545,7 +550,7 @@ The `Constraint` object supports the following keys: to all task groups. When specified, `LTarget` and `RTarget` should be omitted. - * `distinct_property` - If set, the scheduler selects nodes that have a + - `distinct_property` - If set, the scheduler selects nodes that have a distinct value of the specified property for each allocation. This can be specified as a job constraint which applies the constraint to all task groups in the job, or as a task group constraint which scopes the @@ -557,7 +562,7 @@ The `Constraint` object supports the following keys: to all task groups. When specified, `LTarget` should be the property that should be distinct and and `RTarget` should be omitted. - * Comparison Operators - `=`, `==`, `is`, `!=`, `not`, `>`, `>=`, `<`, `<=`. The + - Comparison Operators - `=`, `==`, `is`, `!=`, `not`, `>`, `>=`, `<`, `<=`. The ordering is compared lexically. ### Log Rotation @@ -565,10 +570,10 @@ The `Constraint` object supports the following keys: The `LogConfig` object configures the log rotation policy for a task's `stdout` and `stderr`. The `LogConfig` object supports the following attributes: -* `MaxFiles` - The maximum number of rotated files Nomad will retain for +- `MaxFiles` - The maximum number of rotated files Nomad will retain for `stdout` and `stderr`, each tracked individually. -* `MaxFileSizeMB` - The size of each rotated file. The size is specified in +- `MaxFileSizeMB` - The size of each rotated file. The size is specified in `MB`. If the amount of disk resource requested for the task is less than the total @@ -605,12 +610,12 @@ is started. The `Artifact` object supports the following keys: -* `GetterSource` - The path to the artifact to download. +- `GetterSource` - The path to the artifact to download. -* `RelativeDest` - An optional path to download the artifact into relative to the +- `RelativeDest` - An optional path to download the artifact into relative to the root of the task's directory. If omitted, it will default to `local/`. -* `GetterOptions` - A `map[string]string` block of options for `go-getter`. +- `GetterOptions` - A `map[string]string` block of options for `go-getter`. Full documentation of supported options are available [here](https://github.com/hashicorp/go-getter/tree/ef5edd3d8f6f482b775199be2f3734fd20e04d4a#protocol-specific-options-1). An example is given below: @@ -708,35 +713,35 @@ README][ct]. - `"restart"` - restart the task - `"signal"` - send a configurable signal to the task -* `ChangeSignal` - Specifies the signal to send to the task as a string like +- `ChangeSignal` - Specifies the signal to send to the task as a string like "SIGUSR1" or "SIGINT". This option is required if the `ChangeMode` is `signal`. -* `DestPath` - Specifies the location where the resulting template should be +- `DestPath` - Specifies the location where the resulting template should be rendered, relative to the task directory. -* `EmbeddedTmpl` - Specifies the raw template to execute. One of `SourcePath` +- `EmbeddedTmpl` - Specifies the raw template to execute. One of `SourcePath` or `EmbeddedTmpl` must be specified, but not both. This is useful for smaller templates, but we recommend using `SourcePath` for larger templates. -* `LeftDelim` - Specifies the left delimiter to use in the template. The default +- `LeftDelim` - Specifies the left delimiter to use in the template. The default is "{{" for some templates, it may be easier to use a different delimiter that does not conflict with the output file itself. -* `Perms` - Specifies the rendered template's permissions. File permissions are +- `Perms` - Specifies the rendered template's permissions. File permissions are given as octal of the unix file permissions rwxrwxrwx. -* `RightDelim` - Specifies the right delimiter to use in the template. The default +- `RightDelim` - Specifies the right delimiter to use in the template. The default is "}}" for some templates, it may be easier to use a different delimiter that does not conflict with the output file itself. -* `SourcePath` - Specifies the path to the template to be rendered. `SourcePath` +- `SourcePath` - Specifies the path to the template to be rendered. `SourcePath` is mutually exclusive with `EmbeddedTmpl` attribute. The source can be fetched using an [`Artifact`](#artifact) resource. The template must exist on the machine prior to starting the task; it is not possible to reference a template inside of a Docker container, for example. -* `Splay` - Specifies a random amount of time to wait between 0ms and the given +- `Splay` - Specifies a random amount of time to wait between 0ms and the given splay value before invoking the change mode. Should be specified in nanoseconds. diff --git a/website/source/api/libraries-and-sdks.html.md b/website/source/api/libraries-and-sdks.html.md new file mode 100644 index 000000000..c7d9732fb --- /dev/null +++ b/website/source/api/libraries-and-sdks.html.md @@ -0,0 +1,33 @@ +--- +layout: api +page_title: Libraries and SDKs - HTTP API +sidebar_current: api-libraries-and-sdks +description: |- + There are many third-party libraries for interacting with Nomad's HTTP API. + This page lists the HashiCorp and community-maintained Nomad HTTP API client + libraries. +--- + +# Client Libraries & SDKs + +The programming libraries listed on this page can be used to consume the API +more conveniently. Some are officially maintained while others are provided by +the community. + +## Official Libraries + +- [`api`](https://github.com/hashicorp/nomad/tree/master/api) - Official Golang + client for the Nomad HTTP API + +- [`nomad-java-sdk`](https://github.com/hashicorp/nomad-java-sdk) - Official + Java client for the Nomad HTTP API. + +- [`nomad-ruby`](https://github.com/hashicorp/nomad-ruby) - Official Ruby client + for the Nomad HTTP API + +- [`nomad-scala-sdk`](https://github.com/hashicorp/nomad-scala-sdk) - Official + Scala client for the Nomad HTTP API. + +## Third-Party Libraries + +_Want to see your library here? [Submit a Pull Request](https://github.com/hashicorp/nomad)._ diff --git a/website/source/api/nodes.html.md b/website/source/api/nodes.html.md new file mode 100644 index 000000000..92a5d68dc --- /dev/null +++ b/website/source/api/nodes.html.md @@ -0,0 +1,267 @@ +--- +layout: api +page_title: Nodes - HTTP API +sidebar_current: api-nodes +description: |- + The /node endpoints are used to query for and interact with client nodes. +--- + +# Nodes HTTP API + +The `/node` endpoints are used to query for and interact with client nodes. + +### List Nodes + +This endpoint lists all nodes registered with Nomad. + +| Method | Path | Produces | +| ------ | ------------------------- | -------------------------- | +| `GET` | `/v1/nodes` | `application/json` | + +The table below shows this endpoint's support for +[blocking queries](/api/index.html#blocking-queries) and +[required ACLs](/api/index.html#acls). + +| Blocking Queries | ACL Required | +| ---------------- | ------------ | +| `YES` | `none` | + +### Parameters + +- `prefix` `(string: "")`- Specifies a string to filter nodes on based on an + index prefix. This is specified as a querystring parameter. + +### Sample Request + +```text +$ curl \ + https://nomad.rocks/v1/nodes +``` + +```text +$ curl \ + https://nomad.rocks/v1/nodes?prefix=prod +``` + +### Sample Response + +```json +[ + { + "ID": "fb2170a8-257d-3c64-b14d-bc06cc94e34c", + "Datacenter": "dc1", + "Name": "bacon-mac", + "NodeClass": "", + "Drain": false, + "Status": "ready", + "StatusDescription": "", + "CreateIndex": 5, + "ModifyIndex": 45 + } +] +``` + +## Read Node + +This endpoint queries the status of a client node. + +| Method | Path | Produces | +| ------ | ------------------------- | -------------------------- | +| `GET` | `/v1/node/:node_id` | `application/json` | + +The table below shows this endpoint's support for +[blocking queries](/api/index.html#blocking-queries) and +[required ACLs](/api/index.html#acls). + +| Blocking Queries | ACL Required | +| ---------------- | ------------ | +| `YES` | `none` | + +### Parameters + +- `:node_id` `(string: )`- Specifies the ID of the node. This must be + the full UUID, not the short 8-character one. This is specified as part of the + path. + +### Sample Request + +```text +$ curl \ + https://nomad.rocks/v1/node/fb2170a8-257d-3c64-b14d-bc06cc94e34c +``` + +### Sample Response + +```json +{ + "ID": "fb2170a8-257d-3c64-b14d-bc06cc94e34c", + "SecretID": "", + "Datacenter": "dc1", + "Name": "bacon-mac", + "HTTPAddr": "127.0.0.1:4646", + "TLSEnabled": false, + "Attributes": { + "os.version": "10.12.5", + "cpu.modelname": "Intel(R) Core(TM) i7-3615QM CPU @ 2.30GHz", + "nomad.revision": "f551dcb83e3ac144c9dbb90583b6e82d234662e9", + "driver.docker.volumes.enabled": "1", + "driver.docker": "1", + "cpu.frequency": "2300", + "memory.totalbytes": "17179869184", + "driver.mock_driver": "1", + "kernel.version": "16.6.0", + "unique.network.ip-address": "127.0.0.1", + "nomad.version": "0.5.5dev", + "unique.hostname": "bacon-mac", + "cpu.arch": "amd64", + "os.name": "darwin", + "kernel.name": "darwin", + "unique.storage.volume": "/dev/disk1", + "driver.docker.version": "17.03.1-ce", + "cpu.totalcompute": "18400", + "unique.storage.bytestotal": "249783500800", + "cpu.numcores": "8", + "os.signals": "SIGCONT,SIGSTOP,SIGSYS,SIGINT,SIGIOT,SIGXCPU,SIGSEGV,SIGUSR1,SIGTTIN,SIGURG,SIGUSR2,SIGABRT,SIGALRM,SIGCHLD,SIGFPE,SIGTSTP,SIGIO,SIGKILL,SIGQUIT,SIGXFSZ,SIGBUS,SIGHUP,SIGPIPE,SIGPROF,SIGTRAP,SIGTTOU,SIGILL,SIGTERM", + "driver.raw_exec": "1", + "unique.storage.bytesfree": "142954643456" + }, + "Resources": { + "CPU": 18400, + "MemoryMB": 16384, + "DiskMB": 136332, + "IOPS": 0, + "Networks": [ + { + "Device": "lo0", + "CIDR": "127.0.0.1/32", + "IP": "127.0.0.1", + "MBits": 1000, + "ReservedPorts": null, + "DynamicPorts": null + } + ] + }, + "Reserved": { + "CPU": 0, + "MemoryMB": 0, + "DiskMB": 0, + "IOPS": 0, + "Networks": null + }, + "Links": null, + "Meta": null, + "NodeClass": "", + "ComputedClass": "v1:10952212473894849978", + "Drain": false, + "Status": "ready", + "StatusDescription": "", + "StatusUpdatedAt": 1495748907, + "CreateIndex": 5, + "ModifyIndex": 45 +} +``` + +## Create Node Evaluation + +This endpoint creates a new evaluation for the given node. This can be used to +force a run of the scheduling logic. + +| Method | Path | Produces | +| ------- | ---------------------------- | -------------------------- | +| `POST` | `/v1/node/:node_id/evaluate` | `application/json` | + +The table below shows this endpoint's support for +[blocking queries](/api/index.html#blocking-queries) and +[required ACLs](/api/index.html#acls). + +| Blocking Queries | ACL Required | +| ---------------- | ------------ | +| `NO` | `none` | + +### Parameters + +- `:node_id` `(string: )`- Specifies the UUID of the node. This must + be the full UUID, not the short 8-character one. This is specified as part of + the path. + +### Sample Request + +```text +$ curl \ + https://nomad.rocks/v1/node/fb2170a8-257d-3c64-b14d-bc06cc94e34c/evaluate +``` + +### Sample Response + +```json +{ + "HeartbeatTTL": 0, + "EvalIDs": [ + "4ff1c7a2-c650-4058-f509-d5028ff9566e" + ], + "EvalCreateIndex": 85, + "NodeModifyIndex": 0, + "LeaderRPCAddr": "127.0.0.1:4647", + "NumNodes": 1, + "Servers": [ + { + "RPCAdvertiseAddr": "127.0.0.1:4647", + "RPCMajorVersion": 1, + "RPCMinorVersion": 1, + "Datacenter": "dc1" + } + ], + "Index": 85, + "LastContact": 0, + "KnownLeader": false +} +``` + +## Drain Node + +This endpoint toggles the drain mode of the node. When draining is enabled, no +further allocations will be assigned to this node, and existing allocations will +be migrated to new nodes. + +| Method | Path | Produces | +| ------- | ------------------------- | -------------------------- | +| `POST` | `/v1/node/:node_id/drain` | `application/json` | + +The table below shows this endpoint's support for +[blocking queries](/api/index.html#blocking-queries) and +[required ACLs](/api/index.html#acls). + +| Blocking Queries | ACL Required | +| ---------------- | ------------ | +| `NO` | `none` | + +### Parameters + +- `:node_id` `(string: )`- Specifies the UUID of the node. This must + be the full UUID, not the short 8-character one. This is specified as part of + the path. + +- `enable` `(bool: )` - Specifies if drain mode should be enabled. + This is specified as a query string parameter. + +### Sample Request + +```text +$ curl \ + https://nomad.rocks/v1/node/fb2170a8-257d-3c64-b14d-bc06cc94e34c/drain?enable=true +``` + +### Sample Response + +```json +{ + "EvalIDs": [ + "253ec083-22a7-76c9-b8b6-2bf3d4b27bfb" + ], + "EvalCreateIndex": 91, + "NodeModifyIndex": 90, + "Index": 90, + "LastContact": 0, + "KnownLeader": false +} +``` diff --git a/website/source/api/operator.html.md b/website/source/api/operator.html.md new file mode 100644 index 000000000..5f66eed25 --- /dev/null +++ b/website/source/api/operator.html.md @@ -0,0 +1,124 @@ +--- +layout: api +page_title: Operator - HTTP API +sidebar_current: api-operator +description: |- + The /operator endpoints provides cluster-level tools for Nomad operators, such + as interacting with the Raft subsystem. +--- +# /v1/operator + +The `/operator` endpoint provides cluster-level tools for Nomad operators, such +as interacting with the Raft subsystem. + +~> Use this interface with extreme caution, as improper use could lead to a +Nomad outage and even loss of data. + +See the [Outage Recovery](/guides/outage.html) guide for some examples of how +these capabilities are used. For a CLI to perform these operations manually, +please see the documentation for the +[`nomad operator`](/docs/commands/operator-index.html) command. + + +## Read Raft Configuration + +This endpoint queries the status of a client node registered with Nomad. + +| Method | Path | Produces | +| ------ | --------------------------------- | -------------------------- | +| `GET` | `/v1/operator/raft/configuration` | `application/json` | + +The table below shows this endpoint's support for +[blocking queries](/api/index.html#blocking-queries) and +[required ACLs](/api/index.html#acls). + +| Blocking Queries | ACL Required | +| ---------------- | ------------ | +| `NO` | `none` | + +### Parameters + +- `stale` - Specifies if the cluster should respond without an active leader. + This is specified as a querystring parameter. + +### Sample Request + +```text +$ curl \ + https://nomad.rocks/v1/operator/raft/configuration +``` + +### Sample Response + +```json +{ + "Index": 1, + "Servers": [ + { + "Address": "127.0.0.1:4647", + "ID": "127.0.0.1:4647", + "Leader": true, + "Node": "bacon-mac.global", + "Voter": true + } + ] +} +``` + +#### Field Reference + +- `Index` `(int)` - The `Index` value is the Raft corresponding to this + configuration. The latest configuration may not yet be committed if changes + are in flight. + +- `Servers` `(array: Server)` - The returned `Servers` array has information + about the servers in the Raft peer configuration. + + - `ID` `(string)` - The ID of the server. This is the same as the `Address` + but may be upgraded to a GUID in a future version of Nomad. + + - `Node` `(string)` - The node name of the server, as known to Nomad, or + `"(unknown)"` if the node is stale and not known. + + - `Address` `(string)` - The `ip:port` for the server. + + - `Leader` `(bool)` - is either "true" or "false" depending on the server's + role in the Raft configuration. + + - `Voter` `(bool)` - is "true" or "false", indicating if the server has a vote + in the Raft configuration. Future versions of Nomad may add support for + non-voting servers. + +## Remove Raft Peer + +This endpoint removes a Nomad server with given address from the Raft +configuration. The return code signifies success or failure. + +| Method | Path | Produces | +| -------- | ---------------------------| -------------------------- | +| `DELETE` | `/v1/operator/raft/peer` | `application/json` | + +The table below shows this endpoint's support for +[blocking queries](/api/index.html#blocking-queries) and +[required ACLs](/api/index.html#acls). + +| Blocking Queries | ACL Required | +| ---------------- | ------------ | +| `NO` | `none` | + +### Parameters + +- `address` `(string: )` - Specifies the server to remove as + `ip:port`. This may be provided multiple times and is provided as a + querystring parameter. + +- `stale` - Specifies if the cluster should respond without an active leader. + This is specified as a querystring parameter. + +### Sample Request + +```text +$ curl \ + --request DELETE \ + https://nomad.rocks/v1/operator/raft/peer?address=1.2.3.4 +``` diff --git a/website/source/api/regions.html.md b/website/source/api/regions.html.md new file mode 100644 index 000000000..2e2880db7 --- /dev/null +++ b/website/source/api/regions.html.md @@ -0,0 +1,41 @@ +--- +layout: api +page_title: Regions - HTTP API +sidebar_current: api-regions +description: |- + The /regions endpoints list all known regions. +--- + +# Regions HTTP API + +The `/regions` endpoints list all known regions. + +## List Regions + +| Method | Path | Produces | +| ------ | ---------------------------- | -------------------------- | +| `GET` | `/status/regions` | `application/json` | + +The table below shows this endpoint's support for +[blocking queries](/api/index.html#blocking-queries) and +[required ACLs](/api/index.html#acls). + +| Blocking Queries | ACL Required | +| ---------------- | ------------ | +| `NO` | `none` | + +### Sample Request + +```text +$ curl \ + https://nomad.rocks/v1/status/regions +``` + +### Sample Response + +```json +[ + "region1", + "region2" +] +``` diff --git a/website/source/api/status.html.md b/website/source/api/status.html.md new file mode 100644 index 000000000..949165c58 --- /dev/null +++ b/website/source/api/status.html.md @@ -0,0 +1,71 @@ +--- +layout: api +page_title: Status - HTTP API +sidebar_current: api-status +description: |- + The /status endpoints query the Nomad system status. +--- + +# Status HTTP API + +The `/status` endpoints query the Nomad system status. + +## Read Leader + +This endpoint returns the address of the current leader in the region. + +| Method | Path | Produces | +| ------ | ---------------------------- | -------------------------- | +| `GET` | `/status/leader` | `application/json` | + +The table below shows this endpoint's support for +[blocking queries](/api/index.html#blocking-queries) and +[required ACLs](/api/index.html#acls). + +| Blocking Queries | ACL Required | +| ---------------- | ------------ | +| `NO` | `none` | + +### Sample Request + +```text +$ curl \ + https://nomad.rocks/v1/status/leader +``` + +### Sample Response + +```json +"127.0.0.1:4647" +``` + +## List Peers + +This endpoint returns the set of raft peers in the region. + +| Method | Path | Produces | +| ------ | ---------------------------- | -------------------------- | +| `GET` | `/status/peers` | `application/json` | + +The table below shows this endpoint's support for +[blocking queries](/api/index.html#blocking-queries) and +[required ACLs](/api/index.html#acls). + +| Blocking Queries | ACL Required | +| ---------------- | ------------ | +| `NO` | `none` | + +### Sample Request + +```text +$ curl \ + https://nomad.rocks/v1/status/peers +``` + +### Sample Response + +```json +[ + "127.0.0.1:4647" +] +``` diff --git a/website/source/api/system.html.md b/website/source/api/system.html.md new file mode 100644 index 000000000..d730f054a --- /dev/null +++ b/website/source/api/system.html.md @@ -0,0 +1,59 @@ +--- +layout: api +page_title: System - HTTP API +sidebar_current: api-system +description: |- + The /system endpoints are used for system maintenance. +--- + +# System HTTP API + +The `/system` endpoints are used to for system maintenance and should not be +necessary for most users. + +## Force GC + +This endpoint initializes a garbage collection of jobs, evals, allocations, and +nodes. This is an asynchronous operation. + +| Method | Path | Produces | +| ------ | ---------------------------| -------------------------- | +| `PUT` | `/v1/system/gc` | `application/json` | + +The table below shows this endpoint's support for +[blocking queries](/api/index.html#blocking-queries) and +[required ACLs](/api/index.html#acls). + +| Blocking Queries | ACL Required | +| ---------------- | ------------ | +| `NO` | `none` | + +### Sample Request + +```text +$ curl \ + --request PUT \ + https://nomad.rocks/v1/system/gc +``` + +## Reconcile Summaries + +This endpoint reconciles the summaries of all registered jobs. + +| Method | Path | Produces | +| ------ | --------------------------------- | -------------------------- | +| `PUT` | `/v1/system/reconcile/summaries` | `application/json` | + +The table below shows this endpoint's support for +[blocking queries](/api/index.html#blocking-queries) and +[required ACLs](/api/index.html#acls). + +| Blocking Queries | ACL Required | +| ---------------- | ------------ | +| `NO` | `none` | +### Sample Request + +```text +$ curl \ + https://nomad.rocks/v1/system/reconcile/summaries +``` diff --git a/website/source/api/validate.html.md b/website/source/api/validate.html.md new file mode 100644 index 000000000..8b6c2ac97 --- /dev/null +++ b/website/source/api/validate.html.md @@ -0,0 +1,63 @@ +--- +layout: api +page_title: Validate - HTTP API +sidebar_current: api-validate +description: |- + The /validate endpoints are used to validate object structs, fields, and + types. +--- + +# Validate HTTP API + +The `/validate` endpoints are used to validate object structs, fields, and +types. + +## Validate Job + +This endpoint validates a Nomad job file. The local Nomad agent forwards the +request to a server. In the event a server can't be reached the agent verifies +the job file locally but skips validating driver configurations. + +~> This endpoint accepts a **JSON job file**, not an HCL job file. + +| Method | Path | Produces | +| ------- | ------------------------- | -------------------------- | +| `POST` | `/v1/validate/job` | `application/json` | + +The table below shows this endpoint's support for +[blocking queries](/api/index.html#blocking-queries) and +[required ACLs](/api/index.html#acls). + +| Blocking Queries | ACL Required | +| ---------------- | ------------ | +| `NO` | `none` | + +### Parameters + +There are no parameters, but the request _body_ contains the entire job file. + +### Sample Payload + +```text +(any valid nomad job IN JSON FORMAT) +``` + +### Sample Request + +```text +$ curl \ + --request POST \ + --data @my-job.nomad \ + https://nomad.rocks/v1/validate/job +``` + +### Sample Response +```json +{ + "DriverConfigValidated": true, + "ValidationErrors": [ + "Task group cache validation failed: 1 error(s) occurred:\n\n* Task redis validation failed: 1 error(s) occurred:\n\n* 1 error(s) occurred:\n\n* minimum CPU value is 20; got 1" + ], + "Error": "1 error(s) occurred:\n\n* Task group cache validation failed: 1 error(s) occurred:\n\n* Task redis validation failed: 1 error(s) occurred:\n\n* 1 error(s) occurred:\n\n* minimum CPU value is 20; got 1" +} +``` diff --git a/website/source/community.html.erb b/website/source/community.html.erb index 5273df22f..62e641f81 100644 --- a/website/source/community.html.erb +++ b/website/source/community.html.erb @@ -8,120 +8,131 @@ description: |-

Community

-Nomad is an open source project with a growing community. There are -active, dedicated users willing to help you through various mediums. + Nomad is an open source project with a growing community. There are + active, dedicated users willing to help you through various mediums.

-Gitter: Nomad Gitter Room + Gitter: Nomad Gitter Room

-IRC: Use the Gitter IRC bridge + IRC: Use the Gitter IRC bridge

-Mailing list: -Nomad Google Group + Mailing list: + Nomad Google Group

-Bug Tracker: -Issue tracker - on GitHub. Please only use this for reporting bugs. Do not ask -for general help here. Use IRC or the mailing list for that. + Bug Tracker: + Issue tracker + on GitHub. Please only use this for reporting bugs. Do not ask + for general help here. Use IRC or the mailing list for that. +

+ +

Community Tools

+

+ These Nomad projects are created and managed by the amazing members of the + Nomad community: +

-

Community Tools

-

These Nomad projects are created and managed by the amazing members of the Nomad community:

    -
  • nomad-ui - Nomad UI is a simple to deploy, web based UI for interacting with Nomad
    • -
  • nomad-jenkins - This project uses Nomad to provision new Jenkins build slaves based on workload
    • +
  • nomad-ui - Nomad UI is a simple to deploy, web based UI for interacting with Nomad
    • +
  • nomad-jenkins - This project uses Nomad to provision new Jenkins build slaves based on workload
-

People

+ + Want to see your library here? + Submit a Pull Request. + We also have a full list of HTTP API Libraries. + + + +

People

+

-The following people are some of the faces behind Nomad. They each -contribute to Nomad in some core way. Over time, faces may appear and -disappear from this list as contributors come and go. In addition to -the faces below, Nomad is a project by -HashiCorp, so many HashiCorp -employees actively contribute to Nomad. + The following people are some of the faces behind Nomad. They each contribute + to Nomad in some core way. Over time, faces may appear and disappear from this + list as contributors come and go. In addition to the faces below, Nomad is a + project by HashiCorp, so many + HashiCorp employees actively contribute to Nomad.

+
-
- -
-

Armon Dadgar (@armon)

-

- Armon Dadgar is a creator of Nomad. He works on all aspects of Nomad, - focusing on core architecture. Armon is also an author or - core contributor to: - Vault, - Consul, - Serf, - Terraform, - and Statsite. -

-
+
+ +
+

Armon Dadgar (@armon)

+

+ Armon Dadgar is a creator of Nomad. He works on all aspects of Nomad, + focusing on core architecture. Armon is also an author or + core contributor to: + Vault, + Consul, + Serf, + Terraform, + and Statsite. +

+
-
- -
-

Ryan Uber (@ryanuber)

-

- Ryan Uber is a HashiCorp employee and core contributor to Nomad, with a - focus on the agent, API client, and command-line interface. Ryan is also - an active contributor to both Consul - and Serf. -

-
-
- -
- -
-

Alex Dadgar (@dadgar)

-

- Alex is a HashiCorp employee and a core contributor to Nomad. He works on - resource isolation and Drivers, among other things. -

-
-
- -
- -
-

Clint Shryock (@catsby)

-

- Clint Shryock is a HashiCorp employee and core developer on Nomad, - mostly focusing on Drivers and Fingerprinters. Mostly. Clint is also - a core developer on Terraform, and - contributes to Packer. -

-
-
- -
- -
-

Chris Bednarski (@cbednarski)

-

- Chris works at HashiCorp where he helps build Nomad and - Packer, making sure all - parts of the stack play nice together. Chris created - Hostess. -

-
-
+
+ +
+

Ryan Uber (@ryanuber)

+

+ Ryan Uber is a HashiCorp employee and core contributor to Nomad, with a + focus on the agent, API client, and command-line interface. Ryan is also + an active contributor to both Consul + and Serf. +

+
+
- -
-

Jonathan Thomas - JT (@captainill)

-

- JT is an employee at Hashicorp where he works on the identity of all the open source projects. - JT will take the designs and cut up responsive HTML/CSS for each project. -

-
-
+ +
+

Alex Dadgar (@dadgar)

+

+ Alex is a HashiCorp employee and a core contributor to Nomad. He works on + resource isolation and Drivers, among other things. +

+
+
-
+
+ +
+

Clint Shryock (@catsby)

+

+ Clint Shryock is a HashiCorp employee and core developer on Nomad, + mostly focusing on Drivers and Fingerprinters. Mostly. Clint is also + a core developer on Terraform, and + contributes to Packer. +

+
+
+ +
+ +
+

Chris Bednarski (@cbednarski)

+

+ Chris works at HashiCorp where he helps build Nomad and + Packer, making sure all + parts of the stack play nice together. Chris created + Hostess. +

+
+
+ +
+ +
+

Jonathan Thomas - JT (@captainill)

+

+ JT is an employee at Hashicorp where he works on the identity of all the open source projects. + JT will take the designs and cut up responsive HTML/CSS for each project. +

+
+
diff --git a/website/source/docs/commands/inspect.html.md.erb b/website/source/docs/commands/inspect.html.md.erb index 3517416db..ae9b8f8d3 100644 --- a/website/source/docs/commands/inspect.html.md.erb +++ b/website/source/docs/commands/inspect.html.md.erb @@ -18,7 +18,7 @@ nomad inspect [options] The `inspect` command requires a single argument, a submitted job's name, and will retrieve the JSON version of the job. This JSON is valid to be submitted to -the [Job HTTP API](/docs/http/job.html). This command is useful to inspect what +the [Job HTTP API](/api/jobs.html). This command is useful to inspect what version of a job Nomad is running. ## General Options diff --git a/website/source/docs/commands/operator-raft-list-peers.html.md.erb b/website/source/docs/commands/operator-raft-list-peers.html.md.erb index ab2e405d2..d6b23c976 100644 --- a/website/source/docs/commands/operator-raft-list-peers.html.md.erb +++ b/website/source/docs/commands/operator-raft-list-peers.html.md.erb @@ -9,11 +9,11 @@ description: > # Command: `operator raft list-peers` The Raft list-peers command is used to display the current Raft peer -configuration. +configuration. See the [Outage Recovery](/guides/outage.html) guide for some examples of how this command is used. For an API to perform these operations programatically, -please see the documentation for the [Operator](/docs/http/operator.html) +please see the documentation for the [Operator](/api/operator.html) endpoint. ## Usage @@ -36,7 +36,7 @@ server. ## Examples An example output with three servers is as follows: - + ``` $ nomad operator raft list-peers Node ID Address State Voter @@ -58,4 +58,3 @@ Raft configuration. - `Voter` is "true" or "false", indicating if the server has a vote in the Raft configuration. Future versions of Nomad may add support for non-voting servers. - diff --git a/website/source/docs/commands/operator-raft-remove-peer.html.md.erb b/website/source/docs/commands/operator-raft-remove-peer.html.md.erb index fae613d2b..08357efa2 100644 --- a/website/source/docs/commands/operator-raft-remove-peer.html.md.erb +++ b/website/source/docs/commands/operator-raft-remove-peer.html.md.erb @@ -21,7 +21,7 @@ command. See the [Outage Recovery](/guides/outage.html) guide for some examples of how this command is used. For an API to perform these operations programatically, -please see the documentation for the [Operator](/docs/http/operator.html) +please see the documentation for the [Operator](/api/operator.html) endpoint. ## Usage @@ -38,4 +38,3 @@ nomad operator raft remove-peer [options] * `-peer-address`: Remove a Nomad server with given address from the Raft configuration. The format is "IP:port" - diff --git a/website/source/docs/http/agent-force-leave.html.md b/website/source/docs/http/agent-force-leave.html.md deleted file mode 100644 index 486112e26..000000000 --- a/website/source/docs/http/agent-force-leave.html.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -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 `force-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 deleted file mode 100644 index c2ead7df3..000000000 --- a/website/source/docs/http/agent-join.html.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -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 deleted file mode 100644 index f68ad2a5a..000000000 --- a/website/source/docs/http/agent-members.html.md +++ /dev/null @@ -1,70 +0,0 @@ ---- -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 - { - "ServerName": "DIPTANUs-MBP", - "ServerRegion": "global", - "ServerDC": "dc1", - "Members": [ - { - "Name": "DIPTANUs-MBP.global", - "Addr": "127.0.0.1", - "Port": 4648, - "Tags": { - "mvn": "1", - "build": "0.5.0rc2", - "port": "4647", - "bootstrap": "1", - "role": "nomad", - "region": "global", - "dc": "dc1", - "vsn": "1" - }, - "Status": "alive", - "ProtocolMin": 1, - "ProtocolMax": 4, - "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 deleted file mode 100644 index 91fb615de..000000000 --- a/website/source/docs/http/agent-self.html.md +++ /dev/null @@ -1,163 +0,0 @@ ---- -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
-
- Query the state of the target agent. -
- -
Method
-
GET
- -
URL
-
`/v1/agent/self`
- -
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" - }, - "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/docs/http/agent-servers.html.md b/website/source/docs/http/agent-servers.html.md deleted file mode 100644 index 4371e1ae3..000000000 --- a/website/source/docs/http/agent-servers.html.md +++ /dev/null @@ -1,82 +0,0 @@ ---- -layout: "http" -page_title: "HTTP API: /v1/agent/servers" -sidebar_current: "docs-http-agent-servers" -description: |- - The '/v1/agent/servers' endpoint is used to query and update the servers list. ---- - -# /v1/agent/servers - -The `servers` endpoint is used to query an agent in client mode for its list -of known servers. Client nodes register themselves with these server addresses -so that they may dequeue work. The `servers` endpoint can be used to keep this -configuration up to date if there are changes in the cluster. - -## GET - -
-
Description
-
- Lists the known server nodes. -
- -
Method
-
GET
- -
URL
-
`/v1/agent/servers`
- -
Parameters
-
- None -
- -
Returns
-
- - ```javascript - [ - "server1.local:4647", - "server2.local:4647" - ] - ``` - -
-
- -## PUT / POST - -
-
Description
-
- Updates the list of known servers to the provided list. Replaces - all previous server addresses with the new list. -
- -
Method
-
PUT or POST
- -
URL
-
`/v1/agent/servers`
- -
Parameters
-
-
    -
  • - address - required - The address of a server node in host:port format. This - parameter may be specified multiple times to configure - multiple servers on the client. -
    • -
-
- -
Returns
-
- A 200 status code on success. -
-
- - diff --git a/website/source/docs/http/alloc.html.md b/website/source/docs/http/alloc.html.md deleted file mode 100644 index 0ad22b79c..000000000 --- a/website/source/docs/http/alloc.html.md +++ /dev/null @@ -1,281 +0,0 @@ ---- -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 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 -
- -
Blocking Queries
-
- [Supported](/docs/http/index.html#blocking-queries) -
- -
Returns
-
- - ```javascript - { - "ID": "203266e5-e0d6-9486-5e05-397ed2b184af", - "EvalID": "e68125ed-3fba-fb46-46cc-291addbc4455", - "Name": "example.cache[0]", - "NodeID": "e02b6169-83bd-9df6-69bd-832765f333eb", - "JobID": "example", - "ModifyIndex": 9, - "Resources": { - "Networks": [ - { - "DynamicPorts": [ - { - "Value": 20802, - "Label": "db" - } - ], - "ReservedPorts": null, - "MBits": 10, - "IP": "", - "CIDR": "", - "Device": "" - } - ], - "IOPS": 0, - "DiskMB": 0, - "MemoryMB": 256, - "CPU": 500 - }, - "TaskGroup": "cache", - "Job": { - "ModifyIndex": 5, - "CreateIndex": 5, - "StatusDescription": "", - "Status": "", - "Meta": null, - "Update": { - "MaxParallel": 1, - "Stagger": 1e+10 - }, - "TaskGroups": [ - { - "Meta": null, - "Tasks": [ - { - "Meta": null, - "Resources": { - "Networks": [ - { - "DynamicPorts": [ - { - "Value": 20802, - "Label": "db" - } - ], - "ReservedPorts": null, - "MBits": 0, - "IP": "127.0.0.1", - "CIDR": "", - "Device": "lo" - } - ], - "IOPS": 0, - "DiskMB": 0, - "MemoryMB": 256, - "CPU": 500 - }, - "Constraints": null, - "Services": [ - { - "Checks": [ - { - "Timeout": 2e+09, - "Interval": 1e+10, - "Protocol": "", - "Http": "", - "Script": "", - "Type": "tcp", - "Name": "alive", - "Id": "" - } - ], - "PortLabel": "db", - "Tags": [ - "global", - "cache" - ], - "Name": "example-cache-redis", - "Id": "" - } - ], - "Env": null, - "Config": { - "port_map": [ - { - "db": 6379 - } - ], - "image": "redis:latest" - }, - "Driver": "docker", - "Name": "redis" - } - ], - "RestartPolicy": { - "Delay": 2.5e+10, - "Interval": 3e+11, - "Attempts": 10 - }, - "Constraints": null, - "Count": 1, - "Name": "cache" - } - ], - "Region": "global", - "ID": "example", - "Name": "example", - "Type": "service", - "Priority": 50, - "AllAtOnce": false, - "Datacenters": [ - "dc1" - ], - "Constraints": [ - { - "Operand": "=", - "RTarget": "linux", - "LTarget": "${attr.kernel.name}" - } - ] - }, - "TaskResources": { - "redis": { - "Networks": [ - { - "DynamicPorts": [ - { - "Value": 20802, - "Label": "db" - } - ], - "ReservedPorts": null, - "MBits": 0, - "IP": "127.0.0.1", - "CIDR": "", - "Device": "lo" - } - ], - "IOPS": 0, - "DiskMB": 0, - "MemoryMB": 256, - "CPU": 500 - } - }, - "Metrics": { - "CoalescedFailures": 0, - "AllocationTime": 1590406, - "NodesEvaluated": 1, - "NodesFiltered": 0, - "ClassFiltered": null, - "ConstraintFiltered": null, - "NodesExhausted": 0, - "ClassExhausted": null, - "DimensionExhausted": null, - "Scores": { - "e02b6169-83bd-9df6-69bd-832765f333eb.binpack": 6.133651487695705 - } - }, - "DesiredStatus": "run", - "DesiredDescription": "", - "ClientStatus": "running", - "ClientDescription": "", - "TaskStates": { - "redis": { - "Events": [ - { - "KillError": "", - "Message": "", - "Signal": 0, - "ExitCode": 0, - "DriverError": "", - "Time": 1447806038427841000, - "Type": "Started" - } - ], - "State": "running" - "FinishedAt": "0001-01-01T00:00:00Z", - "StartedAt": "2017-03-31T22:51:40.248633594Z", - "Failed": false, - } - }, - "CreateIndex": 7 - } - ``` - -
-
- -### Field Reference - -* `TaskStates` - `TaskStates` is a map of tasks to their current state and the - latest events that have effected the state. - - A task can be in the following states: - - * `TaskStatePending` - The task is waiting to be run, either for the first - time or due to a restart. - * `TaskStateRunning` - The task is currently running. - * `TaskStateDead` - The task is dead and will not run again. - - Further the state contains the `StartedAt` and `FinishedAt` times of the - task. `StartedAt` can be updated multiple times if the task restarts but - `FinishedAt` is set only when the task transistions to `TaskStateDead` - -

The latest 10 events are stored per task. Each event is timestamped (unix nano-seconds) - and has one of the following types:

- - * `Setup Failure` - The task could not be started because there was a - failure setting up the task prior to it running. - * `Driver Failure` - The task could not be started due to a failure in the - driver. - * `Started` - The task was started; either for the first time or due to a - restart. - * `Terminated` - The task was started and exited. - * `Killing` - The task has been sent the kill signal. - * `Killed` - The task was killed by an user. - * `Received` - The task has been pulled by the client at the given timestamp. - * `Failed Validation` - The task was invalid and as such it didn't run. - * `Restarting` - The task terminated and is being restarted. - * `Not Restarting` - the task has failed and is not being restarted because it has exceeded its restart policy. - * `Downloading Artifacts` - The task is downloading the artifact(s) specified in the task. - * `Failed Artifact Download` - Artifact(s) specified in the task failed to download. - * `Restart Signaled` - The task was signalled to be restarted. - * `Signaling` - The task was is being sent a signal. - * `Sibling Task Failed` - A task in the same task group failed. - * `Leader Task Dead` - The group's leader task is dead. - * `Driver` - A message from the driver. - * `Task Setup` - Task setup messages. - - Depending on the type the event will have applicable annotations. diff --git a/website/source/docs/http/allocs.html.md b/website/source/docs/http/allocs.html.md deleted file mode 100644 index dea7b63f0..000000000 --- a/website/source/docs/http/allocs.html.md +++ /dev/null @@ -1,86 +0,0 @@ ---- -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
-
-
    -
  • - prefix - optional - even-length - Filter allocations based on an identifier prefix. -
    • -
-
- -
Blocking Queries
-
- [Supported](/docs/http/index.html#blocking-queries) -
- -
Returns
-
- - ```javascript - [ - { - "ID": "203266e5-e0d6-9486-5e05-397ed2b184af", - "EvalID": "e68125ed-3fba-fb46-46cc-291addbc4455", - "Name": "example.cache[0]", - "NodeID": "e02b6169-83bd-9df6-69bd-832765f333eb", - "JobID": "example", - "TaskGroup": "cache", - "DesiredStatus": "run", - "DesiredDescription": "" - "ClientDescription": "", - "ClientStatus": "running", - "TaskStates": { - "redis": { - "Events": [ - { - "KillError": "", - "Message": "", - "Signal": 0, - "ExitCode": 0, - "DriverError": "", - "Time": 1447806038427841000, - "Type": "Started" - } - ], - "State": "running" - } - }, - "CreateIndex": 7, - "ModifyIndex": 9, - } - ... - ] - ``` - -
-
diff --git a/website/source/docs/http/client-allocation-stats.html.md b/website/source/docs/http/client-allocation-stats.html.md deleted file mode 100644 index 344b977c7..000000000 --- a/website/source/docs/http/client-allocation-stats.html.md +++ /dev/null @@ -1,155 +0,0 @@ ---- -layout: "http" -page_title: "HTTP API: /v1/client/allocation/stats" -sidebar_current: "docs-http-client-allocation-stats" -description: |- - The '/v1/client/allocation/` endpoint is used to query the actual resources - consumed by an allocation. ---- - -# /v1/client/allocation - -The client `allocation` endpoint is used to query the actual resources consumed -by an allocation. The API endpoint is hosted by the Nomad client and requests -have to be made to the nomad client whose resource usage metrics are of -interest. - -## GET - -
-
Description
-
- Query resource usage of an allocation running on a client. -
- -
Method
-
GET
- -
URL
-
`/v1/client/allocation//stats`
- -
Returns
-
- - ```javascript - { - "ResourceUsage": { - "CpuStats": { - "Measured": [ - "System Mode", - "User Mode", - "Percent" - ], - "Percent": 105.77854560628487, - "SystemMode": 6.860067935411291, - "ThrottledPeriods": 0, - "ThrottledTime": 0, - "TotalTicks": 714.0051828424228, - "UserMode": 98.9184820888787 - }, - "MemoryStats": { - "Cache": 0, - "KernelMaxUsage": 0, - "KernelUsage": 0, - "MaxUsage": 0, - "Measured": [ - "RSS", - "Swap" - ], - "RSS": 14098432, - "Swap": 0 - } - }, - "Tasks": { - "redis": { - "Pids": { - "27072": { - "CpuStats": { - "Measured": [ - "System Mode", - "User Mode", - "Percent" - ], - "Percent": 6.8607999603563385, - "SystemMode": 5.880684245133524, - "ThrottledPeriods": 0, - "ThrottledTime": 0, - "TotalTicks": 0, - "UserMode": 0.9801144039714172 - }, - "MemoryStats": { - "Cache": 0, - "KernelMaxUsage": 0, - "KernelUsage": 0, - "MaxUsage": 0, - "Measured": [ - "RSS", - "Swap" - ], - "RSS": 13418496, - "Swap": 0 - } - }, - "27073": { - "CpuStats": { - "Measured": [ - "System Mode", - "User Mode", - "Percent" - ], - "Percent": 98.91774564592852, - "SystemMode": 0.9793836902777665, - "ThrottledPeriods": 0, - "ThrottledTime": 0, - "TotalTicks": 0, - "UserMode": 97.93836768490729 - }, - "MemoryStats": { - "Cache": 0, - "KernelMaxUsage": 0, - "KernelUsage": 0, - "MaxUsage": 0, - "Measured": [ - "RSS", - "Swap" - ], - "RSS": 679936, - "Swap": 0 - } - } - }, - "ResourceUsage": { - "CpuStats": { - "Measured": [ - "System Mode", - "User Mode", - "Percent" - ], - "Percent": 105.77854560628487, - "SystemMode": 6.860067935411291, - "ThrottledPeriods": 0, - "ThrottledTime": 0, - "TotalTicks": 714.0051828424228, - "UserMode": 98.9184820888787 - }, - "MemoryStats": { - "Cache": 0, - "KernelMaxUsage": 0, - "KernelUsage": 0, - "MaxUsage": 0, - "Measured": [ - "RSS", - "Swap" - ], - "RSS": 14098432, - "Swap": 0 - } - }, - "Timestamp": 1465865820750959600 - } - }, - "Timestamp": 1465865820750959600 - } - ``` -
-
diff --git a/website/source/docs/http/client-fs.html.md b/website/source/docs/http/client-fs.html.md deleted file mode 100644 index 0c6c7140b..000000000 --- a/website/source/docs/http/client-fs.html.md +++ /dev/null @@ -1,370 +0,0 @@ ---- -layout: "http" -page_title: "HTTP API: /v1/client/fs" -sidebar_current: "docs-http-client-fs" -description: |- - The '/v1/client/fs` endpoints are used to read the contents of an allocation - directory. ---- - -# /v1/client/fs - -The client `fs` endpoints are used to read the contents of files and -directories inside an allocation directory. The API endpoints are hosted by the -Nomad client and requests have to be made to the Client where the particular -allocation was placed. - -## GET - -
-
Description
-
- Read contents of a file in an allocation directory. -
- -
Method
-
GET
- -
URL
-
`/v1/client/fs/cat/`
- -
Parameters
-
-
    -
  • - path - required - The path relative to the root of the allocation directory. It - defaults to `/` -
    • -
-
- -
Returns
-
- - ``` -... -07:49 docker/3e8f0f4a67c2[924]: 1:M 22 Jun 21:07:49.110 # Server started, Redis version 3.2.1 -07:49 docker/3e8f0f4a67c2[924]: 1:M 22 Jun 21:07:49.110 * The server is now ready to accept connections on port 6379 -... - ``` - -
- -
- -
-
Description
-
- Read contents of a file in an allocation directory at a particular offset. -
- -
Method
-
GET
- -
URL
-
`/v1/client/fs/readat/`
- -
Parameters
-
-
    -
  • - path - required - The path relative to the root of the allocation directory. It - defaults to `/` -
    • -
-
    -
  • - offset - required - The byte offset from where content is going to be read. -
    • -
-
    -
  • - limit - required - The number of bytes to read from the offset. -
    • -
- -
- -
Returns
-
- - ``` -... -07:49 docker/3e8f0f4a67c2[924]: 1:M 22 Jun 21:07:49.110 # Server started, Redis version 3.2.1 -07:49 docker/3e8f0f4a67c2[924]: 1:M 22 Jun 21:07:49.110 * The server is now ready to accept connections on port 6379 -... - ``` - -
- -
- - -
-
Description
-
- Stream contents of a file in an allocation directory. -
- -
Method
-
GET
- -
URL
-
`/v1/client/fs/stream/`
- -
Parameters
-
-
    -
  • - path - required - The path relative to the root of the allocation directory. It - defaults to `/` -
    • -
  • - offset - The offset to start streaming from. Defaults to 0. -
    • -
  • - origin - Origin can be either "start" or "end" and applies the offset relative to - either the start or end of the file respectively. Defaults to "start". -
    • -
-
- -
Returns
-
- - ``` -... - { - "File":"alloc/logs/redis.stdout.0", - "Offset":3604480 - "Data": "NTMxOTMyCjUzMTkzMwo1MzE5MzQKNTMx..." - } - { - "File":"alloc/logs/redis.stdout.0", - "FileEvent": "file deleted" - } - ``` - -
- - -
Field Reference
-
- The return value is a stream of frames. These frames contain the following - fields: - -
    -
  • - Data - A base64 encoding of the bytes being streamed. -
    • -
  • - FileEvent - An event that could cause a change in the streams position. The possible - values are "file deleted" and "file truncated". -
    • -
  • - Offset - Offset is the offset into the stream. -
    • -
  • - File - The name of the file being streamed. -
    • -
-
-
- - - -
-
Description
-
- Stream a task's stdout/stderr logs. -
- -
Method
-
GET
- -
URL
-
`/v1/client/fs/logs/`
- -
Parameters
-
-
    -
  • - task - required - The name of the task inside the allocation to stream logs from. -
    • -
  • - follow - required - A boolean of whether to follow logs. -
    • -
  • - type - Either, "stdout" or "stderr", defaults to "stdout" if omitted. -
    • -
  • - offset - The offset to start streaming from. Defaults to 0. -
    • -
  • - origin - Origin can be either "start" or "end" and applies the offset relative to - either the start or end of the logs respectively. Defaults to "start". -
    • -
  • - plain - A boolean of whether to return just the plain text without framing. - This can be usef when viewing logs in a browser. -
    • -
-
- -
Returns
-
- - ``` -... - { - "File":"alloc/logs/redis.stdout.0", - "Offset":3604480 - "Data": "NTMxOTMyCjUzMTkzMwo1MzE5MzQKNTMx..." - } - { - "File":"alloc/logs/redis.stdout.0", - "FileEvent": "file deleted" - } - ``` - -
- - -
Field Reference
-
- The return value is a stream of frames. These frames contain the following - fields: - -
    -
  • - Data - A base64 encoding of the bytes being streamed. -
    • -
  • - FileEvent - An event that could cause a change in the streams position. The possible - values are "file deleted" and "file truncated". -
    • -
  • - Offset - Offset is the offset into the stream. -
    • -
  • - File - The name of the file being streamed. -
    • -
-
-
- -
-
Description
-
- List files in an allocation directory. -
- -
Method
-
GET
- -
URL
-
`/v1/client/fs/ls/`
- -
Parameters
-
-
    -
  • - path - required - The path relative to the root of the allocation directory. It - defaults to `/`, the root of the allocation directory. -
    • -
-
- -
Returns
-
- - ```javascript - [ - { - "Name": "alloc", - "IsDir": true, - "Size": 4096, - "FileMode": "drwxrwxr-x", - "ModTime": "2016-03-15T15:40:00.414236712-07:00" - }, - { - "Name": "redis", - "IsDir": true, - "Size": 4096, - "FileMode": "drwxrwxr-x", - "ModTime": "2016-03-15T15:40:56.810238153-07:00" - } - ] - ``` - -
-
- -
-
Description
-
- Stat a file in an allocation directory. -
- -
Method
-
GET
- -
URL
-
`/v1/client/fs/stat/`
- -
Parameters
-
-
    -
  • - path - required - The path of the file relative to the root of the allocation directory. -
    • -
-
- -
Returns
-
- - ```javascript - { - "Name": "redis-syslog-collector.out", - "IsDir": false, - "Size": 96, - "FileMode": "-rw-rw-r--", - "ModTime": "2016-03-15T15:40:56.822238153-07:00" - } - ``` - -
-
diff --git a/website/source/docs/http/client-stats.html.md b/website/source/docs/http/client-stats.html.md deleted file mode 100644 index bf3a123cf..000000000 --- a/website/source/docs/http/client-stats.html.md +++ /dev/null @@ -1,88 +0,0 @@ ---- -layout: "http" -page_title: "HTTP API: /v1/client/stats" -sidebar_current: "docs-http-client-stats" -description: |- - The '/v1/client/stats` endpoint is used to query the actual resources consumed - on the node. ---- - -# /v1/client/stats - -The client `stats` endpoint is used to query the actual resources consumed on a node. -The API endpoint is hosted by the Nomad client and requests have to be made to -the nomad client whose resource usage metrics are of interest. - -## GET - -
-
Description
-
- Query the actual resource usage of a Nomad client -
- -
Method
-
GET
- -
URL
-
`/v1/client/stats`
- -
Returns
-
- - ```javascript - { - "CPU": [ - { - "CPU": "cpu0", - "Idle": 89.2156862745098, - "System": 4.901960784313726, - "Total": 10.784313725490197, - "User": 5.88235294117647 - }, - { - "CPU": "cpu1", - "Idle": 100, - "System": 0, - "Total": 0, - "User": 0 - }, - { - "CPU": "cpu2", - "Idle": 94.05940594059405, - "System": 2.9702970297029703, - "Total": 5.9405940594059405, - "User": 2.9702970297029703 - }, - { - "CPU": "cpu3", - "Idle": 99.00990099009901, - "System": 0, - "Total": 0.9900990099009901, - "User": 0.9900990099009901 - } - ], - "CPUTicksConsumed": 119.5762958648806, - "DiskStats": [ - { - "Available": 16997969920, - "Device": "/dev/disk1", - "InodesUsedPercent": 85.84777164286838, - "Mountpoint": "/", - "Size": 120108089344, - "Used": 102847975424, - "UsedPercent": 85.62951586835626 - } - ], - "Memory": { - "Available": 3724746752, - "Free": 2446233600, - "Total": 8589934592, - "Used": 4865187840 - }, - "Timestamp": 1465839167993064200, - "Uptime": 101149 - } - ``` -
-
diff --git a/website/source/docs/http/eval.html.md b/website/source/docs/http/eval.html.md deleted file mode 100644 index 5be72f146..000000000 --- a/website/source/docs/http/eval.html.md +++ /dev/null @@ -1,131 +0,0 @@ ---- -layout: "http" -page_title: "HTTP API: /v1/evaluation" -sidebar_current: "docs-http-eval-" -description: |- - The '/v1/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
-
- Query a specific evaluation. -
- -
Method
-
GET
- -
URL
-
`/v1/evaluation/`
- -
Parameters
-
- None -
- -
Blocking Queries
-
- [Supported](/docs/http/index.html#blocking-queries) -
- -
Returns
-
- - ```javascript - { - "ID": "055c0867-8bf7-5068-b3a3-d64e4e84e702", - "Priority": 50, - "Type": "service", - "TriggeredBy": "job-register", - "JobID": "example", - "JobModifyIndex": 13, - "NodeID": "", - "NodeModifyIndex": 0, - "Status": "complete", - "StatusDescription": "", - "Wait": 0, - "NextEval": "", - "PreviousEval": "", - "BlockedEval": "fee40e32-aa0f-bf5e-b2fd-b08350875fdb", - "FailedTGAllocs": { - "cache": { - "NodesEvaluated": 1, - "NodesFiltered": 0, - "NodesAvailable": { - "dc1": 1 - }, - "ClassFiltered": null, - "ConstraintFiltered": null, - "NodesExhausted": 1, - "ClassExhausted": null, - "DimensionExhausted": { - "memory exhausted": 1 - }, - "Scores": null, - "AllocationTime": 61601, - "CoalescedFailures": 2 - } - }, - "CreateIndex": 14, - "ModifyIndex": 17 - } - ``` - -
-
- -
-
Description
-
- Query the allocations created or modified by an evaluation. -
- -
Method
-
GET
- -
URL
-
`/v1/evaluation//allocations`
- -
Parameters
-
- None -
- -
Blocking Queries
-
- [Supported](/docs/http/index.html#blocking-queries) -
- -
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 deleted file mode 100644 index b843d307a..000000000 --- a/website/source/docs/http/evals.html.md +++ /dev/null @@ -1,73 +0,0 @@ ---- -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
-
-
    -
  • - prefix - optional - even-length - Filter evaluations based on an identifier prefix. -
    • -
-
- -
Blocking Queries
-
- [Supported](/docs/http/index.html#blocking-queries) -
- -
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/index.html.md b/website/source/docs/http/index.html.md deleted file mode 100644 index 37118d730..000000000 --- a/website/source/docs/http/index.html.md +++ /dev/null @@ -1,98 +0,0 @@ ---- -layout: "http" -page_title: "HTTP API" -sidebar_current: "docs-http-overview" -description: |- - Nomad has an HTTP API that can be used to programmatically use Nomad. ---- - -# HTTP API - -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 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. - -## Compressed Responses - -The HTTP API will gzip the response if the HTTP request denotes that the client accepts -gzip compression. This is achieved via the standard, `Accept-Encoding: gzip` - -## 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. diff --git a/website/source/docs/http/job.html.md b/website/source/docs/http/job.html.md deleted file mode 100644 index f201077b6..000000000 --- a/website/source/docs/http/job.html.md +++ /dev/null @@ -1,748 +0,0 @@ ---- -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 single 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 -
- -
Blocking Queries
-
- [Supported](/docs/http/index.html#blocking-queries) -
- -
Returns
-
- - ```javascript - { - "Region": "global", - "ID": "binstore-storagelocker", - "Name": "binstore-storagelocker", - "Type": "service", - "Priority": 50, - "AllAtOnce": false, - "Datacenters": [ - "us2", - "eu1" - ], - "Constraints": [ - { - "LTarget": "${attr.kernel.os}", - "RTarget": "windows", - "Operand": "=" - } - ], - "TaskGroups": [ - { - "Name": "binsl", - "Count": 5, - "Constraints": [ - { - "LTarget": "${attr.kernel.os}", - "RTarget": "linux", - "Operand": "=" - } - ], - "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": null - } - ] - }, - "Meta": null - }, - { - "Name": "storagelocker", - "Driver": "java", - "Config": { - "image": "hashicorp/storagelocker" - }, - "Constraints": [ - { - "LTarget": "${attr.kernel.arch}", - "RTarget": "amd64", - "Operand": "=" - } - ], - "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": "", - "Version": 3, - "CreateIndex": 14, - "ModifyIndex": 14 - } - ``` -
-
- -
-
Description
-
- Query all versions of a single job. -
- -
Method
-
GET
- -
URL
-
`/v1/job//versions`
- -
Parameters
-
- None -
- -
Blocking Queries
-
- [Supported](/docs/http/index.html#blocking-queries) -
- -
Returns
-
- - ```javascript - [ - { - "Region": "global", - "ID": "binstore-storagelocker", - "Version": 2, - ... - }, - { - "Region": "global", - "ID": "binstore-storagelocker", - "Version": 1, - ... - }, - { - "Region": "global", - "ID": "binstore-storagelocker", - "Version": 0, - ... - } - ] - ``` -
-
- -
-
Description
-
- Query the allocations belonging to a single job. -
- -
Method
-
GET
- -
URL
-
`/v1/job//allocations`
- -
Parameters
-
-
    -
  • - all - optional - Returns all allocations of job with the given ID including those from - past instances of the job. -
    • -
-
- -
Blocking Queries
-
- [Supported](/docs/http/index.html#blocking-queries) -
- -
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 - }, - ... - ] - ``` - -
-
- -
-
Description
-
- Query the evaluations belonging to a single job. -
- -
Method
-
GET
- -
URL
-
`/v1/job//evaluations`
- -
Parameters
-
- None -
- -
Blocking Queries
-
- [Supported](/docs/http/index.html#blocking-queries) -
- -
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 - }, - ... - ] - ``` - -
-
- -
-
Description
-
- Query the summary of a job. -
- -
Method
-
GET
- -
URL
-
`/v1/job//summary`
- -
Parameters
-
- None -
- -
Blocking Queries
-
- [Supported](/docs/http/index.html#blocking-queries) -
- -
Returns
-
- - ```javascript - { - "JobID": "example", - "Children": { - "Dead": 0, - "Running": 7, - "Pending": 2 - }, - "Summary": { - "cache": { - "Queued": 0, - "Complete": 0, - "Failed": 0, - "Running": 1, - "Starting": 0, - "Lost": 0 - } - }, - "CreateIndex": 6, - "ModifyIndex": 10 - } - ``` - -
-
- - -## 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. -
    • -
  • - EnforceIndex - optional - If EnforceIndex is set the job will only be registered if the passed - JobModifyIndex matches the current job's index. If the index is zero, - the register only occurs if the job is new. This paradigm allows - check-and-set style job updating. -
    • -
  • - JobModifyIndex - optional - The JobModifyIndex to enforce the current job is at. -
    • -
-
- -
Returns
-
- - ```javascript - { - "EvalID": "d092fdc0-e1fd-2536-67d8-43af8ca798ac", - "EvalCreateIndex": 35, - "JobModifyIndex": 34, - } - ``` - -
-
- -
-
Description
-
- Dispatch a new instance of a parameterized job. -
- -
Method
-
PUT or POST
- -
URL
-
`/v1/job//dispatch`
- -
Parameters
-
-
    -
  • - Payload - optional - A `[]byte` array encoded as a base64 string with a maximum size of 16KiB. -
    • -
  • - Meta - optional - A `map[string]string` of metadata keys to their values. -
    • -
-
- -
Returns
-
- - ```javascript - { - "Index": 13, - "JobCreateIndex": 12, - "EvalCreateIndex": 13, - "EvalID": "e5f55fac-bc69-119d-528a-1fc7ade5e02c", - "DispatchedJobID": "example/dispatch-1485408778-81644024" - } - ``` - -
-
- -
-
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, - } - ``` - -
-
- -
-
Description
-
- Invoke a dry-run of the scheduler for the job. -
- -
Method
-
PUT or POST
- -
URL
-
`/v1/job//plan`
- -
Parameters
-
-
    -
  • - Job - required - The JSON definition of the job. -
    • -
  • - Diff - optional - Whether the diff structure between the submitted and server side version - of the job should be included in the response. -
    • -
-
- -
Returns
-
- - ```javascript - { - "Index": 0, - "NextPeriodicLaunch": "0001-01-01T00:00:00Z", - "Diff": { - "Type": "Added", - "TaskGroups": [ - { - "Updates": { - "create": 1 - }, - "Type": "Added", - "Tasks": [ - { - "Type": "Added", - "Objects": [...], - "Name": "redis", - "Fields": [ - { - "Type": "Added", - "Old": "", - "New": "docker", - "Name": "Driver", - "Annotations": null - }, - { - "Type": "Added", - "Old": "", - "New": "5000000000", - "Name": "KillTimeout", - "Annotations": null - } - ], - "Annotations": [ - "forces create" - ] - } - ], - "Objects": [...], - "Name": "cache", - "Fields": [...] - } - ], - "Objects": [ - { - "Type": "Added", - "Objects": null, - "Name": "Datacenters", - "Fields": [...] - }, - { - "Type": "Added", - "Objects": null, - "Name": "Constraint", - "Fields": [...] - }, - { - "Type": "Added", - "Objects": null, - "Name": "Update", - "Fields": [...] - } - ], - "ID": "example", - "Fields": [...], - ... - ] - }, - "CreatedEvals": [ - { - "ModifyIndex": 0, - "CreateIndex": 0, - "SnapshotIndex": 0, - "AnnotatePlan": false, - "EscapedComputedClass": false, - "NodeModifyIndex": 0, - "NodeID": "", - "JobModifyIndex": 0, - "JobID": "example", - "TriggeredBy": "job-register", - "Type": "batch", - "Priority": 50, - "ID": "312e6a6d-8d01-0daf-9105-14919a66dba3", - "Status": "blocked", - "StatusDescription": "created to place remaining allocations", - "Wait": 0, - "NextEval": "", - "PreviousEval": "80318ae4-7eda-e570-e59d-bc11df134817", - "BlockedEval": "", - "FailedTGAllocs": null, - "ClassEligibility": { - "v1:7968290453076422024": true - } - } - ], - "JobModifyIndex": 0, - "FailedTGAllocs": { - "cache": { - "CoalescedFailures": 3, - "AllocationTime": 46415, - "Scores": null, - "NodesEvaluated": 1, - "NodesFiltered": 0, - "NodesAvailable": { - "dc1": 1 - }, - "ClassFiltered": null, - "ConstraintFiltered": null, - "NodesExhausted": 1, - "ClassExhausted": null, - "DimensionExhausted": { - "cpu exhausted": 1 - } - } - }, - "Annotations": { - "DesiredTGUpdates": { - "cache": { - "DestructiveUpdate": 0, - "InPlaceUpdate": 0, - "Stop": 0, - "Migrate": 0, - "Place": 11, - "Ignore": 0 - } - } - } - } - ``` - -
- -
Field Reference
-
-
    -
  • - Diff - A diff structure between the submitted job and the server side version. - The top-level object is a Job Diff which contains Task Group Diffs, - which in turn contain Task Diffs. Each of these objects then has Object - and Field Diff structures embedded. -
    • -
  • - NextPeriodicLaunch - If the job being planned is periodic, this field will include the next - launch time for the job. -
    • -
  • - CreatedEvals - A set of evaluations that were created as a result of the dry-run. These - evaluations can signify a follow-up rolling update evaluation or a - blocked evaluation. -
    • -
  • - JobModifyIndex - The JobModifyIndex of the server side version of this job. -
    • -
  • - FailedTGAllocs - A set of metrics to understand any allocation failures that occurred for - the Task Group. -
    • -
  • - Annotations - Annotations include the DesiredTGUpdates, which tracks what the - scheduler would do given enough resources for each Task Group. -
    • -
-
-
- - -
-
Description
-
- Forces a new instance of the periodic job. A new instance will be created - even if it violates the job's - [`prohibit_overlap`](/docs/job-specification/periodic.html#prohibit_overlap) settings. As - such, this should be only used to immediately run a periodic job. -
- -
Method
-
PUT or POST
- -
URL
-
`/v1/job//periodic/force`
- -
Parameters
-
- None -
- -
Returns
-
- - ```javascript - { - "EvalCreateIndex": 7, - "EvalID": "57983ddd-7fcf-3e3a-fd24-f699ccfb36f4" - } - ``` - -
-
- -## 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, - } - ``` - -
-
diff --git a/website/source/docs/http/jobs.html.md b/website/source/docs/http/jobs.html.md deleted file mode 100644 index 34f5125cc..000000000 --- a/website/source/docs/http/jobs.html.md +++ /dev/null @@ -1,104 +0,0 @@ ---- -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 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
-
-
    -
  • - prefix - optional - Filter jobs based on an identifier prefix. -
    • -
-
- -
Blocking Queries
-
- [Supported](/docs/http/index.html#blocking-queries) -
- -
Returns
-
- - ```javascript - [ - { - "ID": "binstore-storagelocker", - "Name": "binstore-storagelocker", - "Type": "service", - "Priority": 50, - "Status": "", - "StatusDescription": "", - "CreateIndex": 14, - "ModifyIndex": 14 - }, - ... - ] - ``` - -
-
- -## PUT / POST - -
-
Description
-
- Registers a new job. -
- -
Method
-
PUT or POST
- -
URL
-
`/v1/jobs`
- -
Parameters
-
-
    -
  • - Job - required - The JSON definition of the job. The general structure is given - by the [job specification](/docs/http/json-jobs.html). -
    • -
-
-
Returns
-
- - ```javascript - { - "EvalID": "d092fdc0-e1fd-2536-67d8-43af8ca798ac", - "EvalCreateIndex": 35, - "JobModifyIndex": 34, - } - ``` - -
-
diff --git a/website/source/docs/http/node.html.md b/website/source/docs/http/node.html.md deleted file mode 100644 index f716df54d..000000000 --- a/website/source/docs/http/node.html.md +++ /dev/null @@ -1,392 +0,0 @@ ---- -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 -
- -
Blocking Queries
-
- [Supported](/docs/http/index.html#blocking-queries) -
- -
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", - "memory.totalbytes": "8589934592", - "network.ip-address": "127.0.0.1", - "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": { - "CPU": 0, - "MemoryMB": 0, - "DiskMB": 0, - "IOPS": 0, - "Networks": null - }, - "Links": {}, - "Meta": {}, - "NodeClass": "", - "Drain": false, - "Status": "ready", - "StatusDescription": "", - "CreateIndex": 3, - "ModifyIndex": 4 - } - ``` - -
-
- -
-
Description
-
- Query the allocations belonging to a single node. -
- -
Method
-
GET
- -
URL
-
`/v1/node//allocations`
- -
Parameters
-
- None -
- -
Blocking Queries
-
- [Supported](/docs/http/index.html#blocking-queries) -
- -
Returns
-
- - ```javascript - [ - { - "ID": "203266e5-e0d6-9486-5e05-397ed2b184af", - "EvalID": "e68125ed-3fba-fb46-46cc-291addbc4455", - "Name": "example.cache[0]", - "NodeID": "e02b6169-83bd-9df6-69bd-832765f333eb", - "JobID": "example", - "ModifyIndex": 9, - "Resources": { - "Networks": [ - { - "DynamicPorts": [ - { - "Value": 20802, - "Label": "db" - } - ], - "ReservedPorts": null, - "MBits": 10, - "IP": "", - "CIDR": "", - "Device": "" - } - ], - "IOPS": 0, - "DiskMB": 0, - "MemoryMB": 256, - "CPU": 500 - }, - "TaskGroup": "cache", - "Job": { - "ModifyIndex": 5, - "CreateIndex": 5, - "StatusDescription": "", - "Status": "", - "Meta": null, - "Update": { - "MaxParallel": 1, - "Stagger": 1e+10 - }, - "TaskGroups": [ - { - "Meta": null, - "Tasks": [ - { - "Meta": null, - "Resources": { - "Networks": [ - { - "DynamicPorts": [ - { - "Value": 20802, - "Label": "db" - } - ], - "ReservedPorts": null, - "MBits": 0, - "IP": "127.0.0.1", - "CIDR": "", - "Device": "lo" - } - ], - "IOPS": 0, - "DiskMB": 0, - "MemoryMB": 256, - "CPU": 500 - }, - "Constraints": null, - "Services": [ - { - "Checks": [ - { - "Timeout": 2e+09, - "Interval": 1e+10, - "Protocol": "", - "Http": "", - "Script": "", - "Type": "tcp", - "Name": "alive", - "Id": "" - } - ], - "PortLabel": "db", - "Tags": [ - "global", - "cache" - ], - "Name": "example-cache-redis", - "Id": "" - } - ], - "Env": null, - "Config": { - "port_map": [ - { - "db": 6379 - } - ], - "image": "redis:latest" - }, - "Driver": "docker", - "Name": "redis" - } - ], - "RestartPolicy": { - "Delay": 2.5e+10, - "Interval": 3e+11, - "Attempts": 10 - }, - "Constraints": null, - "Count": 1, - "Name": "cache" - } - ], - "Region": "global", - "ID": "example", - "Name": "example", - "Type": "service", - "Priority": 50, - "AllAtOnce": false, - "Datacenters": [ - "dc1" - ], - "Constraints": [ - { - "Operand": "=", - "RTarget": "linux", - "LTarget": "${attr.kernel.name}" - } - ] - }, - "TaskResources": { - "redis": { - "Networks": [ - { - "DynamicPorts": [ - { - "Value": 20802, - "Label": "db" - } - ], - "ReservedPorts": null, - "MBits": 0, - "IP": "127.0.0.1", - "CIDR": "", - "Device": "lo" - } - ], - "IOPS": 0, - "DiskMB": 0, - "MemoryMB": 256, - "CPU": 500 - } - }, - "Metrics": { - "CoalescedFailures": 0, - "AllocationTime": 1590406, - "NodesEvaluated": 1, - "NodesFiltered": 0, - "ClassFiltered": null, - "ConstraintFiltered": null, - "NodesExhausted": 0, - "ClassExhausted": null, - "DimensionExhausted": null, - "Scores": { - "e02b6169-83bd-9df6-69bd-832765f333eb.binpack": 6.133651487695705 - } - }, - "DesiredStatus": "run", - "DesiredDescription": "", - "ClientStatus": "running", - "ClientDescription": "", - "TaskStates": { - "redis": { - "Events": [ - { - "KillError": "", - "Message": "", - "Signal": 0, - "ExitCode": 0, - "DriverError": "", - "Time": 1447806038427841000, - "Type": "Started" - } - ], - "State": "running" - } - }, - "CreateIndex": 7 - }, - ... - ] - ``` - -
-
- -## 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 - } - ``` - -
-
- -
-
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 deleted file mode 100644 index 8c58ed870..000000000 --- a/website/source/docs/http/nodes.html.md +++ /dev/null @@ -1,66 +0,0 @@ ---- -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
-
-
    -
  • - prefix - optional - Filter nodes based on an identifier prefix. -
    • -
-
- -
Blocking Queries
-
- [Supported](/docs/http/index.html#blocking-queries) -
- -
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/docs/http/operator.html.md b/website/source/docs/http/operator.html.md deleted file mode 100644 index 43f8ba6e3..000000000 --- a/website/source/docs/http/operator.html.md +++ /dev/null @@ -1,166 +0,0 @@ ---- -layout: "http" -page_title: "HTTP API: /v1/operator/" -sidebar_current: "docs-http-operator" -description: > - The '/v1/operator/' endpoints provides cluster-level tools for Nomad - operators. ---- - -# /v1/operator - -The Operator endpoint provides cluster-level tools for Nomad operators, such -as interacting with the Raft subsystem. This was added in Nomad 0.5.5 - -~> Use this interface with extreme caution, as improper use could lead to a - Nomad outage and even loss of data. - -See the [Outage Recovery](/guides/outage.html) guide for some examples of how -these capabilities are used. For a CLI to perform these operations manually, please -see the documentation for the [`nomad operator`](/docs/commands/operator-index.html) -command. - -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/operator/raft/configuration`
- -
Parameters
-
-
    -
  • - stale - optional - If the cluster doesn't currently have a leader an error will be - returned. You can use the `?stale` query parameter to read the Raft - configuration from any of the Nomad servers. -
    • -
-
- -
Returns
-
- - ```javascript -{ - "Servers": [ - { - "ID": "127.0.0.1:4647", - "Node": "alice", - "Address": "127.0.0.1:4647", - "Leader": true, - "Voter": true - }, - { - "ID": "127.0.0.2:4647", - "Node": "bob", - "Address": "127.0.0.2:4647", - "Leader": false, - "Voter": true - }, - { - "ID": "127.0.0.3:4647", - "Node": "carol", - "Address": "127.0.0.3:4647", - "Leader": false, - "Voter": true - } - ], - "Index": 22 -} - ``` - -
- -
Field Reference
-
- -
    -
  • - Servers - The returned `Servers` array has information about the servers in the Raft - peer configuration. See the `Server` block for a description of its fields: -
    • -
  • - Index - The `Index` value is the Raft corresponding to this configuration. The - latest configuration may not yet be committed if changes are in flight. -
    • -
- - `Server` Fields: -
    -
  • - ID - `ID` is the ID of the server. This is the same as the `Address` but may - be upgraded to a GUID in a future version of Nomad. -
    • -
  • - Node - `Node` is the node name of the server, as known to Nomad, or "(unknown)" if - the node is stale and not known. -
    • -
  • - Address - `Address` is the IP:port for the server. -
    • -
  • - Leader - `Leader` is either "true" or "false" depending on the server's role in the - Raft configuration. -
    • -
  • - Voter - `Voter` is "true" or "false", indicating if the server has a vote in the Raft - configuration. Future versions of Nomad may add support for non-voting servers. -
    • -
- -
-
- - -## DELETE - -
-
Description
-
- Remove the Nomad server with given address from the Raft configuration. The - return code signifies success or failure. -
- -
Method
-
DELETE
- -
URL
-
`/v1/operator/raft/peer`
- -
Parameters
-
-
    -
  • - address - required - The address specifies the server to remove and is given as an `IP:port`. - The port number is usually 4647, unless configured otherwise. Nothing is - required in the body of the request. -
    • -
-
- -
Returns
-
None
- -
diff --git a/website/source/docs/http/regions.html.md b/website/source/docs/http/regions.html.md deleted file mode 100644 index 5de35509c..000000000 --- a/website/source/docs/http/regions.html.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -layout: "http" -page_title: "HTTP API: /v1/regions" -sidebar_current: "docs-http-regions" -description: > - The '/v1/regions' endpoint lists the known cluster regions. ---- - -# /v1/regions - -## GET - -
-
Description
-
- Returns the known region names. -
- -
Method
-
GET
- -
URL
-
`/v1/regions`
- -
Parameters
-
- None -
- -
Returns
-
- - ```javascript - ["region1","region2"] - ``` - -
-
diff --git a/website/source/docs/http/status.html.md b/website/source/docs/http/status.html.md deleted file mode 100644 index 797d8875a..000000000 --- a/website/source/docs/http/status.html.md +++ /dev/null @@ -1,77 +0,0 @@ ---- -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/docs/http/system.html.md b/website/source/docs/http/system.html.md deleted file mode 100644 index bb372739c..000000000 --- a/website/source/docs/http/system.html.md +++ /dev/null @@ -1,62 +0,0 @@ ---- -layout: "http" -page_title: "HTTP API: /v1/system/" -sidebar_current: "docs-http-system" -description: |- - The '/1/system/' endpoints are used to for system maintenance. ---- - -# /v1/system - -The `system` endpoint is used to for system maintenance and should not be -necessary for most users. By default, the agent's local region is used; another -region can be specified using the `?region=` query parameter. - -## PUT - -
-
Description
-
- Initiate garbage collection of jobs, evals, allocations and nodes. -
- -
Method
-
PUT
- -
URL
-
`/v1/system/gc`
- -
Parameters
-
- None -
- -
Returns
-
- None -
-
- - -
-
Description
-
- Reconcile the summaries of all the registered jobs based. -
- -
Method
-
PUT
- -
URL
-
`/v1/system/reconcile/summaries`
- -
Parameters
-
- None -
- -
Returns
-
- None -
-
diff --git a/website/source/docs/http/validate.html.md b/website/source/docs/http/validate.html.md deleted file mode 100644 index 6e55053b8..000000000 --- a/website/source/docs/http/validate.html.md +++ /dev/null @@ -1,209 +0,0 @@ ---- -layout: "http" -page_title: "HTTP API: /v1/validate/" -sidebar_current: "docs-http-validate" -description: |- - The '/1/validate/' endpoints are used to for validation of objects. ---- - -# /v1/validate/job - -The `/validate/job` endpoint is to validate a Nomad job file. The local Nomad -agent forwards the request to a server. In the event a server can't be -reached the agent verifies the job file locally but skips validating driver -configurations. - -## POST - -
-
Description
-
- Validates a Nomad job file -
- -
Method
-
POST
- -
URL
-
`/v1/validate/job`
- -
Parameters
-
- None -
-
Body
-
- - ```javascript -{ - "Job": { - "Region": "global", - "ID": "example", - "ParentID": null, - "Name": "example", - "Type": "service", - "Priority": 50, - "AllAtOnce": null, - "Datacenters": [ - "dc1" - ], - "Constraints": null, - "TaskGroups": [ - { - "Name": "cache", - "Count": 1, - "Constraints": null, - "Tasks": [ - { - "Name": "mongo", - "Driver": "exec", - "User": "", - "Config": { - "args": [ - "-l", - "127.0.0.1", - "0" - ], - "command": "/bin/nc" - }, - "Constraints": null, - "Env": null, - "Services": null, - "Resources": { - "CPU": 1, - "MemoryMB": 10, - "DiskMB": null, - "IOPS": 0, - "Networks": [ - { - "Public": false, - "CIDR": "", - "ReservedPorts": null, - "DynamicPorts": [ - { - "Label": "db111", - "Value": 0 - }, - { - "Label": "http111", - "Value": 0 - } - ], - "IP": "", - "MBits": 10 - } - ] - }, - "Meta": null, - "KillTimeout": null, - "LogConfig": { - "MaxFiles": 10, - "MaxFileSizeMB": 10 - }, - "Artifacts": null, - "Vault": null, - "Templates": null, - "DispatchPayload": null - }, - { - "Name": "redis", - "Driver": "raw_exec", - "User": "", - "Config": { - "args": [ - "-l", - "127.0.0.1", - "0" - ], - "command": "/usr/bin/nc" - }, - "Constraints": null, - "Env": null, - "Services": null, - "Resources": { - "CPU": 1, - "MemoryMB": 10, - "DiskMB": null, - "IOPS": 0, - "Networks": [ - { - "Public": false, - "CIDR": "", - "ReservedPorts": null, - "DynamicPorts": [ - { - "Label": "db", - "Value": 0 - }, - { - "Label": "http", - "Value": 0 - } - ], - "IP": "", - "MBits": 10 - } - ] - }, - "Meta": null, - "KillTimeout": null, - "LogConfig": { - "MaxFiles": 10, - "MaxFileSizeMB": 10 - }, - "Artifacts": null, - "Vault": null, - "Templates": null, - "DispatchPayload": null - } - ], - "RestartPolicy": { - "Interval": 300000000000, - "Attempts": 10, - "Delay": 25000000000, - "Mode": "delay" - }, - "EphemeralDisk": { - "Sticky": null, - "Migrate": null, - "SizeMB": 300 - }, - "Meta": null - } - ], - "Update": { - "Stagger": 10000000000, - "MaxParallel": 0 - }, - "Periodic": null, - "ParameterizedJob": null, - "Payload": null, - "Meta": null, - "VaultToken": null, - "Status": null, - "StatusDescription": null, - "CreateIndex": null, - "ModifyIndex": null, - "JobModifyIndex": null - } -} - ``` - -
- - -
Returns
-
- - ```javascript -{ - "DriverConfigValidated": true, - "ValidationErrors": [ - "Task group cache validation failed: 1 error(s) occurred:\n\n* Task redis validation failed: 1 error(s) occurred:\n\n* 1 error(s) occurred:\n\n* minimum CPU value is 20; got 1" - ], - "Error": "1 error(s) occurred:\n\n* Task group cache validation failed: 1 error(s) occurred:\n\n* Task redis validation failed: 1 error(s) occurred:\n\n* 1 error(s) occurred:\n\n* minimum CPU value is 20; got 1" -} - ``` - -
-
diff --git a/website/source/docs/job-specification/template.html.md b/website/source/docs/job-specification/template.html.md index 99b427f07..51d9c53d9 100644 --- a/website/source/docs/job-specification/template.html.md +++ b/website/source/docs/job-specification/template.html.md @@ -203,7 +203,7 @@ the key name, the second part is the key's value. ## Client Configuration The `template` block has the following [client configuration -options](/docs/agent/config.html#options): +options](/docs/agent/configuration/client.html#options): * `template.allow_host_source` - Allows templates to specify their source template as an absolute path referencing host directories. Defaults to `true`. diff --git a/website/source/docs/operating-a-job/accessing-logs.html.md b/website/source/docs/operating-a-job/accessing-logs.html.md index c006bada1..577bae4f9 100644 --- a/website/source/docs/operating-a-job/accessing-logs.html.md +++ b/website/source/docs/operating-a-job/accessing-logs.html.md @@ -16,7 +16,7 @@ as simple as possible, Nomad provides: - Job specification for [log rotation](/docs/job-specification/logs.html) - CLI command for [log viewing](/docs/commands/logs.html) -- API for programatic [log access](/docs/http/client-fs.html#logs) +- API for programatic [log access](/api/client.html#stream-logs) This section will utilize the job named "docs" from the [previous sections](/docs/operating-a-job/submitting-jobs.html), but these operations diff --git a/website/source/docs/operating-a-job/resource-utilization.html.md b/website/source/docs/operating-a-job/resource-utilization.html.md index a968d2f31..26fcdd932 100644 --- a/website/source/docs/operating-a-job/resource-utilization.html.md +++ b/website/source/docs/operating-a-job/resource-utilization.html.md @@ -94,4 +94,4 @@ documentation](/docs/agent/telemetry.html). For more advanced use cases, the resource usage data is also accessible via the client's HTTP API. See the documentation of the Client's [allocation HTTP -API](/docs/http/client-allocation-stats.html). +API](/api/client.html). diff --git a/website/source/layouts/_sidebar.erb b/website/source/layouts/_sidebar.erb index 38f234513..bee68ba1e 100644 --- a/website/source/layouts/_sidebar.erb +++ b/website/source/layouts/_sidebar.erb @@ -9,6 +9,7 @@
  • Intro
  • Guides
  • Docs
    • +
  • API
  • Community
  • Security
  • Press Kit
    • diff --git a/website/source/layouts/api.erb b/website/source/layouts/api.erb new file mode 100644 index 000000000..0cf29528f --- /dev/null +++ b/website/source/layouts/api.erb @@ -0,0 +1,65 @@ +<% wrap_layout :inner do %> + <% content_for :sidebar do %> + + <% end %> + + <%= yield %> +<% end %> diff --git a/website/source/layouts/docs.erb b/website/source/layouts/docs.erb index 40b4aa873..854692613 100644 --- a/website/source/layouts/docs.erb +++ b/website/source/layouts/docs.erb @@ -291,10 +291,6 @@
    - > - HTTP API - - > Internals