From 08ce8b85f40614a73c2d3835015b961d71b92b1d Mon Sep 17 00:00:00 2001 From: Alex Dadgar Date: Tue, 25 Jul 2017 09:01:45 -0700 Subject: [PATCH 1/8] Status command --- .../source/docs/commands/status.html.md.erb | 100 ++++++++++++------ 1 file changed, 65 insertions(+), 35 deletions(-) diff --git a/website/source/docs/commands/status.html.md.erb b/website/source/docs/commands/status.html.md.erb index 5735b63ce..924754a32 100644 --- a/website/source/docs/commands/status.html.md.erb +++ b/website/source/docs/commands/status.html.md.erb @@ -43,11 +43,10 @@ List of all jobs: ``` $ nomad status -ID Type Priority Status -job1 service 3 pending -job2 service 3 running -job3 service 2 pending -job4 service 1 complete +ID Type Priority Status Submit Date +job1 service 80 running 07/25/17 15:47:11 UTC +job2 batch 40 complete 07/24/17 19:22:11 UTC +job3 service 50 dead (stopped) 07/22/17 16:34:48 UTC ``` Short view of a specific job: @@ -56,6 +55,7 @@ Short view of a specific job: $ nomad status -short job1 ID = job1 Name = Test Job +Submit Date = 07/25/17 15:47:11 UTC Type = service Priority = 3 Datacenters = dc1,dc2,dc3 @@ -67,9 +67,9 @@ Parameterized = false Full status information of a job: ``` -$ nomad status example ID = example Name = example +Submit Date = 07/25/17 15:53:04 UTC Type = service Priority = 50 Datacenters = dc1 @@ -81,9 +81,18 @@ Summary Task Group Queued Starting Running Failed Complete Lost cache 0 0 1 0 0 0 +Latest Deployment +ID = 6294be0c +Status = successful +Description = Deployment completed successfully + +Deployed +Task Group Desired Placed Healthy Unhealthy +cache 1 1 1 0 + Allocations -ID Eval ID Node ID Task Group Desired Status Created At -24cfd201 81efc2fa 8d0331e9 cache run running 08/08/16 21:03:19 CDT +ID Node ID Task Group Version Desired Status Created At +478ce836 5ed166e8 cache 0 run running 07/25/17 15:53:04 UTC ``` Full status information of a perodic job: @@ -91,25 +100,24 @@ Full status information of a perodic job: ``` ID = example Name = example +Submit Date = 07/25/17 15:59:52 UTC Type = batch Priority = 50 Datacenters = dc1 Status = running Periodic = true Parameterized = false -Next Periodic Launch = 01/26/17 06:19:46 UTC (1s from now) +Next Periodic Launch = 07/25/17 16:00:30 UTC (5s from now) Children Job Summary Pending Running Dead -0 5 0 +0 3 0 Previously Launched Jobs ID Status -example/periodic-1485411581 running -example/periodic-1485411582 running -example/periodic-1485411583 running -example/periodic-1485411584 running -example/periodic-1485411585 running +example/periodic-1500998400 running +example/periodic-1500998410 running +example/periodic-1500998420 running ``` Full status information of a parameterized job: @@ -117,6 +125,7 @@ Full status information of a parameterized job: ``` ID = example Name = example +Submit Date = 07/25/17 15:59:52 UTC Type = batch Priority = 50 Datacenters = dc1 @@ -142,9 +151,9 @@ example/dispatch-1485411499-fa2ee40e running Full status information of a job with placement failures: ``` -$ nomad status example ID = example Name = example +Submit Date = 07/25/17 15:55:27 UTC Type = service Priority = 50 Datacenters = dc1 @@ -154,20 +163,28 @@ Parameterized = false Summary Task Group Queued Starting Running Failed Complete Lost -cache 0 0 5 0 0 0 +cache 1 0 4 0 0 0 Placement Failure Task Group "cache": * Resources exhausted on 1 nodes * Dimension "cpu exhausted" exhausted on 1 nodes +Latest Deployment +ID = bb4b2fb1 +Status = running +Description = Deployment is running + +Deployed +Task Group Desired Placed Healthy Unhealthy +cache 5 4 4 0 + Allocations -ID Eval ID Node ID Task Group Desired Status Created At -0b8b9e37 8bf94335 8d0331e9 cache run running 08/08/16 21:03:19 CDT -b206088c 8bf94335 8d0331e9 cache run running 08/08/16 21:03:18 CDT -b82f58b6 8bf94335 8d0331e9 cache run running 08/08/16 21:03:17 CDT -ed3665f5 8bf94335 8d0331e9 cache run running 08/08/16 21:03:21 CDT -24cfd201 8bf94335 8d0331e9 cache run running 08/08/16 21:03:19 CDT +ID Node ID Task Group Version Desired Status Created At +048c1e9e 3f38ecb4 cache 0 run running 07/25/17 15:55:27 UTC +250f9dec 3f38ecb4 cache 0 run running 07/25/17 15:55:27 UTC +2eb772a1 3f38ecb4 cache 0 run running 07/25/17 15:55:27 UTC +a17b7d3d 3f38ecb4 cache 0 run running 07/25/17 15:55:27 UTC ``` Full status information showing evaluations with a placement failure. The in @@ -178,6 +195,7 @@ become availables so that it can place the remaining allocations. $ nomad status -evals example ID = example Name = example +Submit Date = 07/25/17 15:55:27 UTC Type = service Priority = 50 Datacenters = dc1 @@ -187,25 +205,37 @@ Parameterized = false Summary Task Group Queued Starting Running Failed Complete Lost -cache 0 0 5 0 0 0 +cache 1 0 4 0 0 0 Evaluations -ID Priority Triggered By Status Placement Failures -69f34a37 50 job-register blocked N/A - In Progress -8bf94335 50 job-register complete true -df79bec7 50 job-register complete false -81efc2fa 50 job-register complete false +ID Priority Triggered By Status Placement Failures +e44a39e8 50 deployment-watcher canceled false +97018573 50 deployment-watcher complete true +d5a7300c 50 deployment-watcher canceled false +f05a4495 50 deployment-watcher complete true +e3f3bdb4 50 deployment-watcher canceled false +b5f08700 50 deployment-watcher complete true +73bb867a 50 job-register blocked N/A - In Progress +85052989 50 job-register complete true Placement Failure Task Group "cache": * Resources exhausted on 1 nodes * Dimension "cpu exhausted" exhausted on 1 nodes +Latest Deployment +ID = bb4b2fb1 +Status = running +Description = Deployment is running + +Deployed +Task Group Desired Placed Healthy Unhealthy +cache 5 4 4 0 + Allocations -ID Eval ID Node ID Task Group Desired Status Created At -0b8b9e37 8bf94335 8d0331e9 cache run running 08/08/16 21:03:19 CDT -b206088c 8bf94335 8d0331e9 cache run running 08/08/16 21:03:19 CDT -b82f58b6 8bf94335 8d0331e9 cache run running 08/08/16 21:03:19 CDT -ed3665f5 8bf94335 8d0331e9 cache run running 08/08/16 21:03:19 CDT -24cfd201 8bf94335 8d0331e9 cache run running 08/08/16 21:03:19 CDT +ID Node ID Task Group Version Desired Status Created At +048c1e9e 3f38ecb4 cache 0 run running 07/25/17 15:55:27 UTC +250f9dec 3f38ecb4 cache 0 run running 07/25/17 15:55:27 UTC +2eb772a1 3f38ecb4 cache 0 run running 07/25/17 15:55:27 UTC +a17b7d3d 3f38ecb4 cache 0 run running 07/25/17 15:55:27 UTC ``` From 5a2578eefe78a4de0bbbe0fe3c1035f176a45311 Mon Sep 17 00:00:00 2001 From: Alex Dadgar Date: Tue, 25 Jul 2017 09:15:31 -0700 Subject: [PATCH 2/8] alloc-status --- .../docs/commands/alloc-status.html.md.erb | 108 +++++++++--------- .../source/docs/commands/status.html.md.erb | 4 + 2 files changed, 58 insertions(+), 54 deletions(-) diff --git a/website/source/docs/commands/alloc-status.html.md.erb b/website/source/docs/commands/alloc-status.html.md.erb index f7b3b6de0..793394639 100644 --- a/website/source/docs/commands/alloc-status.html.md.erb +++ b/website/source/docs/commands/alloc-status.html.md.erb @@ -39,134 +39,134 @@ allocations and information will be displayed. Short status of an alloc: ``` -$ nomad alloc-status --short 13901f26 -ID = 13901f26 -Eval ID = c3c9a1db -Name = example.cache[0] -Node ID = 1f029d38 -Job ID = example -Client Status = running -Created At = 29/03/16 03:04:53 UTC +$ nomad alloc-status --short 0af996ed +ID = 0af996ed +Eval ID = be9bde98 +Name = example.cache[0] +Node ID = 43c0b14e +Job ID = example +Job Version = 0 +Client Status = running +Client Description = +Desired Status = run +Desired Description = +Created At = 07/25/17 16:12:48 UTC +Deployment ID = 0c83a3b1 +Deployment Health = healthy -==> Tasks +Tasks Name State Last Event Time -redis running Started 29/03/16 03:04:53 UTC -web running Started 29/03/16 03:04:53 UTC +redis running Started 07/25/17 16:12:48 UTC +web running Started 07/25/17 16:12:49 UTC ``` Full status of an alloc, which shows one of the tasks dying and then being restarted: ``` -$ nomad alloc-status cfe85e72 -ID = cfe85e72 -Eval ID = cdc88569 +$ nomad alloc-status 0af996ed +ID = 0af996ed +Eval ID = be9bde98 Name = example.cache[0] -Node ID = bfd3aa86 +Node ID = 43c0b14e Job ID = example -Job Version = 1 +Job Version = 0 Client Status = running Client Description = Desired Status = run Desired Description = -Created At = 07/25/17 23:42:01 UTC -Deployment ID = dd162708 -Deployment Health = unset -Canary = true +Created At = 07/25/17 16:12:48 UTC +Deployment ID = 0c83a3b1 +Deployment Health = healthy Task "redis" is "running" Task Resources CPU Memory Disk IOPS Addresses -4/500 MHz 6.3 MiB/256 MiB 300 MiB 0 db: 127.0.0.1:20055 +1/500 MHz 6.3 MiB/256 MiB 300 MiB 0 db: 127.0.0.1:27908 Task Events: -Started At = 07/25/17 23:42:02 UTC +Started At = 07/25/17 16:12:48 UTC Finished At = N/A Total Restarts = 0 Last Restart = N/A Recent Events: Time Type Description -07/25/17 23:42:02 UTC Started Task started by client -07/25/17 23:42:01 UTC Task Setup Building Task Directory -07/25/17 23:42:01 UTC Received Task received by client +07/25/17 16:12:48 UTC Started Task started by client +07/25/17 16:12:48 UTC Task Setup Building Task Directory +07/25/17 16:12:48 UTC Received Task received by client Task "web" is "running" Task Resources CPU Memory Disk IOPS Addresses -5/500 MHz 6.3 MiB/256 MiB 300 MiB 0 db: 127.0.0.1:28235 +1/500 MHz 6.3 MiB/256 MiB 300 MiB 0 db: 127.0.0.1:30572 Task Events: -Started At = 07/25/17 23:42:02 UTC +Started At = 07/25/17 16:12:49 UTC +>>>>>>> alloc-status Finished At = N/A Total Restarts = 0 Last Restart = N/A Recent Events: -Time Type Description -07/25/17 23:42:02 UTC Started Task started by client -07/25/17 23:42:01 UTC Task Setup Building Task Directory -07/25/17 23:42:01 UTC Received Task received by client +07/25/17 16:12:49 UTC Started Task started by client +07/25/17 16:12:48 UTC Task Setup Building Task Directory +07/25/17 16:12:48 UTC Received Task received by client ``` Verbose status can also be accessed: ``` -$ nomad alloc-status --verbose cfe85e72 -ID = cfe85e72-220e-cb14-edfc-432602ac0981 -Eval ID = cdc88569-bbc3-5549-855f-c0db59d4d4d3 +$ nomad alloc-status -verbose 0af996ed +ID = 0af996ed-aff4-8ddb-a566-e55ebf8969c9 +Eval ID = be9bde98-0490-1beb-ced0-012d10ddf22e Name = example.cache[0] -Node ID = bfd3aa86-ecbf-0f6c-b234-0f4d35792543 +Node ID = 43c0b14e-7f96-e432-a7da-06605257ce0c Job ID = example -Job Version = 1 +Job Version = 0 Client Status = running Client Description = Desired Status = run Desired Description = -Created At = 07/25/17 23:42:01 UTC -Deployment ID = dd162708-d810-a761-53b9-cfb1dc8637e8 +Created At = 07/25/17 16:12:48 UTC +Deployment ID = 0c83a3b1-8a7b-136b-0e11-8383dc6c9276 Deployment Health = healthy -Canary = true Evaluated Nodes = 1 Filtered Nodes = 0 Exhausted Nodes = 0 -Allocation Time = 152.016µs +Allocation Time = 38.474µs Failures = 0 Task "redis" is "running" Task Resources CPU Memory Disk IOPS Addresses -2/500 MHz 6.3 MiB/256 MiB 300 MiB 0 db: 127.0.0.1:20055 +1/500 MHz 6.3 MiB/256 MiB 300 MiB 0 db: 127.0.0.1:27908 Task Events: -Started At = 07/25/17 23:42:02 UTC +Started At = 07/25/17 16:12:48 UTC Finished At = N/A Total Restarts = 0 Last Restart = N/A Recent Events: Time Type Description -07/25/17 23:42:02 UTC Started Task started by client -07/25/17 23:42:01 UTC Task Setup Building Task Directory -07/25/17 23:42:01 UTC Received Task received by client +07/25/17 16:12:48 UTC Started Task started by client +07/25/17 16:12:48 UTC Task Setup Building Task Directory +07/25/17 16:12:48 UTC Received Task received by client Task "web" is "running" Task Resources CPU Memory Disk IOPS Addresses -4/500 MHz 6.3 MiB/256 MiB 300 MiB 0 db: 127.0.0.1:28235 +1/500 MHz 6.3 MiB/256 MiB 300 MiB 0 db: 127.0.0.1:30572 Task Events: -Started At = 07/25/17 23:42:02 UTC +Started At = 07/25/17 16:12:49 UTC Finished At = N/A Total Restarts = 0 Last Restart = N/A Recent Events: Time Type Description -07/25/17 23:42:02 UTC Started Task started by client -07/25/17 23:42:01 UTC Task Setup Building Task Directory -07/25/17 23:42:01 UTC Received Task received by client - -Placement Metrics - * Score "bfd3aa86-ecbf-0f6c-b234-0f4d35792543.binpack" = 9.142490 - * Score "bfd3aa86-ecbf-0f6c-b234-0f4d35792543.job-anti-affinity" = -20.000000 +07/25/17 16:12:49 UTC Started Task started by client +07/25/17 16:12:48 UTC Task Setup Building Task Directory +07/25/17 16:12:48 UTC Received Task received by client ``` diff --git a/website/source/docs/commands/status.html.md.erb b/website/source/docs/commands/status.html.md.erb index 924754a32..3a7f8c317 100644 --- a/website/source/docs/commands/status.html.md.erb +++ b/website/source/docs/commands/status.html.md.erb @@ -67,6 +67,7 @@ Parameterized = false Full status information of a job: ``` +$ nomad status example ID = example Name = example Submit Date = 07/25/17 15:53:04 UTC @@ -98,6 +99,7 @@ ID Node ID Task Group Version Desired Status Created At Full status information of a perodic job: ``` +$ nomad status example ID = example Name = example Submit Date = 07/25/17 15:59:52 UTC @@ -123,6 +125,7 @@ example/periodic-1500998420 running Full status information of a parameterized job: ``` +$ nomad status example ID = example Name = example Submit Date = 07/25/17 15:59:52 UTC @@ -151,6 +154,7 @@ example/dispatch-1485411499-fa2ee40e running Full status information of a job with placement failures: ``` +$ nomad status example ID = example Name = example Submit Date = 07/25/17 15:55:27 UTC From f8b9fc41240b35b633e16da4f8c012e29fa58980 Mon Sep 17 00:00:00 2001 From: Alex Dadgar Date: Tue, 25 Jul 2017 09:20:19 -0700 Subject: [PATCH 3/8] Fix eval-status bug --- command/eval_status.go | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/command/eval_status.go b/command/eval_status.go index bdd6063e6..f2891b316 100644 --- a/command/eval_status.go +++ b/command/eval_status.go @@ -229,7 +229,7 @@ func sortedTaskGroupFromMetrics(groups map[string]*api.AllocationMetric) []strin func getTriggerDetails(eval *api.Evaluation) (noun, subject string) { switch eval.TriggeredBy { - case "job-register", "job-deregister", "periodic-job", "rolling-update": + case "job-register", "job-deregister", "periodic-job", "rolling-update", "deployment-watcher": return "Job ID", eval.JobID case "node-update": return "Node ID", eval.NodeID From a271b8fc22d272a69c2782f463c8eb05aef52191 Mon Sep 17 00:00:00 2001 From: Alex Dadgar Date: Tue, 25 Jul 2017 09:23:44 -0700 Subject: [PATCH 4/8] inspect --- command/inspect.go | 2 +- website/source/docs/commands/alloc-status.html.md.erb | 2 +- website/source/docs/commands/inspect.html.md.erb | 7 ++++--- 3 files changed, 6 insertions(+), 5 deletions(-) diff --git a/command/inspect.go b/command/inspect.go index 449ff63d9..382d98222 100644 --- a/command/inspect.go +++ b/command/inspect.go @@ -24,7 +24,7 @@ General Options: Inspect Options: -version - Display only the history for the given job version. + Display the job at the given job version. -json Output the job in its JSON format. diff --git a/website/source/docs/commands/alloc-status.html.md.erb b/website/source/docs/commands/alloc-status.html.md.erb index 793394639..ce61f963d 100644 --- a/website/source/docs/commands/alloc-status.html.md.erb +++ b/website/source/docs/commands/alloc-status.html.md.erb @@ -32,7 +32,7 @@ allocations and information will be displayed. * `-short`: Display short output. Shows only the most recent task event. * `-verbose`: Show full information. * `-json` : Output the allocation in its JSON format. -* `-t` : Format and display allocation using a Go template. +* `-t` : Format and display the allocation using a Go template. ## Examples diff --git a/website/source/docs/commands/inspect.html.md.erb b/website/source/docs/commands/inspect.html.md.erb index ae9b8f8d3..ebe2e3741 100644 --- a/website/source/docs/commands/inspect.html.md.erb +++ b/website/source/docs/commands/inspect.html.md.erb @@ -27,10 +27,11 @@ version of a job Nomad is running. ## Inspect Options -* `-short`: Display short output. Used only when a single node is being queried. - Drops verbose node allocation data from the output. +* `-version`: Display only the job at the given job version. -* `-verbose`: Show full information. +* `-json` : Output the job in its JSON format. + +* `-t` : Format and display the job using a Go template. ## Examples From 797fc81012c4e572368ef5c98eb5db35c7d0c689 Mon Sep 17 00:00:00 2001 From: Alex Dadgar Date: Tue, 25 Jul 2017 09:37:09 -0700 Subject: [PATCH 5/8] validate --- website/source/docs/commands/run.html.md.erb | 3 ++ .../source/docs/commands/validate.html.md.erb | 28 +++++++++++++++++++ 2 files changed, 31 insertions(+) diff --git a/website/source/docs/commands/run.html.md.erb b/website/source/docs/commands/run.html.md.erb index 5ba1a93de..a378d87dd 100644 --- a/website/source/docs/commands/run.html.md.erb +++ b/website/source/docs/commands/run.html.md.erb @@ -79,6 +79,8 @@ Schedule the job contained in the file `job1.nomad`, monitoring placement: ``` $ nomad run job1.nomad ==> Monitoring evaluation "52dee78a" + Evaluation triggered by job "example" + Evaluation within deployment: "62eb607c" Allocation "5e0b39f0" created: node "3e84d3d2", group "group1" Allocation "5e0b39f0" status changed: "pending" -> "running" Evaluation status changed: "pending" -> "complete" @@ -95,6 +97,7 @@ Job not updated $ nomad run -check-index 6 example.nomad ==> Monitoring evaluation "5ef16dff" Evaluation triggered by job "example" + Evaluation within deployment: "62eb607c" Allocation "6ec7d16f" modified: node "6e1f9bf6", group "cache" Evaluation status changed: "pending" -> "complete" ==> Evaluation "5ef16dff" finished with status "complete" diff --git a/website/source/docs/commands/validate.html.md.erb b/website/source/docs/commands/validate.html.md.erb index 7383e8552..7988544c3 100644 --- a/website/source/docs/commands/validate.html.md.erb +++ b/website/source/docs/commands/validate.html.md.erb @@ -27,3 +27,31 @@ and supports `go-getter` syntax. On successful validation, exit code 0 will be returned, otherwise an exit code of 1 indicates an error. + +## Examples + +Validate a job with invalid syntax: + +``` +$ nomad validate example.nomad +Job validation errors: +1 error(s) occurred: + +* group "cache" -> task "redis" -> config: 1 error(s) occurred: + +* field "image" is required +``` + +Validate a job that has a configuration that causes warnings: + +``` +$ nomad validate example.nomad +Job Warnings: +1 warning(s): + +* Group "cache" has warnings: 1 error(s) occurred: + +* Update max parallel count is greater than task group count (6 > 3). A destructive change would result in the simultaneous replacement of all allocations. + +Job validation successful +``` From e0beda704a0450f2d54318b0e8803e3148ba272a Mon Sep 17 00:00:00 2001 From: Alex Dadgar Date: Tue, 25 Jul 2017 11:18:21 -0700 Subject: [PATCH 6/8] New commands docs and small fixes This PR adds the command documentations and has small CLI fixes. --- command/deployment_fail.go | 6 +- command/deployment_promote.go | 10 +- command/deployment_resume.go | 6 +- command/deployment_status.go | 6 +- command/job_promote.go | 10 +- website/redirects.txt | 7 +- .../docs/commands/deployment.html.md.erb | 34 +++ .../docs/commands/deployment/fail.html.md.erb | 61 +++++ .../docs/commands/deployment/list.html.md.erb | 43 ++++ .../commands/deployment/pause.html.md.erb | 40 ++++ .../commands/deployment/promote.html.md.erb | 221 ++++++++++++++++++ .../commands/deployment/resume.html.md.erb | 52 +++++ .../commands/deployment/status.html.md.erb | 68 ++++++ website/source/docs/commands/job.html.md.erb | 32 +++ .../docs/commands/job/deployments.html.md.erb | 47 ++++ .../dispatch.html.md.erb} | 6 +- .../docs/commands/job/history.html.md.erb | 85 +++++++ .../docs/commands/job/promote.html.md.erb | 221 ++++++++++++++++++ .../docs/commands/job/revert.html.md.erb | 94 ++++++++ website/source/docs/commands/run.html.md.erb | 2 - website/source/layouts/docs.erb | 44 +++- 21 files changed, 1066 insertions(+), 29 deletions(-) create mode 100644 website/source/docs/commands/deployment.html.md.erb create mode 100644 website/source/docs/commands/deployment/fail.html.md.erb create mode 100644 website/source/docs/commands/deployment/list.html.md.erb create mode 100644 website/source/docs/commands/deployment/pause.html.md.erb create mode 100644 website/source/docs/commands/deployment/promote.html.md.erb create mode 100644 website/source/docs/commands/deployment/resume.html.md.erb create mode 100644 website/source/docs/commands/deployment/status.html.md.erb create mode 100644 website/source/docs/commands/job.html.md.erb create mode 100644 website/source/docs/commands/job/deployments.html.md.erb rename website/source/docs/commands/{job-dispatch.html.md.erb => job/dispatch.html.md.erb} (94%) create mode 100644 website/source/docs/commands/job/history.html.md.erb create mode 100644 website/source/docs/commands/job/promote.html.md.erb create mode 100644 website/source/docs/commands/job/revert.html.md.erb diff --git a/command/deployment_fail.go b/command/deployment_fail.go index fe808feea..759254e9e 100644 --- a/command/deployment_fail.go +++ b/command/deployment_fail.go @@ -25,9 +25,9 @@ General Options: Fail Options: -detach - Return immediately instead of entering monitor mode. After deployment - resume, the evaluation ID will be printed to the screen, which can be used - to examine the evaluation using the eval-status command. + Return immediately instead of entering monitor mode. After deployment + resume, the evaluation ID will be printed to the screen, which can be used + to examine the evaluation using the eval-status command. -verbose Display full information. diff --git a/command/deployment_promote.go b/command/deployment_promote.go index a549ea52c..15288bcf5 100644 --- a/command/deployment_promote.go +++ b/command/deployment_promote.go @@ -31,13 +31,13 @@ General Options: Promote Options: -group - Group may be specified many times and is used to promote that particular - group. If no specific groups are specified, all groups are promoted. + Group may be specified many times and is used to promote that particular + group. If no specific groups are specified, all groups are promoted. -detach - Return immediately instead of entering monitor mode. After deployment - resume, the evaluation ID will be printed to the screen, which can be used - to examine the evaluation using the eval-status command. + Return immediately instead of entering monitor mode. After deployment + resume, the evaluation ID will be printed to the screen, which can be used + to examine the evaluation using the eval-status command. -verbose Display full information. diff --git a/command/deployment_resume.go b/command/deployment_resume.go index e41ee9e24..47a599fc6 100644 --- a/command/deployment_resume.go +++ b/command/deployment_resume.go @@ -23,9 +23,9 @@ General Options: Resume Options: -detach - Return immediately instead of entering monitor mode. After deployment - resume, the evaluation ID will be printed to the screen, which can be used - to examine the evaluation using the eval-status command. + Return immediately instead of entering monitor mode. After deployment + resume, the evaluation ID will be printed to the screen, which can be used + to examine the evaluation using the eval-status command. -verbose Display full information. diff --git a/command/deployment_status.go b/command/deployment_status.go index efa086012..c8093d960 100644 --- a/command/deployment_status.go +++ b/command/deployment_status.go @@ -195,7 +195,11 @@ func formatDeploymentGroups(d *api.Deployment, uuidLength int) string { row += fmt.Sprintf("%v|", state.AutoRevert) } if canaries { - row += fmt.Sprintf("%v|", state.Promoted) + if state.DesiredCanaries > 0 { + row += fmt.Sprintf("%v|", state.Promoted) + } else { + row += fmt.Sprintf("%v|", "N/A") + } } row += fmt.Sprintf("%d|", state.DesiredTotal) if canaries { diff --git a/command/job_promote.go b/command/job_promote.go index 1cfdfb9b5..fc101bf40 100644 --- a/command/job_promote.go +++ b/command/job_promote.go @@ -32,13 +32,13 @@ General Options: Promote Options: -group - Group may be specified many times and is used to promote that particular - group. If no specific groups are specified, all groups are promoted. + Group may be specified many times and is used to promote that particular + group. If no specific groups are specified, all groups are promoted. -detach - Return immediately instead of entering monitor mode. After deployment - resume, the evaluation ID will be printed to the screen, which can be used - to examine the evaluation using the eval-status command. + Return immediately instead of entering monitor mode. After deployment + resume, the evaluation ID will be printed to the screen, which can be used + to examine the evaluation using the eval-status command. -verbose Display full information. diff --git a/website/redirects.txt b/website/redirects.txt index f625c56a0..e87d06b18 100644 --- a/website/redirects.txt +++ b/website/redirects.txt @@ -60,6 +60,10 @@ /docs/cluster/manual.html /guides/cluster/manual.html /docs/cluster/federation.html /guides/cluster/federation.html /docs/cluster/requirements.html /guides/cluster/requirements.html +/docs/commands/operator-index.html /docs/commands/operator.html +/docs/commands/operator-raft-list-peers.html /docs/commands/operator/raft-list-peers.html +/docs/commands/operator-raft-remove-peer.html /docs/commands/operator/raft-remove-peer.html +/docs/commands/job-dispatch.html /docs/commands/job/dispatch.html # API /docs/http/index.html /api/index.html @@ -84,6 +88,3 @@ /docs/http/status.html /api/status.html /docs/http/operator.html /api/operator.html /docs/http/system.html /api/system.html -/docs/commands/operator-index.html /docs/commands/operator.html -/docs/commands/operator-raft-list-peers.html /docs/commands/operator/raft-list-peers.html -/docs/commands/operator-raft-remove-peer.html /docs/commands/operator/raft-remove-peer.html diff --git a/website/source/docs/commands/deployment.html.md.erb b/website/source/docs/commands/deployment.html.md.erb new file mode 100644 index 000000000..39ba2a94f --- /dev/null +++ b/website/source/docs/commands/deployment.html.md.erb @@ -0,0 +1,34 @@ +--- +layout: "docs" +page_title: "Commands: deployment" +sidebar_current: "docs-commands-deployment" +description: > + The deployment command is used to interact with deployments. +--- + +# Nomad Deployment + +Command: `nomad deployment` + +The `deployment` command is used to interact with deployments. + +## Usage + +Usage: `nomad deployment [options]` + +Run `nomad deployment -h` for help on that subcommand. The following +subcommands are available: + +* [`deployment fail`][fail] - Manually fail a deployment +* [`deployment list`][list] - List all deployments +* [`deployment pause`][pause] - Pause a deployment +* [`deployment promote`][promote] - Promote canaries in a deployment +* [`deployment resume`][resume] - Resume a paused deployment +* [`deployment status`][status] - Display the status of a deployment + +[fail]: /docs/commands/deployment/fail.html "Manually fail a deployment" +[list]: /docs/commands/deployment/list.html "List all deployments" +[pause]: /docs/commands/deployment/pause.html "Pause a deployment" +[promote]: /docs/commands/deployment/promote.html "Promote canaries in a deployment" +[resume]: /docs/commands/deployment/resume.html "Resume a paused deployment" +[status]: /docs/commands/deployment/status.html "Display the status of a deployment" diff --git a/website/source/docs/commands/deployment/fail.html.md.erb b/website/source/docs/commands/deployment/fail.html.md.erb new file mode 100644 index 000000000..4429065ac --- /dev/null +++ b/website/source/docs/commands/deployment/fail.html.md.erb @@ -0,0 +1,61 @@ +--- +layout: "docs" +page_title: "Commands: deployment fail" +sidebar_current: "docs-commands-deployment-fail" +description: > + The deployment fail command is used to manually fail a deployment. +--- + +# Command: deployment fail + +The `deployment fail` command is used to mark a deployment as failed. Failing a +deployment will stop the placement of new allocations as part of rolling +deployment and if the job is configured to auto revert, the job will attempt to +roll back to a stable version. + +## Usage + +``` +nomad deployment fail [options] +``` + +The `deployment fail` command requires a single argument, a deployment ID or +prefix. + +## General Options + +<%= partial "docs/commands/_general_options" %> + +## Fail Options + +* `-detach`: Return immediately instead of monitoring. A new evaluation ID + will be output, which can be used to examine the evaluation using the + [eval-status](/docs/commands/eval-status.html) command + +* `-verbose`: Show full information. + +## Examples + +Manually mark an ongoing deployment as failed: + +``` +$ nomad deployment fail 8990cfbc +Deployment "8990cfbc-28c0-cb28-ca31-856cf691b987" failed + +==> Monitoring evaluation "a2d97ad5" + Evaluation triggered by job "example" + Evaluation within deployment: "8990cfbc" + Evaluation status changed: "pending" -> "complete" +==> Evaluation "a2d97ad5" finished with status "complete" + +$ nomad deployment status 8990cfbc +ID = 8990cfbc +Job ID = example +Job Version = 2 +Status = failed +Description = Deployment marked as failed + +Deployed +Task Group Desired Placed Healthy Unhealthy +cache 3 2 1 0 +``` diff --git a/website/source/docs/commands/deployment/list.html.md.erb b/website/source/docs/commands/deployment/list.html.md.erb new file mode 100644 index 000000000..683a2d19d --- /dev/null +++ b/website/source/docs/commands/deployment/list.html.md.erb @@ -0,0 +1,43 @@ +--- +layout: "docs" +page_title: "Commands: deployment list" +sidebar_current: "docs-commands-deployment-list" +description: > + The deployment list command is used to list deployments. +--- + +# Command: deployment list + +The `deployment list` command is used list all deployments. + +## Usage + +``` +nomad deployment list [options] +``` + +The `deployment list` command requires no arguments. + +## General Options + +<%= partial "docs/commands/_general_options" %> + +## List Options + +* `-json` : Output the deployments in their JSON format. + +* `-t` : Format and display the deployments using a Go template. + +* `-verbose`: Show full information. + +## Examples + +List all tracked deployments: + +``` +$ nomad deployment list +ID Job ID Job Version Status Description +8990cfbc example 2 failed Deployment marked as failed +62eb607c example 1 successful Deployment completed successfully +5f271fe2 example 0 successful Deployment completed successfully +``` diff --git a/website/source/docs/commands/deployment/pause.html.md.erb b/website/source/docs/commands/deployment/pause.html.md.erb new file mode 100644 index 000000000..f218b924e --- /dev/null +++ b/website/source/docs/commands/deployment/pause.html.md.erb @@ -0,0 +1,40 @@ +--- +layout: "docs" +page_title: "Commands: deployment pause" +sidebar_current: "docs-commands-deployment-pause" +description: > + The deployment pause command is used to pause a deployment and disallow new + placements. +--- + +# Command: deployment pause + +The `deployment pause` command is used to pause a deployment. Pausing a +deployment will pause the placement of new allocations as part of rolling +deployment. + +## Usage + +``` +nomad deployment pause [options] +``` + +The `deployment pause` command requires a single argument, a deployment ID or +prefix. + +## General Options + +<%= partial "docs/commands/_general_options" %> + +## Pause Options + +* `-verbose`: Show full information. + +## Examples + +Manually pause a deployment: + +``` +$ nomad deployment pause 2f14ba55 +Deployment "2f14ba55-acfb-cb31-821c-facf1b9b0830" paused +``` diff --git a/website/source/docs/commands/deployment/promote.html.md.erb b/website/source/docs/commands/deployment/promote.html.md.erb new file mode 100644 index 000000000..e42b3aa88 --- /dev/null +++ b/website/source/docs/commands/deployment/promote.html.md.erb @@ -0,0 +1,221 @@ +--- +layout: "docs" +page_title: "Commands: deployment promote" +sidebar_current: "docs-commands-deployment-promote" +description: > + The deployment promote command is used to promote canaries in a deployment. +--- + +# Command: deployment promote + +The `deployment promote` command is used to promote task groups in a deployment. +Promotion should occur when the deployment has placed canaries for a task group +and those canaries have been deemed healthy. When a task group is promoted, the +rolling upgrade of the remaining allocations is unblocked. If the canaries are +found to be unhealthy, the deployment may either be failed using the "nomad +deployment fail" command, the job can be failed forward by submitting a new +version or failed backwards by reverting to an older version using the [`job +revert`](/docs/commands/job-revert.html) command. + +## Usage + +``` +nomad deployment promote [options] +``` + +The `deployment promote` command requires a single argument, a deployment ID or +prefix. When run without specifying any groups to promote, the promote command +promotes all task groups. The group flag can be specified multiple times to +select particular groups to promote. + +## General Options + +<%= partial "docs/commands/_general_options" %> + +## Promote Options + +* `-group`: Group may be specified many times and is used to promote that + particular group. If no specific groups are specified, all groups are + promoted. + +* `-detach`: Return immediately instead of monitoring. A new evaluation ID + will be output, which can be used to examine the evaluation using the + [eval-status](/docs/commands/eval-status.html) command + +* `-verbose`: Show full information. + +## Examples + +Promote canaries in all groups: + +``` +# Have two task groups waiting for promotion. +$ nomad status example +ID = example +Name = example +Submit Date = 07/25/17 18:35:05 UTC +Type = service +Priority = 50 +Datacenters = dc1 +Status = running +Periodic = false +Parameterized = false + +Summary +Task Group Queued Starting Running Failed Complete Lost +cache 0 0 3 0 0 0 +web 0 0 3 0 0 0 + +Latest Deployment +ID = 9fa81f27 +Status = running +Description = Deployment is running but requires promotion + +Deployed +Task Group Promoted Desired Canaries Placed Healthy Unhealthy +web false 2 1 1 0 0 +cache false 2 1 1 0 0 + +Allocations +ID Node ID Task Group Version Desired Status Created At +091377e5 a8dcce2d web 1 run running 07/25/17 18:35:05 UTC +d2b13584 a8dcce2d cache 1 run running 07/25/17 18:35:05 UTC +4bb185b7 a8dcce2d web 0 run running 07/25/17 18:31:34 UTC +9b6811ee a8dcce2d cache 0 run running 07/25/17 18:31:34 UTC +e0a2441b a8dcce2d cache 0 run running 07/25/17 18:31:34 UTC +f2409f7d a8dcce2d web 0 run running 07/25/17 18:31:34 UTC + +# Promote all groups within the deployment +$ nomad deployment promote 9fa81f27 +==> Monitoring evaluation "6c6e64ae" + Evaluation triggered by job "example" + Evaluation within deployment: "9fa81f27" + Allocation "8fa21654" created: node "a8dcce2d", group "web" + Allocation "9f6727a6" created: node "a8dcce2d", group "cache" + Evaluation status changed: "pending" -> "complete" +==> Evaluation "6c6e64ae" finished with status "complete" + +# Inspect the status and see both groups have been promoted. +$ nomad status example +ID = example +Name = example +Submit Date = 07/25/17 18:35:05 UTC +Type = service +Priority = 50 +Datacenters = dc1 +Status = running +Periodic = false +Parameterized = false + +Summary +Task Group Queued Starting Running Failed Complete Lost +cache 0 0 2 0 2 0 +web 0 0 2 0 2 0 + +Latest Deployment +ID = 9fa81f27 +Status = successful +Description = Deployment completed successfully + +Deployed +Task Group Promoted Desired Canaries Placed Healthy Unhealthy +web true 2 1 2 2 0 +cache true 2 1 2 2 0 + +Allocations +ID Node ID Task Group Version Desired Status Created At +8fa21654 a8dcce2d web 1 run running 07/25/17 18:35:21 UTC +9f6727a6 a8dcce2d cache 1 run running 07/25/17 18:35:21 UTC +091377e5 a8dcce2d web 1 run running 07/25/17 18:35:05 UTC +d2b13584 a8dcce2d cache 1 run running 07/25/17 18:35:05 UTC +4bb185b7 a8dcce2d web 0 stop complete 07/25/17 18:31:34 UTC +9b6811ee a8dcce2d cache 0 stop complete 07/25/17 18:31:34 UTC +e0a2441b a8dcce2d cache 0 stop complete 07/25/17 18:31:34 UTC +f2409f7d a8dcce2d web 0 stop complete 07/25/17 18:31:34 UTC +``` + +Promote canaries in a particular group: + +``` +# Have two task groups waiting for promotion. +$ nomad status example +ID = example +Name = example +Submit Date = 07/25/17 18:37:14 UTC +Type = service +Priority = 50 +Datacenters = dc1 +Status = running +Periodic = false +Parameterized = false + +Summary +Task Group Queued Starting Running Failed Complete Lost +cache 0 0 3 0 0 0 +web 0 0 3 0 0 0 + +Latest Deployment +ID = a6b87a6c +Status = running +Description = Deployment is running but requires promotion + +Deployed +Task Group Promoted Desired Canaries Placed Healthy Unhealthy +cache false 2 1 1 1 0 +web false 2 1 1 1 0 + +Allocations +ID Node ID Task Group Version Desired Status Created At +3071ab8f 6240eed6 web 1 run running 07/25/17 18:37:14 UTC +eeeed13b 6240eed6 cache 1 run running 07/25/17 18:37:14 UTC +0ee7800c 6240eed6 cache 0 run running 07/25/17 18:37:08 UTC +a714a926 6240eed6 cache 0 run running 07/25/17 18:37:08 UTC +cee52788 6240eed6 web 0 run running 07/25/17 18:37:08 UTC +ee8f972e 6240eed6 web 0 run running 07/25/17 18:37:08 UTC + +# Promote only the cache canaries +$ nomad deployment promote -group cache a6b87a6c +==> Monitoring evaluation "37383564" + Evaluation triggered by job "example" + Evaluation within deployment: "a6b87a6c" + Allocation "bbddf5c3" created: node "6240eed6", group "cache" + Evaluation status changed: "pending" -> "complete" +==> Evaluation "37383564" finished with status "complete" + +# Inspect the status and see that only the cache canaries are promoted +$ nomad status example +ID = example +Name = example +Submit Date = 07/25/17 18:37:14 UTC +Type = service +Priority = 50 +Datacenters = dc1 +Status = running +Periodic = false +Parameterized = false + +Summary +Task Group Queued Starting Running Failed Complete Lost +cache 0 0 2 0 2 0 +web 0 0 3 0 0 0 + +Latest Deployment +ID = a6b87a6c +Status = running +Description = Deployment is running but requires promotion + +Deployed +Task Group Promoted Desired Canaries Placed Healthy Unhealthy +web false 2 1 1 1 0 +cache true 2 1 2 2 0 + +Allocations +ID Node ID Task Group Version Desired Status Created At +bbddf5c3 6240eed6 cache 1 run running 07/25/17 18:37:40 UTC +eeeed13b 6240eed6 cache 1 run running 07/25/17 18:37:14 UTC +3071ab8f 6240eed6 web 1 run running 07/25/17 18:37:14 UTC +a714a926 6240eed6 cache 0 stop complete 07/25/17 18:37:08 UTC +cee52788 6240eed6 web 0 run running 07/25/17 18:37:08 UTC +ee8f972e 6240eed6 web 0 run running 07/25/17 18:37:08 UTC +0ee7800c 6240eed6 cache 0 stop complete 07/25/17 18:37:08 UTC +``` diff --git a/website/source/docs/commands/deployment/resume.html.md.erb b/website/source/docs/commands/deployment/resume.html.md.erb new file mode 100644 index 000000000..c548dcde2 --- /dev/null +++ b/website/source/docs/commands/deployment/resume.html.md.erb @@ -0,0 +1,52 @@ +--- +layout: "docs" +page_title: "Commands: deployment resume" +sidebar_current: "docs-commands-deployment-resume" +description: > + The deployment resume command is used to resume a paused deployment. +--- + +# Command: deployment resume + +The `deployment resume` command is used used to unpause a paused deployment. +Resuming a deployment will resume the placement of new allocations as part of +rolling deployment. + +## Usage + +``` +nomad deployment resume [options] +``` + +The `deployment resume` command requires a single argument, a deployment ID or +prefix. + +## General Options + +<%= partial "docs/commands/_general_options" %> + +## Resume Options + +* `-detach`: Return immediately instead of monitoring. A new evaluation ID + will be output, which can be used to examine the evaluation using the + [eval-status](/docs/commands/eval-status.html) command + +* `-verbose`: Show full information. + +## Examples + +Manually resume a deployment: + +``` +$ nomad deployment resume c848972e +Deployment "c848972e-dcd3-7354-e0d2-39d86642cdb1" resumed + +==> Monitoring evaluation "5e266d42" + Evaluation triggered by job "example" + Evaluation within deployment: "c848972e" + Allocation "00208424" created: node "6240eed6", group "web" + Allocation "68c72edf" created: node "6240eed6", group "cache" + Allocation "00208424" status changed: "pending" -> "running" + Evaluation status changed: "pending" -> "complete" +==> Evaluation "5e266d42" finished with status "complete" +``` diff --git a/website/source/docs/commands/deployment/status.html.md.erb b/website/source/docs/commands/deployment/status.html.md.erb new file mode 100644 index 000000000..b68345669 --- /dev/null +++ b/website/source/docs/commands/deployment/status.html.md.erb @@ -0,0 +1,68 @@ +--- +layout: "docs" +page_title: "Commands: deployment status" +sidebar_current: "docs-commands-deployment-status" +description: > + The deployment status command is used to display the status of a deployment. +--- + +# Command: deployment status + +The `deployment status` command is used to display the status of a deployment. +The status will display the number of desired changes as well as the currently +applied changes. + +## Usage + +``` +nomad deployment status [options] +``` + +The `deployment status` command requires a single argument, a deployment ID or +prefix. + +## General Options + +<%= partial "docs/commands/_general_options" %> + +## Status Options + +* `-json` : Output the deployment in its JSON format. + +* `-t` : Format and display the deployment using a Go template. + +* `-verbose`: Show full information. + +## Examples + +Inspect the status of a complete deployment: + +``` +$ nomad deployment status 06ca68a2 +ID = 06ca68a2 +Job ID = example +Job Version = 0 +Status = successful +Description = Deployment completed successfully + +Deployed +Task Group Desired Placed Healthy Unhealthy +cache 2 2 2 0 +web 2 2 2 0 +``` + +Inspect the status of a deployment that is waiting for canary promotion: + +``` +$ nomad deployment status 0b +ID = 0b23b149 +Job ID = example +Job Version = 1 +Status = running +Description = Deployment is running but requires promotion + +Deployed +Task Group Promoted Desired Canaries Placed Healthy Unhealthy +cache false 2 1 1 0 0 +web N/A 2 0 2 2 0 +``` diff --git a/website/source/docs/commands/job.html.md.erb b/website/source/docs/commands/job.html.md.erb new file mode 100644 index 000000000..de1b36eb3 --- /dev/null +++ b/website/source/docs/commands/job.html.md.erb @@ -0,0 +1,32 @@ +--- +layout: "docs" +page_title: "Commands: job" +sidebar_current: "docs-commands-job" +description: > + The job command is used to interact with jobs. +--- + +# Nomad Job + +Command: `nomad job` + +The `job` command is used to interact with jobs. + +## Usage + +Usage: `nomad job [options]` + +Run `nomad job -h` for help on that subcommand. The following +subcommands are available: + +* [`job deployments`][deployments] - List deployments for a job +* [`job dispatch`][dispatch] - Dispatch an instance of a parameterized job +* [`job history`][history] - Display all tracked versions of a job +* [`job promote`][promote] - Promote a job's canaries +* [`job revert`][revert] - Revert to a prior version of the job + +[deployments]: /docs/commands/job/deployments.html "List deployments for a job" +[dispatch]: /docs/commands/job/dispatch.html "Dispatch an instance of a parameterized job" +[history]: /docs/commands/job/history.html "Display all tracked versions of a job" +[promote]: /docs/commands/job/promote.html "Promote a job's canaries" +[revert]: /docs/commands/job/revert.html "Revert to a prior version of the job" diff --git a/website/source/docs/commands/job/deployments.html.md.erb b/website/source/docs/commands/job/deployments.html.md.erb new file mode 100644 index 000000000..b234f48a4 --- /dev/null +++ b/website/source/docs/commands/job/deployments.html.md.erb @@ -0,0 +1,47 @@ +--- +layout: "docs" +page_title: "Commands: job deployments" +sidebar_current: "docs-commands-job-deployments" +description: > + The deployments command is used to list deployments for a job. +--- + +# Command: job deployments + +The `job dispatch` command is used to display the deployments for a particular +job. + +## Usage + +``` +nomad job deployments [options] +``` + +The `job deployments` command requires a single argument, the job ID or an ID prefix +of a job to display the list of deployments for. + +## General Options + +<%= partial "docs/commands/_general_options" %> + +## Deployment Options + +* `-latest`: Display the latest deployment only. + +* `-json` : Output the deployment in its JSON format. + +* `-t` : Format and display the deployment using a Go template. + +* `-verbose`: Show full information. + +## Examples + +List the deployment for a particular job: + +``` +$ nomad job deployments example +ID Job ID Job Version Status Description +0b23b149 example 1 running Deployment is running but requires promotion +06ca68a2 example 0 successful Deployment completed successfully +``` + diff --git a/website/source/docs/commands/job-dispatch.html.md.erb b/website/source/docs/commands/job/dispatch.html.md.erb similarity index 94% rename from website/source/docs/commands/job-dispatch.html.md.erb rename to website/source/docs/commands/job/dispatch.html.md.erb index 8b6da9e0a..d5ffd8655 100644 --- a/website/source/docs/commands/job-dispatch.html.md.erb +++ b/website/source/docs/commands/job/dispatch.html.md.erb @@ -8,10 +8,6 @@ description: > # Command: job dispatch -~> The `job dispatch` subcommand described here is available only in version -0.5.3 and later. The release candidate is downloadable on the [releases -page.](https://releases.hashicorp.com/nomad/0.5.3-rc1/) - The `job dispatch` command is used to create new instances of a [parameterized job]. The parameterized job captures a job's configuration and runtime requirements in a generic way and `dispatch` is used to provide the input for @@ -48,7 +44,7 @@ client connection issues or internal errors, are indicated by exit code 1. <%= partial "docs/commands/_general_options" %> -## Run Options +## Dispatch Options * `-meta`: Meta takes a key/value pair seperated by "=". The metadata key will be merged into the job's metadata. The job may define a default value for the diff --git a/website/source/docs/commands/job/history.html.md.erb b/website/source/docs/commands/job/history.html.md.erb new file mode 100644 index 000000000..9335ab02b --- /dev/null +++ b/website/source/docs/commands/job/history.html.md.erb @@ -0,0 +1,85 @@ +--- +layout: "docs" +page_title: "Commands: job history" +sidebar_current: "docs-commands-job-history" +description: > + The history command is used to display all tracked versions of a job. +--- + +# Command: job history + +The `job history` command is used to display the known versions of a particular +job. The command can display the diff between job versions and can be useful for +understanding the changes that occured to the job as well as deciding job +versions to revert to. + +## Usage + +``` +nomad job history [options] +``` + +The `job history` command requires a single argument, the job ID or an ID prefix +of a job to display the history for. + +## General Options + +<%= partial "docs/commands/_general_options" %> + +## History Options + +* `-p`: Display the differences between each job and its predecessor. + +* `-full`: Display the full job definition for each version. + +* `-version`: Display only the history for the given version. + +* `-json` : Output the job versions in its JSON format. + +* `-t` : Format and display the job versions using a Go template. + +## Examples + +Display the history showing differences between versions: + +``` +$ nomad job history -p e +Version = 2 +Stable = false +Submit Date = 07/25/17 20:35:43 UTC +Diff = ++/- Job: "example" ++/- Task Group: "cache" + +/- Task: "redis" + +/- Resources { + CPU: "500" + DiskMB: "0" + IOPS: "0" + +/- MemoryMB: "256" => "512" + } + +Version = 1 +Stable = false +Submit Date = 07/25/17 20:35:31 UTC +Diff = ++/- Job: "example" ++/- Task Group: "cache" + +/- Count: "1" => "3" + Task: "redis" + +Version = 0 +Stable = false +Submit Date = 07/25/17 20:35:28 UTC +``` + +Display the memory ask across submitted job versions: + +``` +$ nomad job history -t "{{range .}}\ +v{{.Version}}: {{with index .TaskGroups 0}}{{with index .Tasks 0}}{{.Resources.MemoryMB}}{{end}}{{end}}\ + +{{end}}" example +v2: 512 +v1: 256 +v0: 256 +``` diff --git a/website/source/docs/commands/job/promote.html.md.erb b/website/source/docs/commands/job/promote.html.md.erb new file mode 100644 index 000000000..983499e9d --- /dev/null +++ b/website/source/docs/commands/job/promote.html.md.erb @@ -0,0 +1,221 @@ +--- +layout: "docs" +page_title: "Commands: job promote" +sidebar_current: "docs-commands-job-promote" +description: > + The promote command is used to promote a job's canaries. +--- + +# Command: job promote + +The `job promote` command is used to promote task groups in the most recent +deployment for the given job. Promotion should occur when the deployment has +placed canaries for a task group and those canaries have been deemed healthy. +When a task group is promoted, the rolling upgrade of the remaining allocations +is unblocked. If the canaries are found to be unhealthy, the deployment may +either be failed using the "nomad deployment fail" command, the job can be +failed forward by submitting a new version or failed backwards by reverting to +an older version using the [job revert](/docs/commands/job/revert.html) command. + +## Usage + +``` +nomad job promote [options] +``` + +The `job promote` command requires a single argument, a job ID or +prefix. When run without specifying any groups to promote, the promote command +promotes all task groups. The group flag can be specified multiple times to +select particular groups to promote. + +## General Options + +<%= partial "docs/commands/_general_options" %> + +## Promote Options + +* `-group`: Group may be specified many times and is used to promote that + particular group. If no specific groups are specified, all groups are + promoted. + +* `-detach`: Return immediately instead of monitoring. A new evaluation ID + will be output, which can be used to examine the evaluation using the + [eval-status](/docs/commands/eval-status.html) command + +* `-verbose`: Show full information. + +## Examples + +Promote canaries in all groups: + +``` +# Have two task groups waiting for promotion. +$ nomad status example +ID = example +Name = example +Submit Date = 07/25/17 18:35:05 UTC +Type = service +Priority = 50 +Datacenters = dc1 +Status = running +Periodic = false +Parameterized = false + +Summary +Task Group Queued Starting Running Failed Complete Lost +cache 0 0 3 0 0 0 +web 0 0 3 0 0 0 + +Latest Deployment +ID = 9fa81f27 +Status = running +Description = Deployment is running but requires promotion + +Deployed +Task Group Promoted Desired Canaries Placed Healthy Unhealthy +web false 2 1 1 0 0 +cache false 2 1 1 0 0 + +Allocations +ID Node ID Task Group Version Desired Status Created At +091377e5 a8dcce2d web 1 run running 07/25/17 18:35:05 UTC +d2b13584 a8dcce2d cache 1 run running 07/25/17 18:35:05 UTC +4bb185b7 a8dcce2d web 0 run running 07/25/17 18:31:34 UTC +9b6811ee a8dcce2d cache 0 run running 07/25/17 18:31:34 UTC +e0a2441b a8dcce2d cache 0 run running 07/25/17 18:31:34 UTC +f2409f7d a8dcce2d web 0 run running 07/25/17 18:31:34 UTC + +# Promote all groups +$ nomad job promote example +==> Monitoring evaluation "6c6e64ae" + Evaluation triggered by job "example" + Evaluation within deployment: "9fa81f27" + Allocation "8fa21654" created: node "a8dcce2d", group "web" + Allocation "9f6727a6" created: node "a8dcce2d", group "cache" + Evaluation status changed: "pending" -> "complete" +==> Evaluation "6c6e64ae" finished with status "complete" + +# Inspect the status and see both groups have been promoted. +$ nomad status example +ID = example +Name = example +Submit Date = 07/25/17 18:35:05 UTC +Type = service +Priority = 50 +Datacenters = dc1 +Status = running +Periodic = false +Parameterized = false + +Summary +Task Group Queued Starting Running Failed Complete Lost +cache 0 0 2 0 2 0 +web 0 0 2 0 2 0 + +Latest Deployment +ID = 9fa81f27 +Status = successful +Description = Deployment completed successfully + +Deployed +Task Group Promoted Desired Canaries Placed Healthy Unhealthy +web true 2 1 2 2 0 +cache true 2 1 2 2 0 + +Allocations +ID Node ID Task Group Version Desired Status Created At +8fa21654 a8dcce2d web 1 run running 07/25/17 18:35:21 UTC +9f6727a6 a8dcce2d cache 1 run running 07/25/17 18:35:21 UTC +091377e5 a8dcce2d web 1 run running 07/25/17 18:35:05 UTC +d2b13584 a8dcce2d cache 1 run running 07/25/17 18:35:05 UTC +4bb185b7 a8dcce2d web 0 stop complete 07/25/17 18:31:34 UTC +9b6811ee a8dcce2d cache 0 stop complete 07/25/17 18:31:34 UTC +e0a2441b a8dcce2d cache 0 stop complete 07/25/17 18:31:34 UTC +f2409f7d a8dcce2d web 0 stop complete 07/25/17 18:31:34 UTC +``` + +Promote canaries in a particular group: + +``` +# Have two task groups waiting for promotion. +$ nomad status example +ID = example +Name = example +Submit Date = 07/25/17 18:37:14 UTC +Type = service +Priority = 50 +Datacenters = dc1 +Status = running +Periodic = false +Parameterized = false + +Summary +Task Group Queued Starting Running Failed Complete Lost +cache 0 0 3 0 0 0 +web 0 0 3 0 0 0 + +Latest Deployment +ID = a6b87a6c +Status = running +Description = Deployment is running but requires promotion + +Deployed +Task Group Promoted Desired Canaries Placed Healthy Unhealthy +cache false 2 1 1 1 0 +web false 2 1 1 1 0 + +Allocations +ID Node ID Task Group Version Desired Status Created At +3071ab8f 6240eed6 web 1 run running 07/25/17 18:37:14 UTC +eeeed13b 6240eed6 cache 1 run running 07/25/17 18:37:14 UTC +0ee7800c 6240eed6 cache 0 run running 07/25/17 18:37:08 UTC +a714a926 6240eed6 cache 0 run running 07/25/17 18:37:08 UTC +cee52788 6240eed6 web 0 run running 07/25/17 18:37:08 UTC +ee8f972e 6240eed6 web 0 run running 07/25/17 18:37:08 UTC + +# Promote only the cache canaries +$ nomad job promote example +==> Monitoring evaluation "37383564" + Evaluation triggered by job "example" + Evaluation within deployment: "a6b87a6c" + Allocation "bbddf5c3" created: node "6240eed6", group "cache" + Evaluation status changed: "pending" -> "complete" +==> Evaluation "37383564" finished with status "complete" + +# Inspect the status and see that only the cache canaries are promoted +$ nomad status example +ID = example +Name = example +Submit Date = 07/25/17 18:37:14 UTC +Type = service +Priority = 50 +Datacenters = dc1 +Status = running +Periodic = false +Parameterized = false + +Summary +Task Group Queued Starting Running Failed Complete Lost +cache 0 0 2 0 2 0 +web 0 0 3 0 0 0 + +Latest Deployment +ID = a6b87a6c +Status = running +Description = Deployment is running but requires promotion + +Deployed +Task Group Promoted Desired Canaries Placed Healthy Unhealthy +web false 2 1 1 1 0 +cache true 2 1 2 2 0 + +Allocations +ID Node ID Task Group Version Desired Status Created At +bbddf5c3 6240eed6 cache 1 run running 07/25/17 18:37:40 UTC +eeeed13b 6240eed6 cache 1 run running 07/25/17 18:37:14 UTC +3071ab8f 6240eed6 web 1 run running 07/25/17 18:37:14 UTC +a714a926 6240eed6 cache 0 stop complete 07/25/17 18:37:08 UTC +cee52788 6240eed6 web 0 run running 07/25/17 18:37:08 UTC +ee8f972e 6240eed6 web 0 run running 07/25/17 18:37:08 UTC +0ee7800c 6240eed6 cache 0 stop complete 07/25/17 18:37:08 UTC +``` diff --git a/website/source/docs/commands/job/revert.html.md.erb b/website/source/docs/commands/job/revert.html.md.erb new file mode 100644 index 000000000..9bfb8b6de --- /dev/null +++ b/website/source/docs/commands/job/revert.html.md.erb @@ -0,0 +1,94 @@ +--- +layout: "docs" +page_title: "Commands: job revert" +sidebar_current: "docs-commands-job-revert" +description: > + The revert command is used to revert to a prior version of the job. +--- + +# Command: job dispatch + +The `job dispatch` command is used to revert a job to a prior version of the +job. The available versions to revert to can be found using [`job +history`](/docs/commands/job/history.html) command. + +## Usage + +``` +nomad job revert [options] +``` + +The `job revert` command requires two inputs, the job ID and the version of that job +to revert to. + +## General Options + +<%= partial "docs/commands/_general_options" %> + +## Revert Options + +* `-detach`: Return immediately instead of monitoring. A new evaluation ID + will be output, which can be used to examine the evaluation using the + [eval-status](/docs/commands/eval-status.html) command + +* `-verbose`: Show full information. + +## Examples + +Revert to an older version of a job: + +``` +$ nomad job history -p example +Version = 1 +Stable = false +Submit Date = 07/25/17 21:27:30 UTC +Diff = ++/- Job: "example" ++/- Task Group: "cache" + +/- Task: "redis" + +/- Config { + +/- image: "redis:3.2" => "redis:4.0" + port_map[0][db]: "6379" + } + +Version = 0 +Stable = false +Submit Date = 07/25/17 21:27:18 UTC + +$ nomad job revert example 0 +==> Monitoring evaluation "faff5c30" + Evaluation triggered by job "example" + Evaluation within deployment: "e17c8592" + Allocation "4ed0ca3b" modified: node "e8a2243d", group "cache" + Evaluation status changed: "pending" -> "complete" +==> Evaluation "faff5c30" finished with status "complete" + +$ nomad job history -p example +Version = 2 +Stable = true +Submit Date = 07/25/17 21:27:43 UTC +Diff = ++/- Job: "example" ++/- Task Group: "cache" + +/- Task: "redis" + +/- Config { + +/- image: "redis:4.0" => "redis:3.2" + port_map[0][db]: "6379" + } + +Version = 1 +Stable = false +Submit Date = 07/25/17 21:27:30 UTC +Diff = ++/- Job: "example" ++/- Task Group: "cache" + +/- Task: "redis" + +/- Config { + +/- image: "redis:3.2" => "redis:4.0" + port_map[0][db]: "6379" + } + +Version = 0 +Stable = false +Submit Date = 07/25/17 21:27:18 UTC +``` diff --git a/website/source/docs/commands/run.html.md.erb b/website/source/docs/commands/run.html.md.erb index a378d87dd..41d17a3a4 100644 --- a/website/source/docs/commands/run.html.md.erb +++ b/website/source/docs/commands/run.html.md.erb @@ -68,8 +68,6 @@ precedence, going from highest to lowest: the `-vault-token` flag, the * `-output`: Output the JSON that would be submitted to the HTTP API without submitting the job. -## Status Options - * `-verbose`: Show full information. ## Examples diff --git a/website/source/layouts/docs.erb b/website/source/layouts/docs.erb index aaa140568..9792b5cfb 100644 --- a/website/source/layouts/docs.erb +++ b/website/source/layouts/docs.erb @@ -179,6 +179,29 @@ > client-config + > + deployment + + > eval-status @@ -191,8 +214,25 @@ > inspect - > - job dispatch + > + job + > keygen From f660d79514d2e4ab382e4566026a81cca5acc573 Mon Sep 17 00:00:00 2001 From: Michael Schurter Date: Tue, 25 Jul 2017 14:48:25 -0700 Subject: [PATCH 7/8] Missing period --- website/source/docs/commands/deployment/fail.html.md.erb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/source/docs/commands/deployment/fail.html.md.erb b/website/source/docs/commands/deployment/fail.html.md.erb index 4429065ac..774f75b0a 100644 --- a/website/source/docs/commands/deployment/fail.html.md.erb +++ b/website/source/docs/commands/deployment/fail.html.md.erb @@ -30,7 +30,7 @@ prefix. * `-detach`: Return immediately instead of monitoring. A new evaluation ID will be output, which can be used to examine the evaluation using the - [eval-status](/docs/commands/eval-status.html) command + [eval-status](/docs/commands/eval-status.html) command. * `-verbose`: Show full information. From 0db6b986eb424a7f15359d6cdbdc96288a7fa1c6 Mon Sep 17 00:00:00 2001 From: Alex Dadgar Date: Tue, 25 Jul 2017 17:34:28 -0700 Subject: [PATCH 8/8] Fix indentation --- website/redirects.txt | 52 +++++++++++++++++++++---------------------- 1 file changed, 26 insertions(+), 26 deletions(-) diff --git a/website/redirects.txt b/website/redirects.txt index e87d06b18..f1ed702f6 100644 --- a/website/redirects.txt +++ b/website/redirects.txt @@ -37,33 +37,33 @@ # # 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 -/docs/commands/operator-index.html /docs/commands/operator.html -/docs/commands/operator-raft-list-peers.html /docs/commands/operator/raft-list-peers.html +/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 +/docs/commands/operator-index.html /docs/commands/operator.html +/docs/commands/operator-raft-list-peers.html /docs/commands/operator/raft-list-peers.html /docs/commands/operator-raft-remove-peer.html /docs/commands/operator/raft-remove-peer.html -/docs/commands/job-dispatch.html /docs/commands/job/dispatch.html +/docs/commands/job-dispatch.html /docs/commands/job/dispatch.html # API /docs/http/index.html /api/index.html