From c6c52bc53e99cb8f2fe9d08a05452056daa4efec Mon Sep 17 00:00:00 2001 From: Isabel Suchanek Date: Wed, 9 Jun 2021 16:25:47 -0700 Subject: [PATCH] docs: add deployment monitor to docs, changelog Updates the deployment status and job run docs --- CHANGELOG.md | 3 + .../docs/commands/deployment/status.mdx | 84 +++++++++++++++-- website/content/docs/commands/job/run.mdx | 89 ++++++++++++++----- 3 files changed, 148 insertions(+), 28 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index e56f03f26..697c6e038 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,8 @@ ## 1.1.2 (Unreleased) +IMPROVEMENTS: +* cli: Added `-monitor` flag to `deployment status` command and automatically monitor deployments from `job run` command. [[GH-10661](https://github.com/hashicorp/nomad/pull/10661)] + ## 1.1.1 (June 9, 2021) FEATURES: diff --git a/website/content/docs/commands/deployment/status.mdx b/website/content/docs/commands/deployment/status.mdx index 458552a98..d8d5863c7 100644 --- a/website/content/docs/commands/deployment/status.mdx +++ b/website/content/docs/commands/deployment/status.mdx @@ -20,6 +20,11 @@ nomad deployment status [options] The `deployment status` command requires a single argument, a deployment ID or prefix. +A `-monitor` flag can be used to update the current deployment status until completion. +When combined with `-verbose`, it will also display the allocations for the given +deployment. If the deployment fails and [`auto_revert`] is set to `true`, it will monitor +the entire process, showing the failure and then monitoring the deployment of the rollback. + When ACLs are enabled, this command requires a token with the 'read-job' capability for the deployment's namespace. @@ -32,6 +37,7 @@ capability for the deployment's namespace. - `-json` : Output the deployment in its JSON format. - `-t` : Format and display the deployment using a Go template. - `-verbose`: Show full information. +- `-monitor`: Enter monitor mode to poll for updates to the deployment status. ## Examples @@ -46,9 +52,9 @@ Status = successful Description = Deployment completed successfully Deployed -Task Group Desired Placed Healthy Unhealthy -cache 2 2 2 0 -web 2 2 2 0 +Task Group Desired Placed Healthy Unhealthy Progress Deadline +cache 2 2 2 0 2021-06-09T15:20:27-07:00 +web 2 2 2 0 2021-06-09T15:20:27-07:00 ``` Inspect the status of a deployment that is waiting for canary promotion: @@ -62,7 +68,73 @@ Status = running Description = Deployment is running but requires manual 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 +Task Group Promoted Desired Canaries Placed Healthy Unhealthy Progress Deadline +cache false 2 1 1 0 0 2021-06-09T15:20:27-07:00 +web N/A 2 0 2 2 0 2021-06-09T15:20:27-07:00 ``` + +Monitor the status of a deployment and its allocations: + +```shell-session +$ nomad deployment status -monitor -verbose dab +2021-06-09T15:10:38-07:00: Monitoring deployment "da9bfc23-576f-be32-61c9-0f9997fe70a6" + ⠙ Deployment "da9bfc23-576f-be32-61c9-0f9997fe70a6" in progress... + + 2021-06-09T15:10:40-07:00 + ID = da9bfc23-576f-be32-61c9-0f9997fe70a6 + Job ID = example + Job Version = 0 + Status = running + Description = Deployment is running + + Deployed + Task Group Desired Placed Healthy Unhealthy Progress Deadline + cache 2 2 1 0 2021-06-09T15:20:27-07:00 + web 1 1 1 0 2021-06-09T15:20:27-07:00 + + Allocations + ID Eval ID Node ID Node Name Task Group Version Desired Status Created Modified + 9e1b4cb9-35c4-49f3-3ccb-1cb10a5a5aa6 e337d747-f59e-329e-4718-46edcc293695 70279742-b106-c487-315f-fb583e13178e mbp.local cache 0 run running 2021-06-09T15:10:17-07:00 2021-06-09T15:10:31-07:00 + bd0a8773-0d37-bca6-6ca1-2d9c8473bdf8 e337d747-f59e-329e-4718-46edcc293695 70279742-b106-c487-315f-fb583e13178e mbp.local cache 0 run running 2021-06-09T15:10:17-07:00 2021-06-09T15:10:29-07:00 + ee873095-8e76-7d4f-095f-b80ce5712d9b e337d747-f59e-329e-4718-46edcc293695 70279742-b106-c487-315f-fb583e13178e mbp.local web 0 run running 2021-06-09T15:10:17-07:00 2021-06-09T15:10:27-07:00 +``` + +Monitor the status of a deployment that fails and has `auto_revert` set to `true`: + +```shell-session +$ nomad deployment status -monitor e45 +2021-06-09T15:49:19-07:00: Monitoring deployment "e45cc3c1" + ⠦ Deployment "e45cc3c1" failed + + 2021-06-09T15:49:48-07:00 + ID = e45cc3c1 + Job ID = example + Job Version = 1 + Status = failed + Description = Failed due to progress deadline - rolling back to job version 0 + + Deployed + Task Group Auto Revert Desired Placed Healthy Unhealthy Progress Deadline + cache true 2 1 0 1 2021-06-09T15:49:48-07:00 + web false 1 1 1 0 2021-06-09T15:59:28-07:00 + + ⠙ Deployment "e094a0be" in progress... + + 2021-06-09T15:50:02-07:00 + ID = e094a0be + Job ID = example + Job Version = 2 + Status = running + Description = Deployment is running + + Deployed + Task Group Auto Revert Desired Placed Healthy Unhealthy Progress Deadline + cache true 2 2 1 0 2021-06-09T15:52:00-07:00 + web false 1 1 1 0 2021-06-09T15:59:58-07:00 +``` + +**Please note**: The library used for updating terminal output in place currently isn't fully +Windows compatible so there may be some formatting differences (different margins, no spinner +indicating deployment is in progress). + +[`auto_revert`]: /docs/job-specification/update#auto_revert \ No newline at end of file diff --git a/website/content/docs/commands/job/run.mdx b/website/content/docs/commands/job/run.mdx index b8aa140e9..ffca3be5b 100644 --- a/website/content/docs/commands/job/run.mdx +++ b/website/content/docs/commands/job/run.mdx @@ -27,8 +27,8 @@ downloaded and read from URL specified. Nomad downloads the job file using By default, on successful job submission the run command will enter an interactive monitor and display log information detailing the scheduling -decisions and placement information for the provided job. The monitor will -exit after scheduling has finished or failed. +decisions, placement information, and [deployment status] for the provided job. +The monitor will exit after scheduling and deployment have finished or failed. On successful job submission and scheduling, exit code 0 will be returned. If there are job placement issues encountered (unsatisfiable constraints, resource @@ -108,17 +108,32 @@ that volume. ## Examples -Schedule the job contained in the file `job1.nomad`, monitoring placement: +Schedule the job contained in the file `job1.nomad`, monitoring placement and deployment: ```shell-session $ nomad job run job1.nomad -==> Monitoring evaluation "52dee78a" - Evaluation triggered by job "example" - Evaluation within deployment: "62eb607c" - Allocation "5e0b39f0" created: node "3e84d3d2", group "group1" - Allocation "5e0b39f0" status changed: "pending" -> "running" - Evaluation status changed: "pending" -> "complete" -==> Evaluation "52dee78a" finished with status "complete" +==> 2021-06-09T15:22:58-07:00: Monitoring evaluation "52dee78a" + 2021-06-09T15:22:58-07:00: Evaluation triggered by job "example" + 2021-06-09T15:22:58-07:00: Allocation "5e0b39f0" created: node "3e84d3d2", group "group1" +==> 2021-06-09T15:22:59-07:00: Monitoring evaluation "52dee78a" + 2021-06-09T15:22:59-07:00: Evaluation within deployment: "62eb607c" + 2021-06-09T15:22:59-07:00: Allocation "5e0b39f0" status changed: "pending" -> "running" + 2021-06-09T15:22:59-07:00: Evaluation status changed: "pending" -> "complete" +==> 2021-06-09T15:22:59-07:00: Evaluation "52dee78a" finished with status "complete" +==> 2021-06-09T15:22:59-07:00: Monitoring deployment "62eb607c" + ⠦ Deployment "62eb607c" in progress... + + 2021-06-09T15:22:59-07:00 + ID = 62eb607c + Job ID = example + Job Version = 0 + Status = running + Description = Deployment is running + + Deployed + Task Group Desired Placed Healthy Unhealthy Progress Deadline + cache 2 2 1 0 2021-06-09T15:32:58-07:00 + web 1 1 1 0 2021-06-09T15:32:58-07:00 ``` Update the job using `check-index`: @@ -129,12 +144,26 @@ Enforcing job modify index 5: job exists with conflicting job modify index: 6 Job not updated $ nomad job run -check-index 6 example.nomad -==> Monitoring evaluation "5ef16dff" - Evaluation triggered by job "example" - Evaluation within deployment: "62eb607c" - Allocation "6ec7d16f" modified: node "6e1f9bf6", group "cache" - Evaluation status changed: "pending" -> "complete" -==> Evaluation "5ef16dff" finished with status "complete" +==> 2021-06-09T16:57:29-07:00: Monitoring evaluation "5ef16dff" + 2021-06-09T16:57:29-07:00: Evaluation triggered by job "example" + 2021-06-09T16:57:29-07:00: Allocation "6ec7d16f" modified: node "6e1f9bf6", group "cache" +==> 2021-06-09T16:57:30-07:00: Monitoring evaluation "5ef16dff" + 2021-06-09T16:57:30-07:00: Evaluation within deployment: "62eb607c" + 2021-06-09T16:57:30-07:00: Evaluation status changed: "pending" -> "complete" +==> 2021-06-09T16:57:30-07:00: Evaluation "5ef16dff" finished with status "complete" +==> 2021-06-09T16:57:30-07:00: Monitoring deployment "62eb607c" + ⠙ Deployment "62eb607c" successful + + 2021-06-09T16:57:30-07:00 + ID = 62eb607c + Job ID = example + Job Version = 2 + Status = successful + Description = Deployment completed successfully + + Deployed + Task Group Desired Placed Healthy Unhealthy Progress Deadline + cache 1 1 1 0 2021-06-09T17:07:00-07:00 ``` Schedule the job contained in `job1.nomad` and return immediately: @@ -150,17 +179,33 @@ failure and the specifics of the placement are printed: ```shell-session $ nomad job run failing.nomad -==> Monitoring evaluation "2ae0e6a5" - Evaluation triggered by job "example" - Evaluation status changed: "pending" -> "complete" -==> Evaluation "2ae0e6a5" finished with status "complete" but failed to place all allocations: - Task Group "cache" (failed to place 1 allocation): +==> 2021-06-09T16:49:00-07:00: Monitoring evaluation "2ae0e6a5" + 2021-06-09T16:49:00-07:00: Evaluation triggered by job "example" +==> 2021-06-09T16:49:01-07:00: Monitoring evaluation "2ae0e6a5" + 2021-06-09T16:49:01-07:00: Evaluation within deployment: "db0c5e57" + 2021-06-09T16:49:01-07:00: Evaluation status changed: "pending" -> "complete" +==> 2021-06-09T16:49:01-07:00: Evaluation "2ae0e6a5" finished with status "complete" but failed to place all allocations: + 2021-06-09T16:49:01-07:00: Task Group "cache" (failed to place 1 allocation): * Class "foo" filtered 1 nodes * Constraint "${attr.kernel.name} = linux" filtered 1 nodes - Evaluation "67493a64" waiting for additional capacity to place remainder + 2021-06-09T16:49:01-07:00: Evaluation "67493a64" waiting for additional capacity to place remainder +==> 2021-06-09T16:49:01-07:00: Monitoring deployment "db0c5e57" + ⠧ Deployment "db0c5e57" in progress... + + 2021-06-09T16:49:03-07:00 + ID = db0c5e57 + Job ID = example + Job Version = 8 + Status = running + Description = Deployment is running + + Deployed + Task Group Desired Placed Healthy Unhealthy Progress Deadline + cache 1 0 0 0 N/A ``` [`go-getter`]: https://github.com/hashicorp/go-getter +[deployment status]: /docs/commands/deployment#status [`job plan` command]: /docs/commands/job/plan [eval status]: /docs/commands/eval-status [job specification]: /docs/job-specification