From c839f38cab03e1aabe7c4fc468a62725c165f673 Mon Sep 17 00:00:00 2001 From: Aimee Ukasick Date: Fri, 11 Oct 2024 12:36:32 -0500 Subject: [PATCH] Docs: Golden Versions updates (#24153) * 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> --- website/content/api-docs/jobs.mdx | 114 +++++++++++++++++- website/content/docs/commands/job/revert.mdx | 11 +- website/content/docs/commands/job/tag.mdx | 89 ++++++++++++++ website/content/docs/concepts/job.mdx | 28 +++++ .../content/partials/version/tag-reason.mdx | 4 + website/data/docs-nav-data.json | 4 + 6 files changed, 244 insertions(+), 6 deletions(-) create mode 100644 website/content/docs/commands/job/tag.mdx create mode 100644 website/content/partials/version/tag-reason.mdx diff --git a/website/content/api-docs/jobs.mdx b/website/content/api-docs/jobs.mdx index e77622991..e276c9cc4 100644 --- a/website/content/api-docs/jobs.mdx +++ b/website/content/api-docs/jobs.mdx @@ -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: )`: 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: )` - 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: )` - 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: )` - The ID of the job. Specify `job_id` as part + of the path. +- `:tag_name` `(string: )` - 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: )` - The job version number. If not + specified, Nomad tags the latest version. Specify `Version` in the payload. +- `Description`: `(string: )` - 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: )` - The ID of the job. Specify `job_id` as part of the path. +- `:tag_name` `(string: )` - 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":"" +} +``` + diff --git a/website/content/docs/commands/job/revert.mdx b/website/content/docs/commands/job/revert.mdx index f0bd4efa6..0c95d693d 100644 --- a/website/content/docs/commands/job/revert.mdx +++ b/website/content/docs/commands/job/revert.mdx @@ -27,12 +27,15 @@ authentication. ## Usage -```plaintext -nomad job revert [options] +```shell-session +nomad job revert [options] ``` -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 diff --git a/website/content/docs/commands/job/tag.mdx b/website/content/docs/commands/job/tag.mdx new file mode 100644 index 000000000..345172d92 --- /dev/null +++ b/website/content/docs/commands/job/tag.mdx @@ -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 [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] +``` + +### 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] -name +``` + +### 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/ + diff --git a/website/content/docs/concepts/job.mdx b/website/content/docs/concepts/job.mdx index 8968c0f4c..fa4aa2af9 100644 --- a/website/content/docs/concepts/job.mdx +++ b/website/content/docs/concepts/job.mdx @@ -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 diff --git a/website/content/partials/version/tag-reason.mdx b/website/content/partials/version/tag-reason.mdx new file mode 100644 index 000000000..aad3aba7c --- /dev/null +++ b/website/content/partials/version/tag-reason.mdx @@ -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. diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index b5be40ec4..0b463a8c6 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -663,6 +663,10 @@ "title": "stop", "path": "commands/job/stop" }, + { + "title": "tag", + "path": "commands/job/tag" + }, { "title": "validate", "path": "commands/job/validate"