feat: Add tray-level firmware sub-target selection

Lets callers restrict a firmware update to a subset of sub-parts within
each targeted tray (e.g. just BMC + NVOS for switch trays, just PSU for
powershelf trays) instead of always installing the whole bundle.

REST surface
------------
- OpenAPI: new optional `targets` array on `FirmwareUpdateRequest` and
  `BatchTrayFirmwareUpdateRequest`. Lowercase names; empty/omitted keeps
  the historical "update everything in the bundle" behavior; unknown
  names are rejected. Requires `version` to be set when non-empty.
  Field is named `targets` (not `components`) to avoid colliding with
  carbide's tray-level "Component" resource vocabulary.
- API model: `APIUpdateFirmwareRequest.Targets`,
  `APIBatchTrayFirmwareUpdateRequest.Targets`, `validateFirmwareTargets`.
- Handlers: `tray.go` (single + batch) plumbs `apiRequest.Targets`
  through `common.ExecuteFirmwareUpdateWorkflow`. `rack.go` continues
  to pass nil (no rack-level sub-target selection - rack requests are
  fanned out to individual tray operations downstream).
- SDK regenerated.

Flow gRPC + Go internals
------------------------
- `flow/proto/v1/flow.proto`: new `repeated string sub_targets = 8;` on
  `UpgradeFirmwareRequest`. Named `sub_targets` (not `components`)
  because `OperationTargetSpec.components` already exists on the same
  request and means "tray INSTANCES to hit"; keeping both as
  `components` would have been ambiguous.
- Regenerated `flow/pkg/proto/v1/flow.pb.go` and
  `workflow-schema/flow/protobuf/v1/flow.pb.go`.
- `operations.FirmwareControlTaskInfo` gains `SubTargets []string`
  (JSON tag `sub_targets`). Populated from `req.GetSubTargets()` in
  `service/server_impl.go` and `converter/protobuf/converter.go`.
- All 5 component-manager FirmwareControl implementations consume
  `info.SubTargets`:
    - nvlswitch/nsm  -> NSM QueueUpdates
    - nvlswitch/nico -> UpdateSwitchFirmwareTarget.Components
    - powershelf/psm -> UpdatePowershelfFirmwareRequest.Components
    - powershelf/nico -> UpdatePowerShelfFirmwareTarget.Components
                        (defaults to PMC when empty, preserving prior
                         behavior)
    - compute/nico  -> currently logs a warning and applies the full
                        bundle; the SetFirmwareUpdateTimeWindow +
                        SetMachineAutoUpdate path has no per-sub-target
                        selection. Will be honored once compute moves
                        to UpdateComponentFirmware.

Centralized name -> enum mapping
--------------------------------
- New package `flow/pkg/common/firmwarecomponents` owns the
  string -> tray-type-specific component-manager-enum mapping for all
  three tray types (NSM NVSwitch, PSM PowerShelf, and the three NICo
  *Component enums). Mappings are explicit hand-written maps rather
  than auto-derived from proto, so adding a new enum value in Core
  requires a deliberate decision about its REST-facing name.
- Completeness-guard unit tests (TestNICo*MapIsComplete) fail if Core
  adds a non-UNKNOWN enum value that the mapping forgot to cover.
- Package name keeps "Component" because it is the semantic destination
  of the parse - the enums in Core are named NvSwitchComponent /
  PowerShelfComponent / ComputeTrayComponent.

Compatibility
-------------
- Proto field number 8 is new (added in this commit), so there are no
  in-flight Temporal workflows or existing gRPC consumers depending on
  any prior name; the JSON-tag/field-name choices are risk-free.
- gRPC wire format only depends on field numbers; the name `sub_targets`
  changes nothing on the wire.
- Empty/omitted `targets` is the legacy behavior, so existing callers
  are unaffected.

Example
-------
PATCH /v2/tray/{id}/firmware
  { "version": "24.11.0", "targets": ["bmc", "nvos"] }

POST /v2/tray/firmware/batch
  { "siteId": "...", "filter": {"type": "switch"},
    "version": "24.11.0", "targets": ["bmc", "nvos"] }

Author: kunzhao-nv

api/pkg/api/handler/rack.go

@@ -1150,7 +1150,7 @@ func (furh UpdateRackFirmwareHandler) Handle(c echo.Context) error {
 	}
 
 	flowResp, err := common.ExecuteFirmwareUpdateWorkflow(ctx, c, logger, stc, targetSpec, apiRequest.Version,
-		fmt.Sprintf("rack-firmware-update-%s", rackStrID), "Rack")
+		nil, fmt.Sprintf("rack-firmware-update-%s", rackStrID), "Rack")
 	if err != nil {
 		return err
 	}
@@ -1268,7 +1268,7 @@ func (furbh BatchUpdateRackFirmwareHandler) Handle(c echo.Context) error {
 	targetSpec := request.Filter.ToTargetSpec()
 
 	flowResp, err := common.ExecuteFirmwareUpdateWorkflow(ctx, c, logger, stc, targetSpec, request.Version,
-		fmt.Sprintf("rack-firmware-batch-update-%s", common.RequestHash(request.Filter)), "Rack")
+		nil, fmt.Sprintf("rack-firmware-batch-update-%s", common.RequestHash(request.Filter)), "Rack")
 	if err != nil {
 		return err
 	}

api/pkg/api/handler/tray.go

@@ -1144,7 +1144,7 @@ func (futh UpdateTrayFirmwareHandler) Handle(c echo.Context) error {
 	}
 
 	flowResp, err := common.ExecuteFirmwareUpdateWorkflow(ctx, c, logger, stc, targetSpec, apiRequest.Version,
-		fmt.Sprintf("tray-firmware-update-%s", trayStrID), "Tray")
+		apiRequest.Targets, fmt.Sprintf("tray-firmware-update-%s", trayStrID), "Tray")
 	if err != nil {
 		return err
 	}
@@ -1259,7 +1259,7 @@ func (futbh BatchUpdateTrayFirmwareHandler) Handle(c echo.Context) error {
 	targetSpec := request.Filter.ToTargetSpec()
 
 	flowResp, err := common.ExecuteFirmwareUpdateWorkflow(ctx, c, logger, stc, targetSpec, request.Version,
-		fmt.Sprintf("tray-firmware-batch-update-%s", common.RequestHash(request.Filter)), "Tray")
+		request.Targets, fmt.Sprintf("tray-firmware-batch-update-%s", common.RequestHash(request.Filter)), "Tray")
 	if err != nil {
 		return err
 	}

api/pkg/api/handler/util/common/common.go

@@ -1762,19 +1762,28 @@ func ExecuteBringUpRackWorkflow(
 
 // ExecuteFirmwareUpdateWorkflow builds an UpgradeFirmwareRequest, executes the UpgradeFirmware
 // workflow via Temporal, and returns the raw SubmitTaskResponse.
+//
+// targets, when non-empty, restricts the upgrade to the listed firmware
+// sub-parts within each targeted tray (e.g. ["bmc", "nvos"] for switch
+// trays). An empty/nil slice keeps the historical "update everything in
+// the bundle" behavior. Names are passed through verbatim to Flow as
+// `sub_targets`, which resolves them against the tray-type-specific
+// component-manager enums (see flow/pkg/common/firmwarecomponents).
 func ExecuteFirmwareUpdateWorkflow(
 	ctx context.Context,
 	c echo.Context,
 	logger zerolog.Logger,
 	stc tclient.Client,
 	targetSpec *flowv1.OperationTargetSpec,
 	version *string,
+	targets []string,
 	workflowID string,
 	entityName string,
 ) (*flowv1.SubmitTaskResponse, error) {
 	flowRequest := &flowv1.UpgradeFirmwareRequest{
 		TargetSpec:    targetSpec,
 		TargetVersion: version,
+		SubTargets:    targets,
 		Description:   fmt.Sprintf("API firmware update %s", entityName),
 	}
 

api/pkg/api/model/firmware.go

@@ -29,14 +29,29 @@ import (
 type APIUpdateFirmwareRequest struct {
 	SiteID  string  `json:"siteId"`
 	Version *string `json:"version,omitempty"`
+	// Targets, when non-empty, restricts the update to a subset of
+	// firmware sub-parts within the targeted tray (e.g. ["bmc", "nvos"]
+	// for switch trays). Names are lowercase. The authoritative supported
+	// set per tray type is derived from the Flow service's NICo proto
+	// bindings (mirroring Core's per-tray-type enums in
+	// carbide-core/crates/rpc/proto/forge.proto); see
+	// flow/pkg/common/firmwarecomponents for the resolution logic and
+	// helpers like SupportedNICoNVSwitchNames.
+	// Empty/nil means "update everything in the bundle". Requires Version.
+	//
+	// REST surface intentionally calls these "targets" to avoid confusion
+	// with carbide's tray-level "Component" vocabulary; the downstream
+	// Flow proto field is still named `components` and represents the
+	// same enum subset.
+	Targets []string `json:"targets,omitempty"`
 }
 
 // Validate validates the firmware update request
 func (r *APIUpdateFirmwareRequest) Validate() error {
 	if r.SiteID == "" {
 		return fmt.Errorf("siteId is required")
 	}
-	return nil
+	return validateFirmwareTargets(r.Targets, r.Version)
 }
 
 // ========== Firmware Update Response ==========
@@ -89,12 +104,38 @@ type APIBatchTrayFirmwareUpdateRequest struct {
 	SiteID  string      `json:"siteId"`
 	Filter  *TrayFilter `json:"filter,omitempty"`
 	Version *string     `json:"version,omitempty"`
+	// Targets, when non-empty, restricts the update to a subset of
+	// firmware sub-parts within each matched tray. Same semantics as the
+	// single-tray variant. Requires Version.
+	Targets []string `json:"targets,omitempty"`
 }
 
 // Validate checks required fields and filter constraints.
 func (r *APIBatchTrayFirmwareUpdateRequest) Validate() error {
 	if r.SiteID == "" {
 		return fmt.Errorf("siteId is required")
 	}
-	return r.Filter.Validate()
+	if err := r.Filter.Validate(); err != nil {
+		return err
+	}
+	return validateFirmwareTargets(r.Targets, r.Version)
+}
+
+// validateFirmwareTargets enforces the cross-field constraint that a
+// firmware-target subset selection is only meaningful when a target version
+// is also supplied. Per-tray-type name validation is delegated to Flow,
+// where the mapping from string to component-manager enum lives.
+func validateFirmwareTargets(targets []string, version *string) error {
+	if len(targets) == 0 {
+		return nil
+	}
+	for _, t := range targets {
+		if t == "" {
+			return fmt.Errorf("targets must not contain empty strings")
+		}
+	}
+	if version == nil || *version == "" {
+		return fmt.Errorf("targets requires version to be set")
+	}
+	return nil
 }

api/pkg/api/model/firmware_test.go

@@ -45,6 +45,88 @@ func TestAPIUpdateFirmwareRequest_Validate(t *testing.T) {
 			request: APIUpdateFirmwareRequest{Version: strPtr("24.11.0")},
 			wantErr: true,
 		},
+		{
+			name: "valid - targets with version",
+			request: APIUpdateFirmwareRequest{
+				SiteID:  "site-1",
+				Version: strPtr("24.11.0"),
+				Targets: []string{"bmc", "nvos"},
+			},
+			wantErr: false,
+		},
+		{
+			name: "invalid - targets without version",
+			request: APIUpdateFirmwareRequest{
+				SiteID:  "site-1",
+				Targets: []string{"bmc"},
+			},
+			wantErr: true,
+		},
+		{
+			name: "invalid - targets with empty version string",
+			request: APIUpdateFirmwareRequest{
+				SiteID:  "site-1",
+				Version: strPtr(""),
+				Targets: []string{"bmc"},
+			},
+			wantErr: true,
+		},
+		{
+			name: "invalid - targets contains empty string",
+			request: APIUpdateFirmwareRequest{
+				SiteID:  "site-1",
+				Version: strPtr("24.11.0"),
+				Targets: []string{"bmc", ""},
+			},
+			wantErr: true,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			err := tt.request.Validate()
+			if tt.wantErr {
+				assert.Error(t, err)
+			} else {
+				assert.NoError(t, err)
+			}
+		})
+	}
+}
+
+func TestAPIBatchTrayFirmwareUpdateRequest_Validate(t *testing.T) {
+	tests := []struct {
+		name    string
+		request APIBatchTrayFirmwareUpdateRequest
+		wantErr bool
+	}{
+		{
+			name:    "valid - siteId only",
+			request: APIBatchTrayFirmwareUpdateRequest{SiteID: "site-1"},
+			wantErr: false,
+		},
+		{
+			name: "valid - targets with version",
+			request: APIBatchTrayFirmwareUpdateRequest{
+				SiteID:  "site-1",
+				Version: strPtr("24.11.0"),
+				Targets: []string{"bmc"},
+			},
+			wantErr: false,
+		},
+		{
+			name: "invalid - targets without version",
+			request: APIBatchTrayFirmwareUpdateRequest{
+				SiteID:  "site-1",
+				Targets: []string{"bmc"},
+			},
+			wantErr: true,
+		},
+		{
+			name:    "invalid - missing siteId",
+			request: APIBatchTrayFirmwareUpdateRequest{},
+			wantErr: true,
+		},
 	}
 
 	for _, tt := range tests {

flow/internal/converter/protobuf/converter.go

@@ -1239,6 +1239,7 @@ func ScheduledOperationFrom(
 		info := &operations.FirmwareControlTaskInfo{
 			Operation:     operations.FirmwareOperationUpgrade,
 			TargetVersion: r.UpgradeFirmware.GetTargetVersion(),
+			SubTargets:    r.UpgradeFirmware.GetSubTargets(),
 		}
 
 		if r.UpgradeFirmware.GetStartTime() != nil {

flow/internal/service/server_impl.go

@@ -1241,6 +1241,7 @@ func (rs *FlowServerImpl) UpgradeFirmware(
 		Operation:     operations.FirmwareOperationUpgrade,
 		TargetVersion: req.GetTargetVersion(),
 		RuleID:        protobuf.UUIDStringFrom(req.GetRuleId()),
+		SubTargets:    req.GetSubTargets(),
 	}
 
 	// Parse optional time parameters for scheduled upgrade

flow/internal/task/componentmanager/compute/nico/nico.go

@@ -315,6 +315,7 @@ func (m *Manager) FirmwareControl(ctx context.Context, target common.Target, inf
 	log.Debug().
 		Str("components", target.String()).
 		Str("target_version", info.TargetVersion).
+		Strs("sub_targets", info.SubTargets).
 		Msg("Scheduling firmware update for compute via NICo")
 
 	if m.nicoClient == nil {
@@ -325,6 +326,19 @@ func (m *Manager) FirmwareControl(ctx context.Context, target common.Target, inf
 		return fmt.Errorf("target is invalid: %w", err)
 	}
 
+	if len(info.SubTargets) > 0 {
+		// SetFirmwareUpdateTimeWindow + SetMachineAutoUpdate (the path used
+		// here for compute trays) do not expose per-sub-target selection;
+		// auto-update will install whatever is in the desired bundle. Log
+		// the requested subset so the limitation is visible until we can
+		// route this through UpdateComponentFirmware (planned alongside the
+		// version → FW Object identifier migration).
+		log.Warn().
+			Str("components", target.String()).
+			Strs("sub_targets", info.SubTargets).
+			Msg("compute firmware sub-target selection is not yet honored; whole bundle will be applied")
+	}
+
 	desiredEntries, err := m.nicoClient.GetDesiredFirmwareVersions(ctx)
 	if err != nil {
 		return fmt.Errorf("failed to query desired firmware versions: %w", err)

flow/internal/task/componentmanager/compute/nico/nico_test.go

@@ -102,6 +102,39 @@ func mustMarshal(t *testing.T, v any) json.RawMessage {
 	return data
 }
 
+// TestFirmwareControl_SubTargetsAccepted verifies that the compute/nico
+// FirmwareControl path tolerates info.SubTargets without erroring. This
+// path goes through SetMachineAutoUpdate + SetFirmwareUpdateTimeWindow,
+// which has no per-sub-target selection in NICo, so the manager only logs
+// a warning and proceeds; we exercise that branch here. The actual
+// per-sub-target dispatch will be added when compute moves to NICo's
+// UpdateComponentFirmware (see comment in nico.go).
+func TestFirmwareControl_SubTargetsAccepted(t *testing.T) {
+	tests := map[string]struct {
+		subTargets []string
+	}{
+		"nil sub_targets (legacy path)":     {subTargets: nil},
+		"empty sub_targets (legacy path)":   {subTargets: []string{}},
+		"non-empty sub_targets (warn path)": {subTargets: []string{"bmc", "bios"}},
+	}
+
+	for name, tc := range tests {
+		t.Run(name, func(t *testing.T) {
+			m := New(nicoapi.NewMockClient(), 0)
+			target := common.Target{
+				Type:         devicetypes.ComponentTypeCompute,
+				ComponentIDs: []string{"machine-1"},
+			}
+
+			err := m.FirmwareControl(context.Background(), target, operations.FirmwareControlTaskInfo{
+				Operation:  operations.FirmwareOperationUpgrade,
+				SubTargets: tc.subTargets,
+			})
+			require.NoError(t, err)
+		})
+	}
+}
+
 // --- Tests for firmware version helper functions ---
 
 func desiredEntry(versions map[string]string) *pb.DesiredFirmwareVersionEntry {

flow/internal/task/componentmanager/nvlswitch/nico/nico.go

@@ -34,6 +34,7 @@ import (
 	"github.com/NVIDIA/infra-controller-rest/flow/internal/task/executor/temporalworkflow/common"
 	"github.com/NVIDIA/infra-controller-rest/flow/internal/task/operations"
 	"github.com/NVIDIA/infra-controller-rest/flow/pkg/common/devicetypes"
+	"github.com/NVIDIA/infra-controller-rest/flow/pkg/common/firmwarecomponents"
 )
 
 const (
@@ -242,12 +243,18 @@ func (m *Manager) FirmwareControl(ctx context.Context, target common.Target, inf
 	log.Debug().
 		Str("components", target.String()).
 		Str("target_version", info.TargetVersion).
+		Strs("sub_targets", info.SubTargets).
 		Msg("Starting firmware update for NVLSwitch via NICo")
 
 	if err := target.Validate(); err != nil {
 		return fmt.Errorf("target is invalid: %w", err)
 	}
 
+	subComponents, err := firmwarecomponents.ParseNICoNVSwitch(info.SubTargets)
+	if err != nil {
+		return err
+	}
+
 	if info.TargetVersion == "" {
 		upToDate, err := m.checkFirmwareUpToDate(ctx, target)
 		if err != nil {
@@ -263,7 +270,8 @@ func (m *Manager) FirmwareControl(ctx context.Context, target common.Target, inf
 	req := &pb.UpdateComponentFirmwareRequest{
 		Target: &pb.UpdateComponentFirmwareRequest_Switches{
 			Switches: &pb.UpdateSwitchFirmwareTarget{
-				SwitchIds: switchIDsProto(target.ComponentIDs),
+				SwitchIds:  switchIDsProto(target.ComponentIDs),
+				Components: subComponents,
 			},
 		},
 		TargetVersion: info.TargetVersion,