Skip to navigation
API ReferenceTray

Firmware update a Tray

View as Markdown

Update firmware on a Tray identified by its component ID or component MAC address.

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

Authentication

AuthorizationBearer
export JWT_BEARER_TOKEN="<jwt-bearer-token>"

# Example org name: "acme-inc
export ORG_NAME=<org-name>

# Use the JWT bearer token in your API request auth header:
curl -v -X GET -H "Content-Type: application/json" -H "Authorization: Bearer $JWT_BEARER_TOKEN" https://nico-rest-api.nico.svc.cluster.local/v2/org/$ORG_NAME/nico/user/current

Path parameters

orgstringRequired
Name of the Org
idstringRequired
Component ID or component MAC address

Request

This endpoint expects an object.
siteIdstringRequiredformat: "uuid"
ID of the Site
versionstring or nullOptional

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.

targetslist of enumsOptional

Optional subset of firmware targets to update within the targeted 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 the 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.

authenticationDataobjectOptional

Optional, write-only authentication data for firmware downloads. Not supported for DPU-only updates or by the legacy NICo compute firmware controller.

ruleIdstringOptionalformat: "uuid"
Optional Operation Rule UUID. When set, pins this firmware update to the named rule and overrides Flow's default rule resolution.
overrideVersionCheckbooleanOptionalDefaults to false

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.

overrideReadinessCheckbooleanOptionalDefaults to false

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.

Response

OK
taskIdslist of stringsOptional
List of task IDs created for the firmware update operation

Errors

400
Bad Request Error
403
Forbidden Error
412
Precondition Failed Error
504
Gateway Timeout Error