kemko/nomad
1
0
Fork 0
mirror of https://github.com/kemko/nomad.git synced 2026-01-01 16:05:42 +03:00
Code Issues Packages Projects Releases Wiki Activity

docs: explain schedule state values (#24160)

Browse Source 
* docs: explain schedule state values

GET /v1/client/allocation/:alloc_id/pause?task=:task_name is a tiny but
critical API for observability of tasks with a schedule. This PR
explains each of the values which might be returned.

* correct docstring

* add missing state and expand PUT docs

---------

Co-authored-by: Aimee Ukasick <aimee.ukasick@hashicorp.com>
This commit is contained in:
Michael Schurter
2024-10-17 11:42:12 -07:00
committed by GitHub
parent 55fe05d353
commit cbbe6bb389
2 changed files with 41 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files

5
api/allocations.go
View File

@@ -547,7 +547,10 @@ type AllocPauseRequest struct {
}
type AllocGetPauseResponse struct {
// ScheduleState will be one of "pause", "run", "scheduled".
// ScheduleState will be one of "" (run), "force_run", "scheduled_pause",
// "force_pause", or "schedule_resume".
//
// See nomad/structs/task_sched.go for details.
ScheduleState string
}

42
website/content/api-docs/allocations.mdx
View File

@@ -983,6 +983,19 @@ The table below shows this endpoint's support for
must be the full UUID, not the short 8-character one. This is specified as
part of the path.
- `Task` `(string: <required>)` - Specifies the name of the task whose schedule
should be overridden.
- `ScheduleState` `(string: <required>)` - Specifies the pause state to force
the task into. One of:
- `"pause"` - Forces the task to pause.
- `"run"` - Forces the task to run.
- `"scheduled"` - Removes any overrides and forces the task to adhere to
its schedule.
### Sample Request
```shell-session
@@ -1018,12 +1031,12 @@ The table below shows this endpoint's support for
### 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.
- `: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.
- `task` `(string: <required>)` - Specifies the name of the task from which to
retrieve the time-based task execution state.
### Sample Request
@@ -1039,5 +1052,24 @@ $ nomad operator api /v1/client/allocation/23f520cc-629a-46ff-395f-0661e7aa939e/
}
```
#### Field Reference
- `ScheduleState` `(string)`: The task's current paused state. It can can have
one of the following values:
- `""` - The task is running. The only state returned for tasks with no
schedule.
- `force_run` - The task's schedule has been overridden to run.
- `force_pause` - The task's schedule has been overridden to pause.
- `scheduled_pause` - The task is paused according to its schedule.
- `schedule_resume` - A schedule override is being removed. Subsequent calls
should return running (`""`) or paused (`scheduled_pause`) states. This
state is rarely possible to observe since it transitions immediately to
another state.
[`shutdown_delay`]: /nomad/docs/job-specification/group#shutdown_delay
[schedule]: /nomad/docs/job-specification/schedule