Tray

Firmware update Trays

Changed on

Update firmware on Trays with optional filters. If no filter is specified, targets all trays in the Site.

Filter constraints:

  • rackId and rackName are mutually exclusive
  • rackId/rackName cannot be combined with ids (rack-level vs component-level targeting)

Org must have an Infrastructure Provider entity. User must have authorization role with PROVIDER_ADMIN suffix.

patch/v2/org/{org}/nico/tray/firmware

Request

  • Base URL
    https://nico-rest-api.nico.svc.cluster.local
  • URL
    https://nico-rest-api.nico.svc.cluster.local/v2/org/{org}/nico/tray/firmware
  • Auth
    HTTP bearer

Request body

siteIdstring uuid required

ID of the Site

versionstring nullable

Target firmware input serialized as a string. Its format is a contract between the caller and the component backend selected for the target. The REST API and Flow orchestration otherwise preserve this value. Flow only unwraps the optional per-tray mapping described below before passing the value to the selected component manager.

For compatibility, when Flow's compute component manager is explicitly configured as nicolegacy (the default is nico), use a compute tray endpoint without version or targets for on-demand host updates. Core selects the configured host firmware bundle.

For RMS-backed rack-scale firmware updates, use the complete SOT firmware-object JSON document, not a release version such as 24.11.0. A SOT document is an object with ProductName and Milestones at the top level. Each milestone contains Name, State, and BoardSKUs; each board SKU contains Name, Type, and Components. Component groups contain Software and Firmware entries describing Component, Version, Type, FileNames, artifact Locations, and optional SubComponents. Obtain the complete document from the SOT release process; the abbreviated examples are not executable input. Supply a complete document covering all component types selected by the operation rule.

The string can contain either one shared firmware input for all selected trays or a JSON mapping from tray type (compute, nvswitch, powershelf) to firmware input. Each mapping value must satisfy its selected backend's contract. Flow forwards object values as raw JSON and unquotes string values. These exact lowercase top-level keys are reserved for per-tray mappings; a shared JSON object must not contain any of them. A missing tray type in the mapping skips that component type. A non-empty, non-layered value is forwarded unchanged. For rack-scale RMS components, an omitted, null, empty, or whitespace-only value uses the owning rack profile's configured firmware object. Resolution or fetch failures are reported by the asynchronous task.

targetsstring[]

Optional subset of firmware targets to update within each matched tray. Names are lowercase and select sub-parts of the tray (BMC, BIOS, etc.). The accepted set per tray type comes from the Flow service's NICo proto bindings (which mirror Core's per-tray-type enums in NICo-core/crates/rpc/proto/forge.proto), so the supported values track Core as new sub-parts are added:

  • switch trays (NvSwitchComponent): currently bmc, cpld, bios, nvos
  • powershelf trays (PowerShelfComponent): currently pmc, psu
  • compute trays (ComputeTrayComponent): currently bmc, bios

The default nico compute component manager forwards BMC and BIOS selections through UpdateComponentFirmware. The opt-in nicolegacy manager schedules the whole configured host firmware bundle; it does not honor BMC or BIOS sub-target selection. Omitted or empty means "update everything in the bundle" (the historical default) for compute-tray-internal targets. Unknown names are rejected. The special target dpu, valid only on compute trays, requests DPU reprovisioning on each matched host. Unlike the other targets, dpu is NOT covered by the "omitted/empty means everything" default — it must be listed explicitly. version is ignored on the dpu branch; the target firmware version comes from site configuration.

ruleIdstring uuid

Optional Operation Rule UUID. When set, pins every task spawned by this batch to the named rule and overrides Flow's default rule resolution.

overrideVersionCheckboolean

When true, request that the selected component backend override firmware version-based checks when deciding whether to apply the update. This permits same-version reapplication and downgrade when supported. It does not bypass readiness checks or state-controller routing.

overrideReadinessCheckboolean

When true, proceed even if one or more target components (or hosts on the owning rack for rack-scoped components) are reported as not ready by their persisted status. Intended for operator-supervised maintenance.

Example request

{
  "siteId": "550e8400-e29b-41d4-a716-446655440000",
  "filter": {
    "type": "NVSwitch"
  },
  "version": "{\"ProductName\":\"ExampleRackSystem\",\"Milestones\":[{\"Name\":\"example-release\",\"State\":\"Onboarded\",\"BoardSKUs\":[{\"Name\":\"Example-Switch-Tray\",\"Type\":\"Switch Tray\",\"Components\":{\"Software\":[],\"Firmware\":[{\"Component\":\"BMC+CPLD\",\"Version\":\"1.2.3\",\"Type\":\"Prod\",\"FileNames\":[\"switch-firmware.fwpkg\"],\"Locations\":[{\"Location\":\"/firmware/example/switch-firmware.fwpkg\",\"LocationType\":\"FILE\",\"PackageName\":\"\",\"Type\":\"Firmware\",\"FileName\":\"switch-firmware.fwpkg\"}]}]}}]}]}",
  "targets": [
    "bmc"
  ]
}

Response

OK

taskIdsstring[]

List of task IDs created for the firmware update operation

Example response

{
  "taskIds": [
    "550e8400-e29b-41d4-a716-446655440000"
  ]
}

Changes

  • 293dc126ab73Revision changes
    • info

      removed the nico enum value from the response property for the response status

    • info

      removed the nico enum value from the response property for the response status

    • info

      removed the nico enum value from the response property for the response status

  • 78f3b35615a5Revision changes
    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status