Initial Update Designs

[benjaminleonard]

Based on the ongoing API work and Andrew’s progress API, I’ve put together the following:
• Release list page
• Update status page
• Single release detail modal

As usual, this includes some elements that aren’t yet in the API but seem necessary for MVP (and a bit beyond). For example, when designing this there was no endpoint for listing releases.

A couple of open questions:
• For current releases, do users need to manage or prune old releases from the list?
• Would the release list be a standard paginated endpoint?

For the upload release and set target dialogs, we’ll need inline documentation – please ignore the placeholder text for now. As always, we’ll want concise docs in the dialog itself, plus links to more comprehensive information on the docs site.

On the upgrade status page, I’ve added a “status” cell. The idea is that we could either infer the status from the current and target version (which would require returning metadata from the current target TUF repo) or, preferably, have the API return the status directly. Rather than just using a version number/unknown/installing dataset/error, what if we split the state into its own attribute? This would let us show when a component has completed its upgrade.

Any thoughts on exposing more detailed monitoring (similar to what’s shown during ‎⁠mupdate⁠) as part of the troubleshooting UX? I haven’t explored handling stalled or failed updates yet—happy to take your lead here. It might make sense to direct users to the CLI for more granular monitoring if needed.

Finally, I’m using “Releases” as a placeholder term for now, since exposing something like “TUF repo” might be too implementation-specific. Open to discussion on naming!

--

See designs / comment here: https://app.workflow.design/w/doc/ac8c2576-7902-493f-a5f4-6a234e5a193b

[benjaminleonard]

CC: @davepacheco @sunshowers @andrewjstone @iliana @smklein @jgallagher @david-crespo @karencfv (apologies if I've missed someone)

Will try and find some time to discuss on the calendar, perhaps at an update huddle, will give some warning before hand. I do also need to check back in with the latest update API work as some of this may be already out of date.

[david-crespo]

• For current releases, do users need to manage or prune old releases from the list?

Assuming we will not support downgrade (I think this is the case) I think we may want a visual treatment of releases older than current (possibly operationalized as older than any component in the system) that marks them as not actually available for upgrade. We could disappear them but it feels less surprising to keep them there, but grayed out.

• Would the release list be a standard paginated endpoint?

I don't see why not.

[benjaminleonard]

Assuming we will not support downgrade (I think this is the case) I think we may want a visual treatment of releases older than current (possibly operationalized as older than any component in the system) that marks them as not actually available for upgrade. We could disappear them but it feels less surprising to keep them there, but grayed out.

For the update crew: perhaps the case for newer releases that are not viably updated from the current release also, if that's also a limitation?

[jgallagher]

For the update crew: perhaps the case for newer releases that are not viably updated from the current release also, if that's also a limitation?

It is. More context in oxidecomputer/omicron#8056 and RFD 557, but I believe the current state is:

• Releases have a version that's parseable as semver (although we're not following semver; more in the RFD on the meaning).
• If the system's current target release has major version N, releases with major version N+2 or higher are not viable. (I.e., you cannot skip major releases.) This will be a limitation indefinitely.
• If an upgrade is currently in progress, the target release cannot be changed at all until the upgrade completes. This may be relaxed after we ship the first upgrade implementation; ideally you'd be able to set the target release to a higher minor version (e.g., if you're currently upgrading from 15.0.0 to 15.1.0, you ought to be able to change the target to 15.2.0 even before the upgrade finishes, but will not be able to for now).

[karencfv]

Just saw the designs, they look really cool! There's definitely something about finally seeing the work come together in a UI. I left a couple of comments on the artifact visualisation, but just generally really happy to see the UI!

[benjaminleonard]

• Releases have a version that's parseable as semver (although we're not following semver; more in the RFD on the meaning).
• If the system's current target release has major version N, releases with major version N+2 or higher are not viable. (I.e., you cannot skip major releases.) This will be a limitation indefinitely.
• If an upgrade is currently in progress, the target release cannot be changed at all until the upgrade completes. This may be relaxed after we ship the first upgrade implementation; ideally you'd be able to set the target release to a higher minor version (e.g., if you're currently upgrading from 15.0.0 to 15.1.0, you ought to be able to change the target to 15.2.0 even before the upgrade finishes, but will not be able to for now).

All useful info thanks, we'll probably want to prevent these actions on the client since it's usually a nicer experience than waiting for the server error response.

Just saw the designs, they look really cool! There's definitely something about finally seeing the work come together in a UI. I left a couple of comments on the artifact visualisation, but just generally really happy to see the UI!

Much appreciated!

[benjaminleonard]

If the viable upgrade logic is particularly complicated we might consider an endpoint (or a dry run API param) that returns if it's possible and why. Though if it's as simple as you have we could probably recreate it in the console.

[david-crespo]

I was thinking we could just have a boolean field on each release in the list saying whether you can set it as the target at that moment. Maybe not boolean if there’s metadata, like a reason. Wouldn’t need to be a separate endpoint necessarily.

[benjaminleonard]

That's why you're the engineer 🧠