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

New commands docs and small fixes

Browse Source 
This PR adds the command documentations and has small CLI fixes.
This commit is contained in:
Alex Dadgar
2017-07-25 11:18:21 -07:00
parent 278195e6dc
commit 487e1eafee
21 changed files with 1066 additions and 29 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
command/deployment_fail.go
View File

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

10
command/deployment_promote.go
View File

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

6
command/deployment_resume.go
View File

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

6
command/deployment_status.go
View File

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

10
command/job_promote.go
View File

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

7
website/redirects.txt
View File

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

34
website/source/docs/commands/deployment.html.md.erb Normal file
View File

@@ -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 <subcommand> [options]`
Run `nomad deployment <subcommand> -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"

61
website/source/docs/commands/deployment/fail.html.md.erb Normal file
View File

@@ -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] <deployment id>
```
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
```

43
website/source/docs/commands/deployment/list.html.md.erb Normal file
View File

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

40
website/source/docs/commands/deployment/pause.html.md.erb Normal file
View File

@@ -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] <deployment id>
```
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
```

221
website/source/docs/commands/deployment/promote.html.md.erb Normal file
View File

@@ -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] <deployment id>
```
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
```

52
website/source/docs/commands/deployment/resume.html.md.erb Normal file
View File

@@ -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] <deployment id>
```
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"
```

68
website/source/docs/commands/deployment/status.html.md.erb Normal file
View File

@@ -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] <deployment id>
```
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
```

32
website/source/docs/commands/job.html.md.erb Normal file
View File

@@ -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 <subcommand> [options]`
Run `nomad job <subcommand> -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"

47
website/source/docs/commands/job/deployments.html.md.erb Normal file
View File

@@ -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] <job>
```
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
```

6
website/source/docs/commands/job-dispatch.html.md.erb → website/source/docs/commands/job/dispatch.html.md.erb
View File

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

85
website/source/docs/commands/job/history.html.md.erb Normal file
View File

@@ -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] <job>
```
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
```

221
website/source/docs/commands/job/promote.html.md.erb Normal file
View File

@@ -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] <job>
```
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
```

94
website/source/docs/commands/job/revert.html.md.erb Normal file
View File

@@ -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] <job> <version>
```
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
```

2
website/source/docs/commands/run.html.md.erb
View File

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

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

@@ -179,6 +179,29 @@
<li<%= sidebar_current("docs-commands-client-config") %>>
<a href="/docs/commands/client-config.html">client-config</a>
</li>
<li<%= sidebar_current("docs-commands-deployment") %>>
<a href="/docs/commands/deployment.html">deployment</a>
<ul class="nav">
<li<%= sidebar_current("docs-commands-deployment-fail") %>>
<a href="/docs/commands/deployment/fail.html">deployment fail</a>
</li>
<li<%= sidebar_current("docs-commands-deployment-list") %>>
<a href="/docs/commands/deployment/list.html">deployment list</a>
</li>
<li<%= sidebar_current("docs-commands-deployment-pause") %>>
<a href="/docs/commands/deployment/pause.html">deployment pause</a>
</li>
<li<%= sidebar_current("docs-commands-deployment-promote") %>>
<a href="/docs/commands/deployment/promote.html">deployment promote</a>
</li>
<li<%= sidebar_current("docs-commands-deployment-resume") %>>
<a href="/docs/commands/deployment/resume.html">deployment resume</a>
</li>
<li<%= sidebar_current("docs-commands-deployment-status") %>>
<a href="/docs/commands/deployment/status.html">deployment status</a>
</li>
</ul>
</li>
<li<%= sidebar_current("docs-commands-eval-status") %>>
<a href="/docs/commands/eval-status.html">eval-status</a>
</li>
@@ -191,8 +214,25 @@
<li<%= sidebar_current("docs-commands-inspect") %>>
<a href="/docs/commands/inspect.html">inspect</a>
</li>
<li<%= sidebar_current("docs-commands-job-dispatch") %>>
<a href="/docs/commands/job-dispatch.html">job dispatch</a>
<li<%= sidebar_current("docs-commands-job") %>>
<a href="/docs/commands/job.html">job</a>
<ul class="nav">
<li<%= sidebar_current("docs-commands-job-deployments") %>>
<a href="/docs/commands/job/deployments.html">job deployments</a>
</li>
<li<%= sidebar_current("docs-commands-job-dispatch") %>>
<a href="/docs/commands/job/dispatch.html">job dispatch</a>
</li>
<li<%= sidebar_current("docs-commands-job-history") %>>
<a href="/docs/commands/job/history.html">job history</a>
</li>
<li<%= sidebar_current("docs-commands-job-promote") %>>
<a href="/docs/commands/job/promote.html">job promote</a>
</li>
<li<%= sidebar_current("docs-commands-job-revert") %>>
<a href="/docs/commands/job/revert.html">job revert</a>
</li>
</ul>
</li>
<li<%= sidebar_current("docs-commands-keygen") %>>
<a href="/docs/commands/keygen.html">keygen</a>