From 690abefc4adb5ffa7ae29aeb10e3434efc34e453 Mon Sep 17 00:00:00 2001 From: Michael Schurter Date: Wed, 29 May 2024 14:04:25 -0700 Subject: [PATCH] docs: add docs for time based task execution --- command/alloc_pause.go | 12 ++- website/content/api-docs/allocations.mdx | 84 ++++++++++++++++++- website/content/docs/commands/alloc/pause.mdx | 74 ++++++++++++++++ .../docs/job-specification/schedule.mdx | 73 ++++++++++++++++ website/data/docs-nav-data.json | 8 ++ 5 files changed, 243 insertions(+), 8 deletions(-) create mode 100644 website/content/docs/commands/alloc/pause.mdx create mode 100644 website/content/docs/job-specification/schedule.mdx diff --git a/command/alloc_pause.go b/command/alloc_pause.go index f1b9d09e6..b412e5d97 100644 --- a/command/alloc_pause.go +++ b/command/alloc_pause.go @@ -22,11 +22,10 @@ func (c *AllocPauseCommand) Help() string { Usage: nomad alloc pause [options] Set the pause state of an allocation. This command is used to suspend the - operation of a specific alloc and its subtasks. If no task is provided then - all of the allocations subtasks will assume the new pause state. + operation of a specific task. - When ACLs are enabled, this command requires a token with the 'write-job' - capability for the allocation's namespace. + When ACLs are enabled, this command requires the job-submit capability for + the allocation's namespace. General Options: @@ -36,9 +35,8 @@ Pause Specific Options: -state= Specify the schedule state to apply to a task. Must be one of pause, run, - or scheduled. When set to pause the task is halted but the client reports - to the server that the task is still running. When set to run the task is - started regardless of the task schedule. When in scheduled state the task + or scheduled. When set to pause the task is halted. When set to run the task + is started regardless of the task schedule. When in scheduled state the task respects the task schedule state in the task configuration. Defaults to pause. diff --git a/website/content/api-docs/allocations.mdx b/website/content/api-docs/allocations.mdx index 5176a3b38..65eded2e2 100644 --- a/website/content/api-docs/allocations.mdx +++ b/website/content/api-docs/allocations.mdx @@ -927,7 +927,7 @@ The table below shows this endpoint's support for | Blocking Queries | ACL Required | | ---------------- | --------------------- | -| `NO` | `namespace:read-job`` | +| `NO` | `namespace:read-job` | ### Parameters @@ -958,4 +958,86 @@ $ curl \ } ``` +## Override Pause Schedule State + + + +The endpoint is used to override the [`schedule`][schedule] for tasks using +time based execution. + +| Method | Path | Produces | +| -------------- | --------------------------------------- | ------------------ | +| `POST` / `PUT` | `/v1/client/allocation/:alloc_id/pause` | `application/json` | + +The table below shows this endpoint's support for +[blocking queries](/nomad/api-docs#blocking-queries) and +[required ACLs](/nomad/api-docs#acls). + +| Blocking Queries | ACL Required | +| ---------------- | --------------------------- | +| `NO` | `namespace:job-submit` | + +### Parameters + +- `:alloc_id` `(string: )`- Specifies the UUID of the allocation. This + must be the full UUID, not the short 8-character one. This is specified as + part of the path. + +### Sample Request + +```shell-session +$ echo '{"Task": "schedtask", "ScheduleState": "run"}' | \ + nomad operator api /v1/client/allocation/23f520cc-629a-46ff-395f-0661e7aa939e/pause +``` + +### Sample Response + +```json +{ + "Index": 0 +} +``` + +## Read Pause Schedule State + + + +Retrieve the [`schedule`][schedule] state for a task using time based execution. + +| Method | Path | Produces | +| ------ | --------------------------------------- | ------------------ | +| `GET` | `/v1/client/allocation/:alloc_id/pause` | `application/json` | + +The table below shows this endpoint's support for +[blocking queries](/nomad/api-docs#blocking-queries) and +[required ACLs](/nomad/api-docs#acls). + +| Blocking Queries | ACL Required | +| ---------------- | ------------------------- | +| `NO` | `namespace:read-job` | + +### Parameters + +- `:alloc_id` `(string: )`- Specifies the UUID of the allocation. This + must be the full UUID, not the short 8-character one. This is specified as + part of the path. + +- `task` - Specifies the task from which to retrieve the time based task + execution state. + +### Sample Request + +```shell-session +$ nomad operator api /v1/client/allocation/23f520cc-629a-46ff-395f-0661e7aa939e/pause?task=schedtask +``` + +### Sample Response + +```json +{ + "ScheduleState": "scheduled_pause" +} +``` + [`shutdown_delay`]: /nomad/docs/job-specification/group#shutdown_delay +[schedule]: /nomad/docs/job-specification/schedule diff --git a/website/content/docs/commands/alloc/pause.mdx b/website/content/docs/commands/alloc/pause.mdx new file mode 100644 index 000000000..928189680 --- /dev/null +++ b/website/content/docs/commands/alloc/pause.mdx @@ -0,0 +1,74 @@ +--- +layout: docs +page_title: 'Commands: alloc pause' +description: | + Override the schedule for tasks using time based execution. +--- + +# Command: alloc pause + + + +~> **Note:** Time based task execution is an experimental feature and subject +to change.Please refer to the [Upgrade Guide][upgrade] to find breaking +changes. + +Override the schedule for tasks using time based execution. + +## Usage + +```plaintext +nomad alloc pause [options] +``` + +The `alloc pause` command allows a user to override the schedule for tasks +that use time based execution. A user may override a task's +[`schedule`][schedule] and force it to run or stop. The `schedule` will be +ignored until a user resets the override. + +When ACLs are enabled, this command requires the `job-submit` capability for +the allocation's namespace. + +## General Options + +@include 'general_options.mdx' + +## Pause Options + +- `-state`: Override the current scheduled task state to be the specifed state + or reset to the scheduled state. Must be one of `pause`, `run`, or + `scheduled`. When set to `pause` the task is halted. When set to `run` the + task is started. When set to `scheduled` the task respects its + [`schedule`][schedule]. + +- `-status`: Get the current time based task execution state. + +- `-task`: Override the schedule of the specified task. May also be specified + as a positional argument. + +- `-verbose`: Show full information. + +## Examples + +The following command stops the `schedtask` task of the allocation `4d37a9d1` +overriding the task's [`schedule`][schedule] block: + +```shell-session +$ nomad alloc pause -state=pause 4d37a9d1 schedtask +``` + +The following command runs the task overriding the tasks current state or +schedule: + +```shell-session +$ nomad alloc pause -state=pause 4d37a9d1 schedtask +``` + +The following command returns the task to its [`schedule`][schedule]: + +```shell-session +$ nomad alloc pause -state=scheduled 4d37a9d1 schedtask +``` + +[schedule]: /nomad/docs/job-specification/schedule +[upgrade]: /nomad/docs/upgrade/upgrade-specific diff --git a/website/content/docs/job-specification/schedule.mdx b/website/content/docs/job-specification/schedule.mdx new file mode 100644 index 000000000..c1b79d0d1 --- /dev/null +++ b/website/content/docs/job-specification/schedule.mdx @@ -0,0 +1,73 @@ +--- +layout: docs +page_title: schedule Block - Job Specification +description: |- + Time based task execution is enabled by using the "schedule" task block. +--- + +# `schedule` Block + + + + + +~> **Note:** Time based task execution is an experimental feature and subject +to change.Please refer to the [Upgrade Guide][upgrade] to find breaking +changes. + +Time based task execution is enabled by using the `schedule` block. The +`schedule` block controls when a task is allowed to be running. + +Unlike [`periodic`][periodic] jobs, the `schedule` block applies to individual +tasks. The Nomad Client starts and stops tasks at the specified time without +interaction with the Nomad Servers. This means time based task execution works +even when a Client is disconnected from Servers. The task's resources remain +allocated even outside the `schedule` when the task itself is stopped. + +```hcl +job "docs" { + group "tbte" { + task "scheduled" { + schedule { + cron { + start = "30 9 * * MON-FRI *" + end = "0 16" + timezone = "America/New_York" + } + } + } + } +} +``` + +## `schedule` Parameters + +The `schedule` block must have a `cron` block containing: + +- `start` `(string: )` - When the task should be started. Specified in 6 field + [cron format][cron] (no seconds) without `,` or `/` characters. + +- `end` `(string: )` - When the task should be stopped + ([`kill_signal`][kill_signal] and [`kill_timeout`][kill_timeout] apply). + Specified in 2 field [cron format][cron] (minute and hour) without `,` or `/` + characters. + +- `timezone` `(string: "Local")` - What time zone the `start` and `end` times + are specified in. Defaults to the local time zone of the Nomad Client the job + is scheduled onto. + +## Limitations + +- Job deployments outside of the specified `schedule` will be unable to + succeed. To update a job using time based task execution outside of its + schedule, do a [force + update](/nomad/docs/job-specification/update#max_parallel-0). + +- Overnight schedules are currently not supported. Adjusting the `timezone` + should allow converting overnight schedules to times within a single day. + +[periodic]: /nomad/docs/job-specification/periodic +[kill_signal]: /nomad/docs/job-specification/task#kill_signal +[kill_timeout]: /nomad/docs/job-specification/task#kill_timeout +[cron]: https://github.com/hashicorp/cronexpr#implementation 'List of cron expressions' +[upgrade]: /nomad/docs/upgrade/upgrade-specific diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index 2afde25ae..ac24c786d 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -454,6 +454,10 @@ "title": "logs", "path": "commands/alloc/logs" }, + { + "title": "pause", + "path": "commands/alloc/pause" + }, { "title": "restart", "path": "commands/alloc/restart" @@ -1797,6 +1801,10 @@ "title": "scaling", "path": "job-specification/scaling" }, + { + "title": "schedule", + "path": "job-specification/schedule" + }, { "title": "service", "path": "job-specification/service"