»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 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
-address=<addr>: The address of the Nomad server. Overrides theNOMAD_ADDRenvironment variable if set. Defaults tohttp://127.0.0.1:4646.-region=<region>: The region of the Nomad server to forward commands to. Overrides theNOMAD_REGIONenvironment variable if set. Defaults to the Agent's local region.-namespace=<namespace>: The target namespace for queries and actions bound to a namespace. Overrides theNOMAD_NAMESPACEenvironment variable if set. If set to'*', job and alloc subcommands query all namespacecs authorized to user. Defaults to the "default" namespace.-no-color: Disables colored command output. Alternatively,NOMAD_CLI_NO_COLORmay be set.-ca-cert=<path>: Path to a PEM encoded CA cert file to use to verify the Nomad server SSL certificate. Overrides theNOMAD_CACERTenvironment variable if set.-ca-path=<path>: Path to a directory of PEM encoded CA cert files to verify the Nomad server SSL certificate. If both-ca-certand-ca-pathare specified,-ca-certis used. Overrides theNOMAD_CAPATHenvironment variable if set.-client-cert=<path>: Path to a PEM encoded client certificate for TLS authentication to the Nomad server. Must also specify-client-key. Overrides theNOMAD_CLIENT_CERTenvironment variable if set.-client-key=<path>: Path to an unencrypted PEM encoded private key matching the client certificate from-client-cert. Overrides theNOMAD_CLIENT_KEYenvironment variable if set.-tls-server-name=<value>: The server name to use as the SNI host when connecting via TLS. Overrides theNOMAD_TLS_SERVER_NAMEenvironment variable if set.-tls-skip-verify: Do not verify TLS certificate. This is highly not recommended. Verification will also be skipped ifNOMAD_SKIP_VERIFYis set.-token: The SecretID of an ACL token to use to authenticate API requests with. Overrides theNOMAD_TOKENenvironment variable if set.
»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 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 manual 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 manual 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 manual 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