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

Docs: Golden Versions updates (#24153)

Browse Source 
* Add language from CLI help to job revert for version|tag

* Add CLI job tag subcommand page

* Add API create delete tag

Examples use same names between CLI and API

* Update CLI revert, tag; API jobs

* Add job version content

* add tag name unique per job to CLI/API; address Phil's feedback

Add partial explaining why tag, add to CLI/API

* Add diff_version to API jobs list job versions

* Apply suggestions from code review

Co-authored-by: Jeff Boruszak <104028618+boruszak@users.noreply.github.com>

* remove tutorial links since not published yet.

---------

Co-authored-by: Jeff Boruszak <104028618+boruszak@users.noreply.github.com>
This commit is contained in:
Aimee Ukasick
2024-10-11 12:36:32 -05:00
committed by GitHub
parent 4de1665942
commit c839f38cab
6 changed files with 244 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files

114
website/content/api-docs/jobs.mdx
View File

@@ -632,7 +632,10 @@ The table below shows this endpoint's support for
### Parameters
- `diffs` `(bool: false)` - Specifies if the Diffs field should be populated,
containing the structured diff between the current and last job version.
containing the structured diff between the current and last job version. This
is specified as a query string parameter.
- `diff_version` `(int: <optional>)`: Specifies the version to to compare against the current version when you create the structured diff for a job with `diffs=true`. This is specified as a query string parameter.
- `:job_id` `(string: <required>)` - Specifies the ID of the job. This is
specified as part of the path.
@@ -1831,7 +1834,11 @@ The table below shows this endpoint's support for
- `JobID` `(string: <required>)` - Specifies the ID of the job. This is
specified as part of the path.
- `JobVersion` `(integer: 0)` - Specifies the job version to revert to.
- `JobVersion` `(integer: 0)` - Specifies the job version to revert to. Use either
this parameter or `TaggedVersion`, but do not use both.
- `TaggedVersion` `(string: "")` - Specifies the tag name of the job version you
want to revert to. Use either this parameter or `JobVersion`, but do not use both.
- `EnforcePriorVersion` `(integer: nil)` - Optional value specifying the current
job's version. This is checked and acts as a check-and-set value before
@@ -1849,6 +1856,8 @@ access. This is specified as a query string parameter.
### Sample Payload
This example specifies the version.
```json
{
"JobID": "my-job",
@@ -1856,6 +1865,15 @@ access. This is specified as a query string parameter.
}
```
This example specifies the tagged version.
```json
{
"JobID": "my-job",
"TaggedVersion": "golden-version"
}
```
### Sample Request
```shell-session
@@ -2682,3 +2700,95 @@ WebSocket Request: /v1/job/actions-demo/action?action=weather&allocID=8614ed07-4
# Toronto: ⛅️ -1°C
{"stdout":{"data":"VG9yb250bzog4puF77iPICAtMcKwQw0K"}}
```
## Create Job Version Tag
This endpoint creates a tag for a job version.
@include 'version/tag-reason.mdx'
| Method | Path | Produces |
| ------ | ----------------- | ------------------ |
| `POST` | `/v1/job/:job_id/versions/:tag_name/tag` | `application/json` |
### Parameters
- `:job_id` `(string: <required>)` - The ID of the job. Specify `job_id` as part
of the path.
- `:tag_name` `(string: <required>)` - The new tag name for the
version specified in the payload. Must be unique per job. Specify `tag_name` as part of the path.
- `Version`: `(int: <optional>)` - The job version number. If not
specified, Nomad tags the latest version. Specify `Version` in the payload.
- `Description`: `(string: <optional>)` - The tag description. Specify `Description` in the payload.
### Sample Payload
```json
{
"Version": 0,
"Description": "The version we can roll back to."
}
```
### Sample Request
This example creates a tag named `golden-version` for version zero of the
`hello-world` job.
```shell-session
$ curl -X POST \
localhost:4646/v1/job/hello-world/versions/golden-version/tag \
-H "Content-Type: application/json" -d \
'{"Version": 0, "Description": "The version we can roll back to."}'
```
### Sample Response
```json
{
"Name":"golden-version",
"Description":"The version we can roll back to.",
"TaggedTime":1728325495829793000,
"Index":361,
"LastContact":0,
"KnownLeader":false,
"NextToken":""}
```
## Delete Job Version Tag
This endpoint deletes a job version tag.
| Method | Path | Produces |
| ------ | ----------------- | ------------------ |
| `DELETE` | `/v1/job/:job_id/versions/:tag_name/tag` | `application/json` |
### Parameters
- `:job_id` `(string: <required>)` - The ID of the job. Specify `job_id` as part of the path.
- `:tag_name` `(string: <required>)` - The tag name. Specify `tag_name` as part of the path.
### Sample Request
This example deletes the `golden-version` tag from the `hello-world` job.
```shell-session
$ curl -X DELETE localhost:4646/v1/job/hello-world/versions/golden-version/tag -H "Content-Type: application/json"
```
### Sample Response
```json
{
"EvalID":"",
"EvalCreateIndex":0,
"JobModifyIndex":0,
"VolumeEvalID":"",
"VolumeEvalIndex":0,
"Index":0,
"LastContact":0,
"KnownLeader":false,
"NextToken":""
}
```

11
website/content/docs/commands/job/revert.mdx
View File

@@ -27,12 +27,15 @@ authentication.
## Usage
```plaintext
nomad job revert [options] <job> <version>
```shell-session
nomad job revert [options] <job> <version|tag>
```
The `job revert` command requires two inputs, the job ID and the version of that
job to revert to.
The `job revert` command requires two inputs: the job ID, and the version number
or tag of the job to revert to. When you specify a version number, Nomad
reverts the job to the exact version number. Alternately, when you specify a
custom tag name as a string, Nomad reverts to the version tagged with that
name.
When ACLs are enabled, this command requires a token with the `submit-job`
capability for the job's namespace. The `list-jobs` capability is required to

89
website/content/docs/commands/job/tag.mdx Normal file
View File

@@ -0,0 +1,89 @@
---
layout: docs
page_title: 'Commands: job tag'
description: |
Use the job tag commands to manage versions. The job tag apply command saves a job version tag, and the job tag unset command removes a job version tag.
---
# Command: job tag
@include 'version/tag-reason.mdx'
Use the `job tag` command to manage tags for job versions. `job tag` has the
following subcommands:
- [`job tag apply`](#apply): Save a job version tag.
- [`job tag unset`](#unset): Remove a tag from a job version.
## Usage
```shell
nomad job tag <subcommand> [options] [args]
```
## General options
Use these optional general options with the subcommands.
@include 'general_options.mdx'
## Apply
Use `job tag apply` to create or modify a version tag.
### Apply usage
```shell-session
nomad job tag apply [options] <job_id>
```
### Apply options
- `name`: Specifies the name of the tag. Must be unique per job.
- `description`: If set, specifies a description for the tag.
- `version`: If set, specifies the version of the job to tag. If not provided, Nomad tags the latest version of the job.
### Apply examples
This example tags the latest version of the job `hello-world`.
```shell-session
$ nomad job tag apply -name "golden-version" \
-description "The version we can roll back to." \
hello-world
```
This example tags version zero of the job `hello-world`.
```shell-session
$ nomad job tag apply -version 0 \
-name "golden-version" \
hello-world
```
## Unset
Use `nomad job tag unset` to delete a tag from a version. This command requires a job name and a tag name.
### Unset usage
```shell-session
nomad job tag unset [options] <job_id> -name <tag>
```
### Unset options
- `name`: Specifies the name of the tag to remove from the job version.
### Examples
This example removes the `golden-version` tag from the `hello-world` job.
```shell-session
$ nomad job tag unset hello-world -name "golden-version"
```
[diff]: /nomad/docs/commands/job/history/
[revert]: /nomad/docs/commands/job/revert/

28
website/content/docs/concepts/job.mdx
View File

@@ -96,6 +96,34 @@ zero. Nomad's garbage collector has not yet removed or purged the job.
The `Stopped` status indicates that a user has manually stopped the job.
Nomad's garbage collector has not yet removed or purged the job.
## Job versions
Nomad creates a new version for your job each time you run your job. A job can
have an unlimited number of versions, and version history is stored in state.
Over time, Nomad garbage collects dead versions that do not have a version tag.
### Tag a version
When you want to save or pin a specific version, you need to create a version
tag with a unique name and optional description. Nomad does not garbage collect
tagged versions even when the tagged version is dead. This lets you revert to
a previous version regardless of how old the tagged version is.
### Compare versions
You can compare the current job version to all previous versions or to a
specific version. Additionally, you can compare two specific versions.
Run commands like `nomad job history` to review differences between past versions
of jobs and their immediate predecessors. Additionally, you can run `nomad job
plan` to review the hypothetical difference of an update against the current job
version.
### Revert to a previous version
You can revert the current running job to a previous version. Nomad stops the
running job and deploys the chosen version.
## Related resources
Refer to the following Nomad documentation pages for more information about

4
website/content/partials/version/tag-reason.mdx Normal file
View File

@@ -0,0 +1,4 @@
Applying a tag to a version prevents Nomad from garbage collecting that version.
You can compare versions by tag name as well as version number.
Tag names must be unique per job.

4
website/data/docs-nav-data.json
View File

@@ -663,6 +663,10 @@
"title": "stop",
"path": "commands/job/stop"
},
{
"title": "tag",
"path": "commands/job/tag"
},
{
"title": "validate",
"path": "commands/job/validate"