Version tag HTTP API doesn't tag latest version (docs+api inaccurate)

[maxramqvist]

trafficstars

Nomad version

Nomad v1.9.1 BuildDate 2024-10-21T09:00:50Z Revision d9ec23f0c1035401e9df6c64d6ffb8bffc555a5e

With ACLs enabled and using Nomad namespaces.

Operating system and Environment details

Ubuntu 22.04, kernel 6.9.3 on x86_64

Issue

According to the docs:

Optionally, you can also supply a tag description and a version number. If you do not supply a version number, Nomad tags the latest version.

If I don't supply the version number the oldest version gets tagged instead of the latest version.

Reproduction steps

1. Nomad doesn't tag the latest version. The version must be specified in the POST body for the tagging to work.

curl -H "x-nomad-token: $NOMAD_TOKEN" http://localhost:4646/v1/job/test-service/versions/vLatest/tag\?namespace\=mynamespace -X POST -d '{}'  
{"Name":"vLatest","Description":"","TaggedTime":1729537471780368140,"Index":232,"LastContact":0,"KnownLeader":false,"NextToken":""}

Adding Version to the body tags the version intended. curl -H "x-nomad-token: $NOMAD_TOKEN" http://localhost:4646/v1/job/test-service/versions/vActualLatest/tag\?namespace\=mynamespace -X POST -d '{"Version": 3}' Results in: {"Name":"vActualLatest","Description":"","TaggedTime":1729537656801230518,"Index":270,"LastContact":0,"KnownLeader":false,"NextToken":""} Results in the desired version getting tagged:

2. An empty body isn't accepted, but a body with an empty JSON object {} is accepted. No biggie really, just not obvious that its required.

curl -X POST -H "x-nomad-token: $NOMAD_TOKEN" http://localhost:4646/v1/job/test-service/versions/v3/tag\?namespace\=mynamespace results in the response: Request body is empty. Specifying an empty JSON as request body works: curl -H "x-nomad-token: $NOMAD_TOKEN" http://localhost:4646/v1/job/test-service/versions/v3/tag\?namespace\=mynamespace -X POST -d '{}', response: ``{"Name":"v3","Description":"","TaggedTime":1729537150671061477,"Index":186,"LastContact":0,"KnownLeader":false,"NextToken":""}

Expected Result

I could create a tag on the latest version of a job without specifying the exact version of the job, as the docs say.

Actual Result

The first version, number 0, gets tagged if I don't specify the exact version I want to tag.

[maxramqvist]

Another issue is that diffs doesn't work in the UI. As you can see in the screenshots, the web ui shows "No changes" - but I've made changes to a few different things in the job. Meta, Docker configuration (labels, image) and some Consul tags.

Using the "Diff against"-button results in that button changing and the url changing but nothing else. I checked the browsers dev tools aswell, no requests get sent when using that button.

Can confirm it both happens on when running Nomad in dev mode and proper production mode with a server cluster and separate clients.

Perhaps I should post a separate issue?

[philrenaud]

Yes, I'd appreciate a second issue for that one — should definitely be showing you diffs between job versions. For a minimum reproduction, could you try modifying a task group's count value to see if that shows up in the diff?

[maxramqvist]

Yep, I'll post a proper issue for that tomorrow. Can confirm no diffs are shown when just changing count.

Thanks in the meantime. Nomad really is a great product!

[philrenaud]

Thanks for saying so!

And regarding the original issue:

• we'll change the documentation here; during development, we had a "if version is not supplied, assume latest" convenience rule at HTTP API level, but ended up moving it to the CLI layer. Why? Internally, we reasoned that CLI version tagging was prone to be a lot more manual and one-shot than doing it via the API, where perf matters more and we might assume that the user has access to the latest version of the job in question (which comes back with a standard job request).
• If the version is not included in the POST body, we actually try for version 0. If you have more versions than agent.server.job_tracked_versions (defaults to 6), you actually get a job "jobname" version 0 not found error, which is not what we intended. I think if it's not provided, we'll throw an error here.`

So that's two upcoming changes: one to clarify in the docs that latest-version is only presumed for CLI requests, and another to throw an error when a version is not supplied to the HTTP API.

[philrenaud]

A point of clarification on my earlier statement:

If the version is not included in the POST body, we actually try for version 0. If you have more versions than agent.server.job_tracked_versions (defaults to 6), you actually get a job "jobname" version 0 not found error, which is not what we intended. I think if it's not provided, we'll throw an error here.`

I've dug into this a bit and had a couple discussions with colleagues on the subject. The decision I've come to is that the CLI should support omitting a version number (and it should default to the latest) as a convenience method, but the HTTP API should have some more rigid expectations, namely that the version should be provided, and that it should be provided as an integer.

Letting it be passed to the API as a pointer would let us have a nullish version number that we could error on, but comes at the cost of a simpler interface. As such, the API will continue to expect a version number to be provided in POST body and in its absence, will treat it as if it's version 0. Not the friendliest DX, but worth it for the benefit of more streamlined behaviour.

We will modify the docs to reflect that version number omission handling is for the CLI only.

[github-actions[bot]]

I'm going to lock this issue because it has been closed for 120 days ⏳. This helps our maintainers find and focus on the active issues. If you have found a problem that seems similar to this, please open a new issue and complete the issue template so we can capture all the details necessary to investigate further.