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

When ACLs are enabled, this command requires a token with the submit-job, and read-job capabilities for the job's namespace. The list-jobs capability is required to run the command with a job prefix instead of the exact job ID.

General Options

-address=<addr>: The address of the Nomad server. Overrides the NOMAD_ADDR environment variable if set. Defaults to http://127.0.0.1:4646.
-region=<region>: The region of the Nomad server to forward commands to. Overrides the NOMAD_REGION environment variable if set. Defaults to the Agent's local region.
-namespace=<namespace>: The target namespace for queries and actions bound to a namespace. Overrides the NOMAD_NAMESPACE environment variable if set. If set to '*', job and alloc subcommands query all namespaces authorized to user. Defaults to the "default" namespace.
-no-color: Disables colored command output. Alternatively, NOMAD_CLI_NO_COLOR may be set. This option takes precedence over -force-color.
-force-color: Forces colored command output. This can be used in cases where the usual terminal detection fails. Alternatively, NOMAD_CLI_FORCE_COLOR may be set. This option has no effect if -no-color is also used.
-ca-cert=<path>: Path to a PEM encoded CA cert file to use to verify the Nomad server SSL certificate. Overrides the NOMAD_CACERT environment 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-cert and -ca-path are specified, -ca-cert is used. Overrides the NOMAD_CAPATH environment 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 the NOMAD_CLIENT_CERT environment variable if set.
-client-key=<path>: Path to an unencrypted PEM encoded private key matching the client certificate from -client-cert. Overrides the NOMAD_CLIENT_KEY environment variable if set.
-tls-server-name=<value>: The server name to use as the SNI host when connecting via TLS. Overrides the NOMAD_TLS_SERVER_NAME environment variable if set.
-tls-skip-verify: Do not verify TLS certificate. This is highly not recommended. Verification will also be skipped if NOMAD_SKIP_VERIFY is set.
-token: The SecretID of an ACL token to use to authenticate API requests with. Overrides the NOMAD_TOKEN environment 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 exampleID            = exampleName          = exampleSubmit Date   = 07/25/17 18:35:05 UTCType          = servicePriority      = 50Datacenters   = dc1Status        = runningPeriodic      = falseParameterized = false SummaryTask Group  Queued  Starting  Running  Failed  Complete  Lostcache       0       0         3        0       0         0web         0       0         3        0       0         0 Latest DeploymentID          = 9fa81f27Status      = runningDescription = Deployment is running but requires manual promotion DeployedTask Group  Promoted  Desired  Canaries  Placed  Healthy  Unhealthyweb         false     2        1         1       0        0cache       false     2        1         1       0        0 AllocationsID        Node ID   Task Group  Version  Desired  Status   Created At091377e5  a8dcce2d  web         1        run      running  07/25/17 18:35:05 UTCd2b13584  a8dcce2d  cache       1        run      running  07/25/17 18:35:05 UTC4bb185b7  a8dcce2d  web         0        run      running  07/25/17 18:31:34 UTC9b6811ee  a8dcce2d  cache       0        run      running  07/25/17 18:31:34 UTCe0a2441b  a8dcce2d  cache       0        run      running  07/25/17 18:31:34 UTCf2409f7d  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 exampleID            = exampleName          = exampleSubmit Date   = 07/25/17 18:35:05 UTCType          = servicePriority      = 50Datacenters   = dc1Status        = runningPeriodic      = falseParameterized = false SummaryTask Group  Queued  Starting  Running  Failed  Complete  Lostcache       0       0         2        0       2         0web         0       0         2        0       2         0 Latest DeploymentID          = 9fa81f27Status      = successfulDescription = Deployment completed successfully DeployedTask Group  Promoted  Desired  Canaries  Placed  Healthy  Unhealthyweb         true      2        1         2       2        0cache       true      2        1         2       2        0 AllocationsID        Node ID   Task Group  Version  Desired  Status    Created At8fa21654  a8dcce2d  web         1        run      running   07/25/17 18:35:21 UTC9f6727a6  a8dcce2d  cache       1        run      running   07/25/17 18:35:21 UTC091377e5  a8dcce2d  web         1        run      running   07/25/17 18:35:05 UTCd2b13584  a8dcce2d  cache       1        run      running   07/25/17 18:35:05 UTC4bb185b7  a8dcce2d  web         0        stop     complete  07/25/17 18:31:34 UTC9b6811ee  a8dcce2d  cache       0        stop     complete  07/25/17 18:31:34 UTCe0a2441b  a8dcce2d  cache       0        stop     complete  07/25/17 18:31:34 UTCf2409f7d  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 exampleID            = exampleName          = exampleSubmit Date   = 07/25/17 18:37:14 UTCType          = servicePriority      = 50Datacenters   = dc1Status        = runningPeriodic      = falseParameterized = false SummaryTask Group  Queued  Starting  Running  Failed  Complete  Lostcache       0       0         3        0       0         0web         0       0         3        0       0         0 Latest DeploymentID          = a6b87a6cStatus      = runningDescription = Deployment is running but requires manual promotion DeployedTask Group  Promoted  Desired  Canaries  Placed  Healthy  Unhealthycache       false     2        1         1       1        0web         false     2        1         1       1        0 AllocationsID        Node ID   Task Group  Version  Desired  Status   Created At3071ab8f  6240eed6  web         1        run      running  07/25/17 18:37:14 UTCeeeed13b  6240eed6  cache       1        run      running  07/25/17 18:37:14 UTC0ee7800c  6240eed6  cache       0        run      running  07/25/17 18:37:08 UTCa714a926  6240eed6  cache       0        run      running  07/25/17 18:37:08 UTCcee52788  6240eed6  web         0        run      running  07/25/17 18:37:08 UTCee8f972e  6240eed6  web         0        run      running  07/25/17 18:37:08 UTC # Promote only the cache canaries$ nomad job promote -group=cache 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 exampleID            = exampleName          = exampleSubmit Date   = 07/25/17 18:37:14 UTCType          = servicePriority      = 50Datacenters   = dc1Status        = runningPeriodic      = falseParameterized = false SummaryTask Group  Queued  Starting  Running  Failed  Complete  Lostcache       0       0         2        0       2         0web         0       0         3        0       0         0 Latest DeploymentID          = a6b87a6cStatus      = runningDescription = Deployment is running but requires manual promotion DeployedTask Group  Promoted  Desired  Canaries  Placed  Healthy  Unhealthyweb         false     2        1         1       1        0cache       true      2        1         2       2        0 AllocationsID        Node ID   Task Group  Version  Desired  Status    Created Atbbddf5c3  6240eed6  cache       1        run      running   07/25/17 18:37:40 UTCeeeed13b  6240eed6  cache       1        run      running   07/25/17 18:37:14 UTC3071ab8f  6240eed6  web         1        run      running   07/25/17 18:37:14 UTCa714a926  6240eed6  cache       0        stop     complete  07/25/17 18:37:08 UTCcee52788  6240eed6  web         0        run      running   07/25/17 18:37:08 UTCee8f972e  6240eed6  web         0        run      running   07/25/17 18:37:08 UTC0ee7800c  6240eed6  cache       0        stop     complete  07/25/17 18:37:08 UTC