From ab1af24e904ac09ebdb1f079ffd383e4fcea3760 Mon Sep 17 00:00:00 2001 From: Tim Gross Date: Tue, 14 Dec 2021 11:59:48 -0500 Subject: [PATCH] docs: nomad eval list Also includes note that `nomad eval status -json` is deprecated and will be replaced with a single evaluation view in a future version of Nomad. --- website/content/docs/commands/eval/index.mdx | 23 +++++++++ website/content/docs/commands/eval/list.mdx | 51 +++++++++++++++++++ .../{eval-status.mdx => eval/status.mdx} | 5 +- .../content/docs/upgrade/upgrade-specific.mdx | 10 ++++ website/data/docs-nav-data.json | 17 ++++++- website/redirects.js | 5 ++ 6 files changed, 108 insertions(+), 3 deletions(-) create mode 100644 website/content/docs/commands/eval/index.mdx create mode 100644 website/content/docs/commands/eval/list.mdx rename website/content/docs/commands/{eval-status.mdx => eval/status.mdx} (91%) diff --git a/website/content/docs/commands/eval/index.mdx b/website/content/docs/commands/eval/index.mdx new file mode 100644 index 00000000000..504cd8a1777 --- /dev/null +++ b/website/content/docs/commands/eval/index.mdx @@ -0,0 +1,23 @@ +--- +layout: docs +page_title: 'Commands: eval' +description: | + The eval command is used to interact with evals. +--- + +# Command: eval + +The `eval` command is used to interact with evals. + +## Usage + +Usage: `nomad eval [options]` + +Run `nomad eval -h` for help on that subcommand. The following +subcommands are available: + +- [`eval list`][list] - List all evals +- [`eval status`][status] - Display the status of a eval + +[list]: /docs/commands/eval/list 'List all evals' +[status]: /docs/commands/eval/status 'Display the status of a eval' diff --git a/website/content/docs/commands/eval/list.mdx b/website/content/docs/commands/eval/list.mdx new file mode 100644 index 00000000000..fe53a6ed31a --- /dev/null +++ b/website/content/docs/commands/eval/list.mdx @@ -0,0 +1,51 @@ +--- +layout: docs +page_title: 'Commands: eval list' +description: | + The eval list command is used to list evaluations. +--- + +# Command: eval list + +The `eval list` command is used list all evaluations. + +## Usage + +```plaintext +nomad eval list [options] +``` + +The `eval list` command requires no arguments. + +When ACLs are enabled, this command requires a token with the 'read-job' +capability for the requested namespace. + +## General Options + +@include 'general_options.mdx' + +## List Options + +- `-verbose`: Show full information. +- `-per_page`: How many results to show per page. +- `-page_token`: Where to start pagination. +- `-job`: Only show evaluations for this job ID. +- `-status`: Only show evaluations with this status. +- `-json`: Output the evaluation in its JSON format. +- `-t`: Format and display evaluation using a Go template. + +## Examples + +List all tracked evaluations: + +```shell-session +$ nomad eval list -per_page 3 -status complete +ID Priority Triggered By Job ID Status Placement Failures +456e37aa 50 deployment-watcher example complete false +1a1eafe6 50 alloc-stop example complete false +3411e37b 50 job-register example complete false + +Results have been paginated. To get the next page run: + +nomad eval list -page_token 9ecffbba-73be-d909-5d7e-ac2694c10e0c +``` diff --git a/website/content/docs/commands/eval-status.mdx b/website/content/docs/commands/eval/status.mdx similarity index 91% rename from website/content/docs/commands/eval-status.mdx rename to website/content/docs/commands/eval/status.mdx index 6d93efc4693..f89bb603b05 100644 --- a/website/content/docs/commands/eval-status.mdx +++ b/website/content/docs/commands/eval/status.mdx @@ -45,7 +45,10 @@ indicated by exit code 1. - `-monitor`: Monitor an outstanding evaluation - `-verbose`: Show full information. -- `-json` : Output the evaluation in its JSON format. +- `-json` : Output a list of all evaluations in JSON format. This + behavior is deprecated and has been replaced by `nomad eval list + -json`. In Nomad 1.4.0 the behavior of this option will change to + output only the selected evaluation in JSON. - `-t` : Format and display evaluation using a Go template. ## Examples diff --git a/website/content/docs/upgrade/upgrade-specific.mdx b/website/content/docs/upgrade/upgrade-specific.mdx index 1035bd56d34..90b5a95a2b9 100644 --- a/website/content/docs/upgrade/upgrade-specific.mdx +++ b/website/content/docs/upgrade/upgrade-specific.mdx @@ -13,6 +13,16 @@ upgrade. However, specific versions of Nomad may have more details provided for their upgrades as a result of new features or changed behavior. This page is used to document those details separately from the standard upgrade flow. +## Nomad 1.2.4 + +#### `nomad eval status -json` deprecated + +Nomad 1.2.4 includes a new `nomad eval list` command that has the +option to display the results in JSON format with the `-json` +flag. This replaces the existing `nomad eval status -json` option. In +Nomad 1.4.0, `nomad eval status -json` will be changed to display only +the selected evaluation in JSON format. + ## Nomad 1.2.2 ### Panic on node class filtering for system and sysbatch jobs fixed diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index 51ce0a2af9e..28f67624c5f 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -353,8 +353,21 @@ ] }, { - "title": "eval status", - "path": "commands/eval-status" + "title": "eval", + "routes": [ + { + "title": "Overview", + "path": "commands/eval" + }, + { + "title": "list", + "path": "commands/eval/list" + }, + { + "title": "status", + "path": "commands/eval/status" + } + ] }, { "title": "job", diff --git a/website/redirects.js b/website/redirects.js index 48a206b7f66..0ed8488b8b2 100644 --- a/website/redirects.js +++ b/website/redirects.js @@ -589,6 +589,11 @@ module.exports = [ destination: '/docs/commands/alloc/status', permanent: true, }, + { + source: '/docs/commands/eval-status', + destination: '/docs/commands/eval/status', + permanent: true, + }, { source: '/docs/commands/fs', destination: '/docs/commands/alloc/fs',