docs: add docs for time based task execution

command/alloc_pause.go

@@ -22,11 +22,10 @@ func (c *AllocPauseCommand) Help() string {
 Usage: nomad alloc pause [options] <allocation> <task>
 
   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=<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.
 

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
+
+<EnterpriseAlert />
+
+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: <required>)`- 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
+
+<EnterpriseAlert />
+
+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: <required>)`- 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

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
+
+<EnterpriseAlert />
+
+~> **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] <allocation> <command>
+```
+
+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

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
+
+<EnterpriseAlert />
+
+<Placement groups={['job', 'group', 'task', 'periodic']} />
+
+~> **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: <required>)` - When the task should be started. Specified in 6 field
+  [cron format][cron] (no seconds) without `,` or `/` characters.
+
+- `end` `(string: <required>)` - 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

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"