From 19c772932bf673b30be236d656d3a88c7301ec1e Mon Sep 17 00:00:00 2001 From: James Rasell Date: Fri, 6 Nov 2020 16:30:24 +0100 Subject: [PATCH] docs: add recommendation CLI documentation. (#9288) Co-authored-by: Chris Baker <1675087+cgbaker@users.noreply.github.com> --- website/data/docs-navigation.js | 17 ++--- .../docs/commands/recommendation/apply.mdx | 68 +++++++++++++++++++ .../docs/commands/recommendation/dismiss.mdx | 37 ++++++++++ .../docs/commands/recommendation/index.mdx | 31 +++++++++ .../docs/commands/recommendation/info.mdx | 57 ++++++++++++++++ .../docs/commands/recommendation/list.mdx | 61 +++++++++++++++++ 6 files changed, 263 insertions(+), 8 deletions(-) create mode 100644 website/pages/docs/commands/recommendation/apply.mdx create mode 100644 website/pages/docs/commands/recommendation/dismiss.mdx create mode 100644 website/pages/docs/commands/recommendation/index.mdx create mode 100644 website/pages/docs/commands/recommendation/info.mdx create mode 100644 website/pages/docs/commands/recommendation/list.mdx diff --git a/website/data/docs-navigation.js b/website/data/docs-navigation.js index 024801488..4af40c48c 100644 --- a/website/data/docs-navigation.js +++ b/website/data/docs-navigation.js @@ -30,7 +30,7 @@ export default [ 'windows-service', ], }, - { category: 'upgrade', content: ['upgrade-specific'] }, + {category: 'upgrade', content: ['upgrade-specific']}, { category: 'integrations', content: ['consul-integration', 'consul-connect', 'vault-integration'], @@ -167,16 +167,17 @@ export default [ 'snapshot-save', ], }, - { category: 'plugin', content: ['status'] }, + {category: 'plugin', content: ['status']}, { category: 'quota', content: ['apply', 'delete', 'init', 'inspect', 'list', 'status'], }, - { category: 'scaling', content: ['policy-info', 'policy-list'] }, - { category: 'sentinel', content: ['apply', 'delete', 'list', 'read'] }, - { category: 'server', content: ['force-leave', 'join', 'members'] }, + {category: 'recommendation', content: ['apply', 'dismiss', 'info', 'list']}, + {category: 'scaling', content: ['policy-info', 'policy-list']}, + {category: 'sentinel', content: ['apply', 'delete', 'list', 'read']}, + {category: 'server', content: ['force-leave', 'join', 'members']}, 'status', - { category: 'system', content: ['gc', 'reconcile-summaries'] }, + {category: 'system', content: ['gc', 'reconcile-summaries']}, 'ui', 'version', { @@ -260,7 +261,7 @@ export default [ content: ['nvidia', 'community'], }, 'schedulers', - { category: 'runtime', content: ['environment', 'interpolation'] }, + {category: 'runtime', content: ['environment', 'interpolation']}, { category: 'autoscaling', content: [ @@ -279,7 +280,7 @@ export default [ }, ], }, - { category: 'telemetry', content: ['metrics'] }, + {category: 'telemetry', content: ['metrics']}, '------------', 'enterprise', 'faq', diff --git a/website/pages/docs/commands/recommendation/apply.mdx b/website/pages/docs/commands/recommendation/apply.mdx new file mode 100644 index 000000000..4a13a6f0c --- /dev/null +++ b/website/pages/docs/commands/recommendation/apply.mdx @@ -0,0 +1,68 @@ +--- +layout: docs +page_title: 'Commands: recommendation apply' +sidebar_title: apply +description: | + The recommendation apply command is used to apply recommendations. +--- + +# Command: recommendation apply + +The `recommendation apply` command is used to apply recommendations. + +~> Recommendation commands are new in Nomad 1.0 and are only available with +Nomad Enterprise. + +## Usage + +```plaintext +nomad recommendation apply [options] +``` + +The `recommendation apply` command requires at least one recommendation ID to +be passed to it. Multiple IDs can be passed, with each recommendation ID +separated from the next by a space. + +## General Options + +@include 'general_options.mdx' + +## Apply Options + +- `-detach`: Return immediately instead of entering monitor mode. After applying + a recommendation, the evaluation ID will be printed to the screen, which can + be used to examine the evaluation using the [`eval status`][/docs/commands/eval-status] command. If applying + recommendations for multiple jobs, this value will always be true. + +- `-policy-override`: If set, any soft mandatory Sentinel policies will be + overridden. This allows a recommendation to be applied when it would be denied + by a policy. + +- `-verbose`: Display full information. + +## Examples + +Apply a single recommendation and enter monitor mode: + +```shell-session +$ nomad recommendation apply a9c041c5-3c04-aa24-bd55-0a80cded4f10 +==> Monitoring evaluation "529cc88e" + Evaluation triggered by job "job1" + Evaluation within deployment: "28a3378f" + Allocation "2a4df8ca" created: node "2f0a2f93", group "group1" + Evaluation status changed: "pending" -> "complete" +==> Evaluation "529cc88e" finished with status "complete" +``` + +Apply multiple recommendations for different jobs: + +```shell-session +$ nomad recommendation apply a9c041c5-3c04-aa24-bd55-0a80cded4f10 811900b6-da11-ef08-f515-f5e6684007a8 +Errors +None + +Results +IDs Namespace Job ID Eval ID Warnings +a9c041c5-3c04-aa24-bd55-0a80cded4f10 default example 7c39ad13-0246-ab8e-6c50-9f3ee500bf5f +811900b6-da11-ef08-f515-f5e6684007a8 default demoapp 68236421-c90f-efa6-fc02-37ae2d59bf03 +``` diff --git a/website/pages/docs/commands/recommendation/dismiss.mdx b/website/pages/docs/commands/recommendation/dismiss.mdx new file mode 100644 index 000000000..e168c5f62 --- /dev/null +++ b/website/pages/docs/commands/recommendation/dismiss.mdx @@ -0,0 +1,37 @@ +--- +layout: docs +page_title: 'Commands: recommendation dismiss' +sidebar_title: dismiss +description: | + The recommendation dismiss command is used to dismiss recommendations. +--- + +# Command: recommendation dismiss + +The `recommendation dismiss` command is used to dismiss recommendations. + +~> Recommendation commands are new in Nomad 1.0 and are only available with +Nomad Enterprise. + +## Usage + +```plaintext +nomad recommendation dismiss [options] +``` + +The `recommendation dismiss` command requires at least one recommendation ID +to be passed to it. Multiple IDs can be passed, with each recommendation ID +separated from the next by a space. + +## General Options + +@include 'general_options.mdx' + +## Examples + +Dismiss a single recommendation: + +```shell-session +$ nomad recommendation dismiss a9c041c5-3c04-aa24-bd55-0a80cded4f10 +Successfully dismissed recommendation +``` diff --git a/website/pages/docs/commands/recommendation/index.mdx b/website/pages/docs/commands/recommendation/index.mdx new file mode 100644 index 000000000..477b3f84a --- /dev/null +++ b/website/pages/docs/commands/recommendation/index.mdx @@ -0,0 +1,31 @@ +--- +layout: docs +page_title: 'Commands: recommendation' +sidebar_title: recommendation +description: | + The recommendation command is used to interact with recommendations. +--- + +# Command: recommendation + +The `recommendation` command is used to interact with recommendations. + +~> Recommendation commands are new in Nomad 1.0 and are only available with +Nomad Enterprise. + +## Usage + +Usage: `nomad recommendation [options]` + +Run `nomad recommendation -h` for help on that subcommand. The following +subcommands are available: + +- [`recommendation apply`][recommendationapply] - Apply one or more Nomad recommendations +- [`recommendation dismiss`][recommendationdismiss] - Dismiss one or more Nomad recommendations +- [`recommendation info`][recommendationinfo] - Display an individual Nomad recommendation +- [`recommendation list`][recommendationlist] - Display all Nomad recommendations + +[recommendationapply]: /docs/commands/recommendation/apply +[recommendationdismiss]: /docs/commands/recommendation/dismiss +[recommendationinfo]: /docs/commands/recommendation/info +[recommendationlist]: /docs/commands/recommendation/list diff --git a/website/pages/docs/commands/recommendation/info.mdx b/website/pages/docs/commands/recommendation/info.mdx new file mode 100644 index 000000000..0536b4e73 --- /dev/null +++ b/website/pages/docs/commands/recommendation/info.mdx @@ -0,0 +1,57 @@ +--- +layout: docs +page_title: 'Commands: recommendation info' +sidebar_title: info +description: | + The recommendation info command is used to read the specified recommendation. +--- + +# Command: recommendation info + +The `recommendation info` command is used to read the specified recommendation. + +~> Recommendation commands are new in Nomad 1.0 and are only available with +Nomad Enterprise. + +## Usage + +```plaintext +nomad recommendation info [options] +``` + +The `recommendation info` command requires a single argument, a recommendation ID. + +## General Options + +@include 'general_options.mdx' + +## Info Options + +- `-json` : Output the recommendation in its JSON format. + +- `-t` : Format and display the recommendation using a Go template. + +## Examples + +View the information of a specific recommendation: + +```shell-session +$ nomad recommendation info 68236421-c90f-efa6-fc02-37ae2d59bf03 +ID = 68236421-c90f-efa6-fc02-37ae2d59bf03 +Namespace = default +Job ID = example +Task Group = cache +Task = redis +Resource = CPU +Value = 57 +Current = 500 + +Stats +max mean min p99 +5.89 1.66 0.44 5.89 + +Meta +nomad_policy_id = e20dc742-dd5d-5419-8add-c5e0233933f5 +num_evaluated_windows = 2 +window_size = 3e+11 +``` diff --git a/website/pages/docs/commands/recommendation/list.mdx b/website/pages/docs/commands/recommendation/list.mdx new file mode 100644 index 000000000..630c00be5 --- /dev/null +++ b/website/pages/docs/commands/recommendation/list.mdx @@ -0,0 +1,61 @@ +--- +layout: docs +page_title: 'Commands: recommendation list' +sidebar_title: list +description: | + The recommendation list command is used to list the available recommendations. +--- + +# Command: recommendation list + +The `recommendation list` command is used to list the available recommendations. + +~> Recommendation commands are new in Nomad 1.0 and are only available with +Nomad Enterprise. + +## Usage + +```plaintext +nomad recommendation list [options] +``` + +The `recommendation list` command requires no arguments. + +## General Options + +@include 'general_options.mdx' + +## List Options + +- `-job`: Specifies the job ID to filter the recommendations list by. + +- `-group`: Specifies the task group name to filter within a job. If specified, + the `-job` flag must also be specified. + +- `-task`: Specifies the task name to filter within a job and task group. If + specified, the `-job` and `-group` flags must also be specified. + +- `-json`: Output the recommendations in its JSON format. + +- `-t`: Format and display the recommendations using a Go template. + +## Examples + +List all available recommendations: + +```shell-session +$ nomad recommendation list +ID Job Group Task Resource Value +ea130ac3-1410-cfe0-f34d-adc3ca94712d example cache-lb nginx CPU 57 +68236421-c90f-efa6-fc02-37ae2d59bf03 example cache redis CPU 57 +980c2554-7a1b-0c51-933a-f46850a228bd example cache redis MemoryMB 10 +``` + +List all available recommendations for the job `example` and the task group `cache`: + +```shell-session +$ nomad recommendation list -job=example -group=cache +ID Job Group Task Resource Value +68236421-c90f-efa6-fc02-37ae2d59bf03 example cache redis CPU 57 +980c2554-7a1b-0c51-933a-f46850a228bd example cache redis MemoryMB 10 +```