From cbd49a7085c548399deaf753e73f74c7c6eb4005 Mon Sep 17 00:00:00 2001 From: James Rasell Date: Fri, 1 Jul 2022 14:50:01 +0100 Subject: [PATCH] docs: add eval delete website doucmentation. --- .changelog/13492.txt | 7 ++ website/content/api-docs/evaluations.mdx | 51 +++++++++++++ website/content/docs/commands/eval/delete.mdx | 75 +++++++++++++++++++ website/content/docs/commands/eval/index.mdx | 3 +- website/data/docs-nav-data.json | 4 + 5 files changed, 139 insertions(+), 1 deletion(-) create mode 100644 .changelog/13492.txt create mode 100644 website/content/docs/commands/eval/delete.mdx diff --git a/.changelog/13492.txt b/.changelog/13492.txt new file mode 100644 index 000000000000..73e01837d2ba --- /dev/null +++ b/.changelog/13492.txt @@ -0,0 +1,7 @@ +```release-note:improvement +cli: Added `delete` command to the eval CLI +``` + +```release-note:improvement +agent: Added delete support to the eval HTTP API +``` diff --git a/website/content/api-docs/evaluations.mdx b/website/content/api-docs/evaluations.mdx index bea826da6529..0a36a6f5ef6e 100644 --- a/website/content/api-docs/evaluations.mdx +++ b/website/content/api-docs/evaluations.mdx @@ -204,6 +204,55 @@ $ curl \ } ``` +## Delete Evaluations + +This endpoint deletes evaluations. In order to utilise this endpoint the +eval broker should be paused via the +[update_scheduler_configuration][operator scheduler update configuration] API +endpoint. + +This API endpoint should be used cautiously and only in outage situations where +there is a large backlog of evaluations not being processed. During most normal +and outage scenarios, Nomad's reconciliation and state management will handle +evaluations as needed. + +| Method | Path | Produces | +| --------- | ----------------- | ------------------ | +| `DELETE` | `/v1/evaluations` | `application/json` | + +The table below shows this endpoint's support for +[blocking queries](/api-docs#blocking-queries) and +[required ACLs](/api-docs#acls). + +| Blocking Queries | ACL Required | +| ---------------- | ------------ | +| `NO` | `management` | + +### Parameters + +- `EvalIDs` `(array: )`- An array of evaluation UUIDs to + delete. This must be a full length UUID and not a prefix. + +### Sample Payload + +```javascript +{ + "EvalIDs": [ + "167ec27d-2e36-979a-280a-a6b920d382db", + "6c193955-ac66-42e2-f4c7-f1fc707f1f5e" + ] +} +``` + +### Sample Request + +```shell-session +$ curl \ + --request DELETE \ + --data @payload.json \ + https://localhost:4646/v1/evaluations +``` + ## List Allocations for Evaluation This endpoint lists the allocations created or modified for the given @@ -332,3 +381,5 @@ $ curl \ } ] ``` + +[update_scheduler_configuration]: api-docs/operator/scheduler#update-scheduler-configuration diff --git a/website/content/docs/commands/eval/delete.mdx b/website/content/docs/commands/eval/delete.mdx new file mode 100644 index 000000000000..42cf5125eb4f --- /dev/null +++ b/website/content/docs/commands/eval/delete.mdx @@ -0,0 +1,75 @@ +--- +layout: docs +page_title: 'Commands: eval delete' +description: | + The eval delete command is used to delete evaluations. +--- + +# Command: eval delete + +The `eval delete` command is used to delete evaluations. It should be used +cautiously and only in outage situations where there is a large backlog of +evaluations not being processed. During most normal and outage scenarios, +Nomad's reconciliation and state management will handle evaluations as needed. + +The eval broker is expected to be paused prior to running this command and +un-paused after. These actions can be performed by the +[`operator scheduler get-config`][scheduler_get_config] +and [`operator scheduler set-config`][scheduler_set_config] commands respectively. + +## Usage + +```plaintext +nomad eval delete [options] [args] +``` + +It takes an optional argument which is the ID of the evaluation to delete. If +the evaluation ID is omitted, this command will use the filter flag to identify +and delete a set of evaluations. + +When ACLs are enabled, this command requires a `management` token. + +## General Options + +@include 'general_options.mdx' + +## Delete Options + +- `-filter`: Specifies an expression used to filter evaluations by for + deletion. + +- `-yes`: Bypass the confirmation prompt if an evaluation ID was not provided. + +## Examples + +Delete an evaluation using its ID: + +```shell-session +$ nomad eval delete 9ecffbba-73be-d909-5d7e-ac2694c10e0c +Successfuly deleted 1 evaluation +``` + +Delete all evaluations with status `pending` for the `example` job: +```shell-session +$ nomad eval delete -filter='Stauts == "pending" and JobID == "example"' +Do you want to list evals (3) before deletion? [y/N] y + +ID Priority Triggered By Job ID Status Placement Failures +cef92121 50 job-register example pending false +1c905ca0 50 job-register example pending false +b9e77692 50 job-register example pending false + +Are you sure you want to delete 3 evals? [y/N] y + +Successfuly deleted 3 evaluations +``` + +Delete all evaluations for the `system` and `service` whilst skipping all +prompts: +```shell-session +$ nomad eval delete -filter='Scheduler == "system" or Scheduler == "service"' -yes +Successfuly deleted 23 evaluations +``` + +[scheduler_get_config]: /docs/commands/operator/scheduler-get-config +[scheduler_set_config]: /docs/commands/operator/scheduler-set-config diff --git a/website/content/docs/commands/eval/index.mdx b/website/content/docs/commands/eval/index.mdx index 504cd8a17772..3b8e4b6c8447 100644 --- a/website/content/docs/commands/eval/index.mdx +++ b/website/content/docs/commands/eval/index.mdx @@ -15,9 +15,10 @@ Usage: `nomad eval [options]` Run `nomad eval -h` for help on that subcommand. The following subcommands are available: - +- [`eval delete`][delete] - Delete evals - [`eval list`][list] - List all evals - [`eval status`][status] - Display the status of a eval +[delete]: /docs/commands/eval/delete 'Delete evals' [list]: /docs/commands/eval/list 'List all evals' [status]: /docs/commands/eval/status 'Display the status of a eval' diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index 50199de2a2eb..bd116674692a 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -372,6 +372,10 @@ "title": "Overview", "path": "commands/eval" }, + { + "title": "delete", + "path": "commands/eval/delete" + }, { "title": "list", "path": "commands/eval/list"