[28/n] [wicketd] add the commission API, client, and OpenAPI document by sunshowers · Pull Request #10857 · oxidecomputer/omicron

sunshowers · 2026-07-17T18:39:32Z

This change implements v1 of the wicketd commission API, as described in RFD 710.

This is a pretty large change, so here's a short orientation and review guide.

What this PR is not

This PR does not change existing functionality. It is completely additive -- any behavior changes were made in prior commits in the stack.
This PR does not introduce a new security boundary. The way to access the commissioning API is exactly the same as the existing wicketd API.
This PR does not represent a customer commitment. The commissioning API is purely for rkdeploy. The extent to which we want to provide access to this API to customers will be determined in the future.

Review guide

The API surface matches what rkdeploy needs almost 1:1. I've paid attention to the type design and ensuring that any partial errors are properly reported to clients (something that was a bit lacking in the unstable API).

I would spend the most time looking at:

The API and type design -- I hope it is all generally self-explanatory.
The implementation in wicketd/src/commission/conversions.rs -- in particular, with extensive use of destructuring.
Wiring into existing code.
The tests.

Part of the review is going to be integrating with rkdeploy -- @JustinAzoff is taking care of this.

Note that while this API is server-side versioned, changing it does carry a substantial cost because such a change has to be coordinated with rkdeploy. So it's worth getting it right.

Depends on:

TODO:

test with rkdeploy on a racklette

Created using spr 1.3.6-beta.1

… the vendored copy (#10868) I moved these crates to crates.io a while ago, and they have a few important bugfixes and features that smoothen the process of integrating #10857. There aren't any wire protocol changes, so this can be landed without breaking rkdeploy.

…e id (#10885) Identified during #10857 review. Also map it to a 400 (client-side error) rather than a 503 (server-side error).

Created using spr 1.3.6-beta.1

…ch (#10888) Found while reviewing #10857. Currently, for transceivers: 1. There's a single `last_seen` across both switches. 2. The `last_seen` is snapshotted at update time, which means that it would only measure how long the update was in the mpsc channel for. Both of these seem incorrect, and in particular the second one would show up as wicket always reporting <1s. <img width="1584" height="332" alt="image" src="https://github.com/user-attachments/assets/c203a9f6-5760-4ec0-a146-e33e550a048a" /> Fix both these issues. To maintain the same wire shape, for point 1 we pick `max`. (The commissioning API will publish per-switch last seen values.) For point 2 there will be a behavior change visible in wicket, but that seems correct.

Created using spr 1.3.6-beta.1

andrewjstone

@sunshowers this looks great so far. I did a preliminary review. I mostly skipped conversions.rs and I still need to look at the integration tests and the http handler and progress files.

andrewjstone · 2026-07-23T20:31:05Z

+    /// Report the update progress of every service processor with update state
+    #[endpoint {
+        method = GET,
+        path = "/update-progress",


Why not /update-progress/sps ? Don't we update other things and show progress?

I should be clear, that I was trying to match this path with the comment.

andrewjstone · 2026-07-23T20:31:34Z

+        HttpError,
+    >;
+
+    /// Start updating one or more service processors


Same as above. I find it somewhat weird that /update only applies to sps.

It's actually doing a full MUPdate -- the nomenclature around SP is a bit of an implementation detail that's leaking here.

What should this be, though? "sleds" is too narrow because this is how you update switches and PSCs as well. "component" feels like a very overloaded term

Slots? Or are those just for sleds?

andrewjstone · 2026-07-23T22:13:56Z

+    /// Reported so that "a peer is on the bootstrap network but cannot be
+    /// matched to inventory" is distinguishable from "the sled has not been
+    /// discovered on the bootstrap network yet" (a `None` `BootstrapSled::ip`).
+    pub unmatched_peers: Vec<UnmatchedBootstrapPeer>,


I really like that you added this field. Thanks!

andrewjstone · 2026-07-23T22:18:58Z

+/// The current status of any rack-level operation being performed.
+#[derive(Clone, Debug, Serialize, Deserialize, JsonSchema, PartialEq, Eq)]
+#[serde(tag = "status", rename_all = "snake_case")]
+pub enum RackOperationStatus {


My PR adding the multirack join service actually changed this status. It's unfortunate, but there needed to be a way to show that multirack was precluding the operation of RSS or vice versa. I suppose for this API, we can do some type of conversion. I was just finding it hard to completely isolate the two, since we need to prevent them from running simultaneously.

Ah interesting. To be honest RSS should use the update engine! Then it can use the progress types which do not bake that kind of knowledge in.

Oh what I'm now wondering is if I can translate RSS information to the progress types.

andrewjstone · 2026-07-23T22:42:05Z

+        // TODO: once rkdeploy is on the published API, we can make
+        // `event_reports` be an IdOrdMap and make this much simpler.
+        let mut entries = IdOrdMap::new();
+        for (sp_type, slots) in event_reports {


Hey @sion42x, look Rain used a nested loop too!

Yeah, sorry for not building iddqd back in 2023 ;)

…ion-types (#10890) Found while reviewing #10857. rkdeploy doesn't need these today, but there's a decent likelihood it'll need them at some point because BGP auth keys are part of RSS.

Created using spr 1.3.6-beta.1

[spr] initial version

ca81f6f

Created using spr 1.3.6-beta.1

JustinAzoff reviewed Jul 17, 2026

View reviewed changes

Comment thread wicketd-commission-types/versions/src/initial/update.rs Outdated

sunshowers changed the title ~~[draft] [11/n] [wicketd] add the commission API, client, and OpenAPI document~~ [draft] [12/n] [wicketd] add the commission API, client, and OpenAPI document Jul 17, 2026

sunshowers changed the title ~~[draft] [12/n] [wicketd] add the commission API, client, and OpenAPI document~~ [draft] [13/n] [wicketd] add the commission API, client, and OpenAPI document Jul 17, 2026

sunshowers changed the title ~~[draft] [13/n] [wicketd] add the commission API, client, and OpenAPI document~~ [draft] [14/n] [wicketd] add the commission API, client, and OpenAPI document Jul 18, 2026

sunshowers mentioned this pull request Jul 20, 2026

[15/n] [update-engine] use oxide-update-engine from crates.io, delete the vendored copy #10868

Merged

1 task

a bunch of updates

ed5bbcf

Created using spr 1.3.6-beta.1

sunshowers changed the title ~~[draft] [14/n] [wicketd] add the commission API, client, and OpenAPI document~~ [draft] [15/n] [wicketd] add the commission API, client, and OpenAPI document Jul 20, 2026

sunshowers changed the title ~~[draft] [15/n] [wicketd] add the commission API, client, and OpenAPI document~~ [draft] [16/n] [wicketd] add the commission API, client, and OpenAPI document Jul 20, 2026

rebase

081b310

Created using spr 1.3.6-beta.1

sunshowers changed the title ~~[draft] [16/n] [wicketd] add the commission API, client, and OpenAPI document~~ [draft] [17/n] [wicketd] add the commission API, client, and OpenAPI document Jul 21, 2026

more updates

7fcfa59

Created using spr 1.3.6-beta.1

sunshowers changed the title ~~[draft] [17/n] [wicketd] add the commission API, client, and OpenAPI document~~ [draft] [18/n] [wicketd] add the commission API, client, and OpenAPI document Jul 21, 2026

sunshowers changed the title ~~[draft] [18/n] [wicketd] add the commission API, client, and OpenAPI document~~ [draft] [19/n] [wicketd] add the commission API, client, and OpenAPI document Jul 21, 2026

sunshowers mentioned this pull request Jul 21, 2026

[19/n] [wicketd] add the commission API, client, and OpenAPI document #10879

Closed

1 task

rebase

9b48da1

Created using spr 1.3.6-beta.1

sunshowers changed the title ~~[draft] [19/n] [wicketd] add the commission API, client, and OpenAPI document~~ [draft] [20/n] [wicketd] add the commission API, client, and OpenAPI document Jul 21, 2026

sunshowers mentioned this pull request Jul 21, 2026

[20/n] [wicketd] make GetInventoryError::InvalidSpIdentifier carry the id #10885

Merged

sunshowers changed the title ~~[draft] [20/n] [wicketd] add the commission API, client, and OpenAPI document~~ [draft] [21/n] [wicketd] add the commission API, client, and OpenAPI document Jul 21, 2026

sunshowers added 2 commits July 21, 2026 13:48

rebase, transceiver stuff

f24509c

Created using spr 1.3.6-beta.1

rustfmt

fe7c221

Created using spr 1.3.6-beta.1

This was referenced Jul 21, 2026

[21/n] [wicketd] compute transceiver staleness at read time, per switch #10888

Merged

[22/n] [wicket-common] move bgp auth key set types to wicketd-commission-types #10890

Merged

sunshowers changed the title ~~[draft] [21/n] [wicketd] add the commission API, client, and OpenAPI document~~ [draft] [xx/n] [wicketd] add the commission API, client, and OpenAPI document Jul 22, 2026

sunshowers added a commit that referenced this pull request Jul 23, 2026

[20/n] [wicketd] make GetInventoryError::InvalidSpIdentifier carry th…

3b28548

…e id (#10885) Identified during #10857 review. Also map it to a 400 (client-side error) rather than a 503 (server-side error).

lots more updates

a516281

Created using spr 1.3.6-beta.1

sunshowers added 2 commits July 23, 2026 11:39

more fixes

1aeab59

Created using spr 1.3.6-beta.1

more fixes

b23fe78

Created using spr 1.3.6-beta.1

sunshowers added 2 commits July 23, 2026 11:45

rustfmt

65e92d6

Created using spr 1.3.6-beta.1

a few more fixes

3c0c201

Created using spr 1.3.6-beta.1

sunshowers changed the title ~~[draft] [xx/n] [wicketd] add the commission API, client, and OpenAPI document~~ [28/n] [wicketd] add the commission API, client, and OpenAPI document Jul 23, 2026

sunshowers marked this pull request as ready for review July 23, 2026 20:06

sunshowers requested review from JustinAzoff and andrewjstone July 23, 2026 20:06

openapi

9c94c5f

Created using spr 1.3.6-beta.1

andrewjstone reviewed Jul 23, 2026

View reviewed changes

start addressing review feedback

78a19a5

Created using spr 1.3.6-beta.1

Uh oh!

Conversation

sunshowers commented Jul 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What this PR is not

Review guide

Uh oh!

Uh oh!

andrewjstone left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sunshowers Jul 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sunshowers Jul 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

sunshowers commented Jul 17, 2026 •

edited

Loading

sunshowers Jul 23, 2026 •

edited

Loading

sunshowers Jul 23, 2026 •

edited

Loading