System Update API

[david-crespo]

RFD 348 is still in progress, but I find it helpful to do this in parallel.

---

This is a big PR, but fortunately it is very straightforward: endpoints plus the service functions, models, and tables you'd expect to see backing those endpoints. It's a good time to add "updateable" to your computer's dictionary.

Included here

• Endpoints
  • System version + status (updating or not + reason)
  • Get tree of updateable components (each w/ version + status)
  • List system updates
  • Get system update
  • Get tree of component updates for top-level system update
  • Start update (noop, returns placeholder SystemUpdateDeployment)
  • Stop update (noop)
  • Change existing refresh endpoint to match new /v1/system/update/... convention
• Nexus functions for all that except start and stop
  • Basic tests that create the thing and then retrieve it
• Tables
  • System updates
  • Component updates
  • Join table between system updates and component updates
  • Updateable components
  • Update deployments
• Weird stuff
  • version_sort column on system_update and component_update that lets us hack in sorting by version
  • Enforce maximum major/minor/patch version number because version_sort relies on zero-padding
  • Make system update semver version the PK for the system updates table and fetch by version in endpoints
    • Ideally we'd be able to fetch by ID also, but there would been a lot of boilerplate to make it work like NameOrId without comparable value due to the latter's reuse in many places. Version is unique and immutable, so this should be good enough to start.

Conspicuously missing, to be done in followups

• nexus functions for updating updateable component rows (possibly also system updates and component updates — not sure if they're supposed to be modified)
• Actually do an update

Do a find for TODO: for an embarrassing number of additional bullets.

Open questions

• What is a good length limit for version strings in the DB? There's no official limit, but the docs suggest a number less than or equal to 255: https://semver.org/#does-semver-have-a-size-limit-on-the-version-string
  • Where/how do we enforce the length limit besides the DB?
• How to represent system status, especially steady reason

[david-crespo]

@smklein if we want to use semver::Version here, which sounds sensible, we need to wrap it and impl JsonSchema on that. Correct?

[smklein]

I believe so - looks like someone already started work on this here: GREsau/schemars#195

[david-crespo]

Good timing. I looked but apparently in the wrong place.

[smklein]

🐮🔔

[david-crespo]

IF (big IF) we don't have anything else hanging off of /system/update other than what's here, seems like we could get away without doing my goofy /update/updates idea if we put system version and component version tree under /system/version. So:

system_update_list                       /v1/system/updates
system_update_view                       /v1/system/updates/{update_id}
system_update_components_list            /v1/system/updates/{update_id}/components
system_update_start                      /v1/system/updates/{update_id}/start
system_update_stop                       /v1/system/updates/{update_id}/stop

system_version                           /v1/system/version
system_component_version_list            /v1/system/version/components

This has the disadvantage of putting version under a different top-level key, which makes it less obvious how closely tied it is to the /system/updates endpoints.

[zephraph]

I much prefer this. The /system/update/updates pattern is fairly different than the rest of our API where typically resources are plural.

[david-crespo]

The problem is this: what do we do when want to add another endpoint that should go under /updates? With /system/update/updates we just add /system/update/other_thing. With /system/updates we can't do /system/updates/other_thing.

[david-crespo]

I forgot, we already have one (which is at /system/updates because it preexisted my current work):

omicron/nexus/src/external_api/http_entrypoints.rs

Lines 5032 to 5040 in 75bd905

	/// Refresh update data
	#[endpoint {
	method = POST,
	path = "/system/updates/refresh",
	tags = ["system"],
	}]
	async fn updates_refresh(
	rqctx: Arc<RequestContext<Arc<ServerContext>>>,
	) -> Result<HttpResponseUpdatedNoContent, HttpError> {

[zephraph]

I don't guess dropshot would let you register /system/updates/refresh before /system/updates/{update_id} to have it automatically be handled, would it? 😅. There's actually no overlap in this case because refresh isn't a valid UUID. If that worked, it'd be sort of ideal.

Beyond that, I'm not really sure. I obviously don't think we should stall on this API decision and I'm fine with moving forward with what's here. Hopefully we'll figure out a better way to do this at some point and update accordingly.

[david-crespo]

No, Dropshot would have to be modified: oxidecomputer/dropshot#199

And more and more I agree with the comments on that issue arguing it’s a footgun.

[david-crespo]

@smklein so far it seems like we'll need the following tables. Maybe we can pair tomorrow on throwing something basic in.

• system updates
• component updates
• join table associating system updates and component updates
• component version and status
• update in progress

System version + status response would be put together by looking at the update in progress table for the status and pulling the low and high versions from the list of components.