From eb3eb8351f8cc001029ee581b1e611cad2eee1af Mon Sep 17 00:00:00 2001 From: Aimee Ukasick Date: Wed, 9 Oct 2024 11:17:22 -0500 Subject: [PATCH] add tag name unique per job to CLI/API; address Phil's feedback Add partial explaining why tag, add to CLI/API --- website/content/api-docs/jobs.mdx | 4 +++- website/content/docs/commands/job/revert.mdx | 8 ++++---- website/content/docs/commands/job/tag.mdx | 4 +++- website/content/partials/version/tag-reason.mdx | 4 ++++ 4 files changed, 14 insertions(+), 6 deletions(-) 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 36dfd557b3d6..33a066f4f0b6 100644 --- a/website/content/api-docs/jobs.mdx +++ b/website/content/api-docs/jobs.mdx @@ -2702,6 +2702,8 @@ WebSocket Request: /v1/job/actions-demo/action?action=weather&allocID=8614ed07-4 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` | @@ -2711,7 +2713,7 @@ This endpoint creates a tag for a job version. - `: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. Specify `tag_name` as part of the path. + 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. diff --git a/website/content/docs/commands/job/revert.mdx b/website/content/docs/commands/job/revert.mdx index d855593bac7c..451a51c51a20 100644 --- a/website/content/docs/commands/job/revert.mdx +++ b/website/content/docs/commands/job/revert.mdx @@ -31,10 +31,10 @@ authentication. nomad job revert [options] ``` -The `job revert` command requires two inputs, the job ID and the version or tag -of that job to revert to. When you specify a version number, Nomad reverts the -job to the exact version number. Alternately, when you specify a version tag, -Nomad reverts to the version with that tag. +The `job revert` command requires two inputs, the job ID and the version number +or tag of that job to revert to. When you specify a version number, Nomad +reverts the job to the exact version number. Alternately, when you specify a +version tag, Nomad reverts to the version with that tag. 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 index 54580deed5eb..345172d92189 100644 --- a/website/content/docs/commands/job/tag.mdx +++ b/website/content/docs/commands/job/tag.mdx @@ -8,6 +8,8 @@ description: | # 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: @@ -38,7 +40,7 @@ nomad job tag apply [options] ### Apply options -- `name`: Specifies the name of the tag. +- `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. diff --git a/website/content/partials/version/tag-reason.mdx b/website/content/partials/version/tag-reason.mdx new file mode 100644 index 000000000000..aad3aba7cda4 --- /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.