From 487e1eafee6a8c6a01c13dc820a4ff08b6f2041e Mon Sep 17 00:00:00 2001 From: Alex Dadgar Date: Tue, 25 Jul 2017 11:18:21 -0700 Subject: [PATCH] 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