Switch | NVIDIA Infra Controller

This document describes the Finite State Machine (FSM) for Switches in NICo: lifecycle from creation through configuration, validation, ready, optional reprovisioning, and deletion.

High-Level Overview

The main flow shows the primary states and transitions:

1 @startuml
2 skinparam state {
3   BackgroundColor White
4 }
5 
6 state "Created" as Created
7 state "Initializing\n(WaitForOsMachineInterface)" as Initializing
8 state "Configuring\n(RotateOsPassword)" as Configuring
9 state "Validating" as Validating
10 state "BomValidating" as BomValidating
11 state "Ready" as Ready
12 state "ReProvisioning\n(Start → WaitFirmware)" as ReProvisioning
13 state "Error" as Error
14 state "Deleting" as Deleting
15 
16 [*] --> Created : Switch created
17 
18 Created --> Initializing : controller processes switch
19 Initializing --> Configuring : all NVOS interfaces associated
20 Initializing --> Error : no NVOS MACs or MAC conflict
21 Configuring --> Validating : rotate password done
22 Validating --> BomValidating : validation complete
23 BomValidating --> Ready : BOM validation complete
24 
25 Ready --> Deleting : marked for deletion
26 Ready --> ReProvisioning : reprovision requested
27 
28 ReProvisioning --> Ready : firmware upgrade Completed
29 ReProvisioning --> Error : firmware upgrade Failed
30 
31 Error --> Deleting : marked for deletion or wait for manual intervention
32 
33 Deleting --> [*] : final delete
34 @enduml

States

State	Description
Created	Switch record exists in NICo; awaiting first controller tick.
Initializing	Controller waits for expected switch NVOS MAC associations. Sub-state: `WaitForOsMachineInterface`.
Configuring	Switch is being configured (rotate OS password). Sub-state: `RotateOsPassword`.
Validating	Switch is being validated. Sub-state: `ValidationComplete`.
BomValidating	BOM (Bill of Materials) validation. Sub-state: `BomValidationComplete`.
Ready	Switch is ready for use. From here it can be deleted, or reprovisioning can be requested.
ReProvisioning	Reprovisioning (e.g. firmware update) in progress. Sub-states: `Start`, `WaitFirmwareUpdateCompletion`. Completion is driven by `firmware_upgrade_status` (Completed → Ready, Failed → Error).
Error	Switch is in error (e.g. firmware upgrade failed or NVOS MAC conflict). Can transition to Deleting if marked for deletion; otherwise waits for manual intervention or ReProvisioning to take machine out of Error
Deleting	Switch is being removed; ends in final delete (terminal).

Transitions (by trigger)

From	To	Trigger / Condition
(create)	Created	Switch created
Created	Initializing (WaitForOsMachineInterface)	Controller processes switch
Initializing (WaitForOsMachineInterface)	Configuring (RotateOsPassword)	All NVOS interfaces associated for expected switch
Initializing (WaitForOsMachineInterface)	Error	Expected switch has empty `nvos_mac_addresses` or MAC owned by another switch
Configuring (RotateOsPassword)	Validating (ValidationComplete)	OS password rotated
Validating (ValidationComplete)	BomValidating (BomValidationComplete)	Validation complete
BomValidating (BomValidationComplete)	Ready	BOM validation complete
Ready	Deleting	`deleted` set (marked for deletion)
Ready	ReProvisioning (Start)	`switch_reprovisioning_requested` is set
ReProvisioning (Start)	ReProvisioning (WaitFirmwareUpdateCompletion)	Reprovision triggered
ReProvisioning (WaitFirmwareUpdateCompletion)	Ready	`firmware_upgrade_status == Completed`
ReProvisioning (WaitFirmwareUpdateCompletion)	Error	`firmware_upgrade_status == Failed { cause }`
Error	Deleting	`deleted` set (marked for deletion)
Deleting	(end)	Final delete committed

Implementation

State type: SwitchControllerState in crates/api-model/src/switch/mod.rs.
Handlers: crates/api/src/state_controller/switch/ — one module per top-level state (created, initializing, configuring, validating, bom_validating, ready, reprovisioning, error_state, deleting).
Orchestration: SwitchStateHandler in handler.rs delegates to the handler for the current controller_state.