[api] Add endpoint that tells you the current API version

[david-crespo]

I am mulling over docs versioning, and while the plan there hasn't been fully ironed out (RFD 458 needs to be finished), an uncontroversial part of it is that an end user should be able to ask the system for its current software version. There are several versions of this problem discussed in #8292 (comment) — the one I am aiming for here is (as @davepacheco put it here): "the release whose Nexus is running right now".

As discussed in RFD 588 Nexus handoff during upgrade, we are only ever serving API traffic on one version of nexus at a time. During an update, we upgrade some sleds to the new version while old Nexus instances keep serving API traffic, and then we cut over to the new instances all at once. All this is to say: I think the releng system version hard-coded into Nexus is a good answer to "the release whose Nexus is running right now". Using a hard-coded value has the advantage that it requires no DB call and therefore the endpoint can be served without any authentication.

As I was working on this, I got a little wrapped around the axle thinking about whether/how to also include the git hash like we do for the TUF repo version strings (see code below). While I do think that would be useful to some end users, who might enjoy being able to go to GitHub and see the exact code that's running, this is not related to my immediate problem and we can solve it separately in a followup. In the meantime this endpoint is quite useful as-is.

omicron/dev-tools/releng/src/main.rs

Lines 245 to 264 in b2b1e39

	let commit = Command::new(&args.git_bin)
	.args(["rev-parse", "HEAD"])
	.ensure_stdout(&logger)
	.await?
	.trim()
	.to_owned();
	let mut version = BASE_VERSION.clone();
	// Differentiate between CI and local builds. We use `0.word` as the
	// prerelease field because it comes before `alpha`.
	version.pre =
	if std::env::var_os("CI").is_some() { "0.ci" } else { "0.local" }
	.parse()?;
	// Set the build metadata to the current commit hash.
	let mut build = String::with_capacity(14);
	build.push_str("git");
	build.extend(commit.chars().take(11));
	version.build = build.parse()?;
	let version_str = version.to_string();
	info!(logger, "version: {}", version_str);

Debatable choices

• How to get the release version
  • I just moved the constant from releng to omicron-common but maybe that feels bad given the purpose of the constant?
• /v1/system/version is kind of a weird path for an endpoint that is accessible without auth — all the rest of the /v1/system/ endpoints are meant for operators.
  • Could do /v1/version or /v1/system-version ?
  • Could even roll it into /v1/ping, though I would never think to look there, so I don't like this idea

[david-crespo]

Probably want to word this more precisely.

[karencfv]

I think the term "Oxide software" could mean many things. For the purpose of this endpoint do you want the API version specifically?

During an update several components will be on different versions during a period of time. This endpoint may confuse our customers during this period thinking all components are running on said version, when in reality they might not be. Because of this, I would not call it "system version".

[david-crespo]

I mostly mean API version. The most literal thing is "API and control plane version" — my understanding is that these are the same thing because when we do handoff from old Nexus to new Nexus, we are switching to the new API and to the new control plane at the same time.

I don't want users to have to see or think about what we normally call the API version — 2026032500.0.0. We use it internally because we have many API versions between releases, but for the end user, API versions correspond 1-1 with release numbers like v19. I want to key the versioned docs off the release number and turn 2026032500.0.0 into more of an implementation detail. This might mean we should add the release version to the OpenAPI schema metadata.

So I agree that "system version" is not a good name for this endpoint at all. "API version" is better. "Control plane version" is pretty direct, but I am worried about the user being able to infer everything they should from that. It's probably a lot easier to infer from "API version" that it doesn't just mean the API shape but also the machinery powering the API. So "API version" is the best option to me so far.

[jgallagher]

+1 on "API version". I don't love "control plane version", because during an update, "the control plane" is on a mix of versions. But because of the way Nexus handoff is structured, there's always exactly one "API version".

[karencfv]

I agree, "API version" is the most correct term

[karencfv]

Thanks for getting the ball rolling! I think we've wanted this endpoint since before I joined the company? 😄

I left a comment, but I think we definitely want @davepacheco to take a look before merging.

[karencfv]

I think the term "Oxide software" could mean many things. For the purpose of this endpoint do you want the API version specifically?

During an update several components will be on different versions during a period of time. This endpoint may confuse our customers during this period thinking all components are running on said version, when in reality they might not be. Because of this, I would not call it "system version".

[david-crespo]

Trying /v1/api-version (/v1/version feels too vague) and some improved docs.

[karencfv]

I like api-version! That said, the release version wouldn't work if you're using it as a header right? It has to be something like curl -H "api-version: 2026041500.0.0" not curl -H "api-version: 19.0.0" right? Do you think this could confuse people?

I realise this was discussed already here

the one I am aiming for here is (as @davepacheco put it #8292 (comment)): "the release whose Nexus is running right now".

So please ignore me if what I'm saying just sounds crazy

[david-crespo]

No, that's a great point and it's true that I am fighting an uphill battle because we've already called that "API version". In order to be able to make the release version the "API version" from a user point of view, like I want to, we'd have to go through everywhere we currently call the date-based version "API version" and call it something else. I'm not too worried about existing users because I doubt many of them have actually seen this header — the SDKs handle it internally. But we would definitely have to change the name to eliminate confusion.

Fortunately, in the OpenAPI schema it's just called version, so we could call it schema version or something like that.

omicron/openapi/nexus/nexus-2026032500.0.0-cf1221.json

Lines 1 to 11 in 8676f30

	{
	"openapi": "3.0.3",
	"info": {
	"title": "Oxide Region API",
	"description": "API for interacting with the Oxide control plane",
	"contact": {
	"url": "https://oxide.computer",
	"email": "api@oxide.computer"
	},
	"version": "2026032500.0.0"
	},

This is where the header name is defined. Looks like it's used in all our internal APIs too.

omicron/common/src/api/mod.rs

Lines 10 to 12 in 8676f30

	/// API versioning header name used across Omicron APIs.
	pub const VERSION_HEADER: http::HeaderName =
	http::HeaderName::from_static("api-version");

Ultimately I'm fine with calling it something else if we want to, but either way it's good to get clear on these relationships and dependencies. Right now I lean toward making the date-based schema version more of an implementation detail, like I said, and making the release version the user-facing API version. Unsurprisingly, this is starting to feel like a short RFD is in order.

[karencfv]

I'm not too worried about existing users because I doubt many of them have actually seen this header — the SDKs handle it internally.

I think I'd be more worried about customers who are writing their own clients without using our SDKs. I think some of them are?

Fortunately, in the OpenAPI schema it's just called version, so we could call it schema version or something like that.

Ultimately I'm fine with calling it something else if we want to, but either way it's good to get clear on these relationships and dependencies.

This makes sense to me, but unsure of how much work this would be.

Unsurprisingly, this is starting to feel like a short RFD is in order.

I hate to say it, but yes 😄