README
¶
NICo Flow
Makefile targets
- gen-pb: Regenerate GRPC autogenerated code for the Flow server
- gen-nicoapi-pb: Regenerate GRPC autogenerated code for the NICo (Core) client
- gen-doc: Generate gRPC API documentation (
docs/grpc-api.mdfor GitLab,docs/grpc-api.htmlfor local) - container: Build a container tagged for local use (last release version + timestamp + git checksum).
How to run Flow on local machine (direct)
Prerequisites
# 1. Start PostgreSQL
./scripts/start-test-postgres.sh
# 2. Start Temporal (required for task operations)
brew install temporal # if not installed
temporal server start-dev --namespace flow --port 7233
Build and Run
# Build
go build -o flow
# Set environment (or use direnv with .envrc)
export DB_ADDR=localhost DB_PORT=30432 DB_USER=postgres DB_PASSWORD=postgres DB_DATABASE=flow_test
export TEMPORAL_HOST=localhost TEMPORAL_PORT=7233 TEMPORAL_NAMESPACE=flow
# Run migrations
./flow db migrate
# Start server (default port 50051)
# Use --dev-mode to enable gRPC reflection and debug logging (required for grpcui/grpcurl)
./flow serve --dev-mode
Note: NICo is not available locally; power/firmware operations will fail. Use dev/staging for those tests.
Test with grpcui
go install github.com/fullstorydev/grpcui/cmd/grpcui@latest
grpcui -plaintext localhost:50051
grpcuiandgrpcurlrely on gRPC server reflection, which is only enabled when the server is started with--dev-mode.
Task Architecture
Design Principles
-
1 Request → 1 TaskSpec: Each operation gRPC request (PowerOn, UpgradeFirmware, etc.) maps to one TaskSpec.
-
1 Rack → 1 Task: Task Manager splits TaskSpec by rack. This ensures fault isolation, parallel execution, and independent status tracking per rack.
-
Temporal Workflows: Each Task runs as a Temporal workflow for durable execution, automatic retries, and observability.
Data Flow
gRPC Request → Server (convert to TaskSpec)
→ Task Manager (resolve + split by rack → create Tasks)
→ Executor (start Temporal Workflow per Task)
→ Workflow (fan-out Activities by component)
→ Activity (call NICo / Core API)
gRPC APIs
The examples below require the server to be running with
--dev-mode(enables gRPC reflection).
List all available APIs:
grpcurl -plaintext localhost:50051 list v1.Flow
Describe a specific API:
grpcurl -plaintext localhost:50051 describe v1.Flow/CreateExpectedRack
Example: GetComponentInfoBySerial
grpcurl -plaintext -d '{
"serial_info": {"manufacturer": "Wiwynn", "serial_number": "B8111801000851500108Y0SA"},
"with_rack": true
}' localhost:50051 v1.Flow/GetComponentInfoBySerial
Response:
{
"component": {
"type": "COMPONENT_TYPE_COMPUTE",
"info": {
"id": {
"id": "57e70199-550d-4934-8fe8-3d951be1afcf"
},
"name": "gpu17-nvl5-gp2-cin1-jhb01",
"manufacturer": "WiWynn",
"model": "GB200 Compute Tray",
"serial_number": "B8111801000851500108Y0SA"
},
"firmware_version": "FW 1.2.00GA",
"position": {
"slot_id": 36,
"tray_idx": 16,
"host_id": 0
},
"bmcs": [
{
"type": "BMC_TYPE_HOST",
"mac_address": "d8:19:09:00:04:af"
},
{
"type": "BMC_TYPE_DPU",
"mac_address": "e0:9d:73:80:c0:59"
},
{
"type": "BMC_TYPE_DPU",
"mac_address": "e0:9d:73:88:de:1b"
}
]
},
"rack": {
"info": {
"id": {
"id": "0fe0e9bb-29e0-4940-b923-8e6f7dc017aa"
},
"name": "g10",
"manufacturer": "Wiwynn",
"serial_number": "B8111801000951700005Y0SA"
},
"location": {
"region": "MY",
"datacenter": "jhb01",
"room": "EW-F00-DH-02",
"position": "EW-F00-DH-02-G10"
},
"components": []
}
}
Power Shelf and NVSwitch Management
Power shelf and NVSwitch power/firmware operations go through Core (NICo) via
its nicoapi gRPC client. Core's per-tray-type backends (PSM, NSM, RMS, ...)
handle the actual hardware traffic.
Documentation
¶
There is no documentation for this package.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package cmd implements the flow CLI commands using Cobra.
|
Package cmd implements the flow CLI commands using Cobra. |
|
internal
|
|
|
alert
Package alert provides an abstraction for sending alerts/notifications from Flow workflows and activities.
|
Package alert provides an abstraction for sending alerts/notifications from Flow workflows and activities. |
|
certs
Package certs provides TLS configuration resolution using deployment-specific defaults: the CERTDIR environment variable and the Kubernetes SPIFFE secret path.
|
Package certs provides TLS configuration resolution using deployment-specific defaults: the CERTDIR environment variable and the Kubernetes SPIFFE secret path. |
|
common/grpclog
Package grpclog provides zerolog-based unary interceptors for the Flow gRPC server and clients.
|
Package grpclog provides zerolog-based unary interceptors for the Flow gRPC server and clients. |
|
inventory/manager
Package manager provides the business logic layer for inventory management.
|
Package manager provides the business logic layer for inventory management. |
|
inventory/store
Package store provides the storage layer for inventory management.
|
Package store provides the storage layer for inventory management. |
|
rule
Package rule contains the shared rule envelope used by Flow rule families.
|
Package rule contains the shared rule envelope used by Flow rule families. |
|
scheduler/taskschedule
Package taskschedule manages user-defined task schedules (task_schedule table).
|
Package taskschedule manages user-defined task schedules (task_schedule table). |
|
service
Package service implements the gRPC server for NICo Flow, the rack-level asset management system.
|
Package service implements the gRPC server for NICo Flow, the rack-level asset management system. |
|
task/componentmanager
Package componentmanager defines the manager contracts used to dispatch task operations.
|
Package componentmanager defines the manager contracts used to dispatch task operations. |
|
task/componentmanager/builtin
Package builtin wires the component manager extensions compiled into the Flow binary.
|
Package builtin wires the component manager extensions compiled into the Flow binary. |
|
task/componentmanager/compute/nico
Package nico is the compute manager implementation that drives compute trays through NICo Core's Component Manager dispatch (the same RPCs already used by nvswitch/nico and powershelf/nico):
|
Package nico is the compute manager implementation that drives compute trays through NICo Core's Component Manager dispatch (the same RPCs already used by nvswitch/nico and powershelf/nico): |
|
task/componentmanager/compute/nicolegacy
Package nicolegacy is the legacy compute manager implementation that dispatches power and firmware operations through NICo Core's machine-centric RPCs (AdminPowerControl, SetFirmwareUpdateTimeWindow, etc.) instead of going through Core's Component Manager handler.
|
Package nicolegacy is the legacy compute manager implementation that dispatches power and firmware operations through NICo Core's machine-centric RPCs (AdminPowerControl, SetFirmwareUpdateTimeWindow, etc.) instead of going through Core's Component Manager handler. |
|
task/componentmanager/config
Package config loads, normalizes, and validates component manager configuration, including component-manager selections, manager-specific configs, and provider/client configs.
|
Package config loads, normalizes, and validates component manager configuration, including component-manager selections, manager-specific configs, and provider/client configs. |
|
task/componentmanager/providerapi
Package providerapi contains provider abstractions that must be shared between the componentmanager package and provider implementation packages without creating an import cycle.
|
Package providerapi contains provider abstractions that must be shared between the componentmanager package and provider implementation packages without creating an import cycle. |
|
task/conflict
Package conflict provides data-driven task conflict detection for Flow.
|
Package conflict provides data-driven task conflict detection for Flow. |
|
task/report
Package report defines the JSON document persisted in task.report and the Tracker that mutates it as a rule-based workflow advances.
|
Package report defines the JSON document persisted in task.report and the Tracker that mutates it as a rule-based workflow advances. |
|
task/store
Package store provides the storage layer for task and operation rule management.
|
Package store provides the storage layer for task and operation rule management. |
|
pkg
|
|
|
certs
Package certs provides TLS configuration building from explicit certificate file paths.
|
Package certs provides TLS configuration building from explicit certificate file paths. |
|
client
Package client provides a gRPC client for interacting with the Flow service.
|
Package client provides a gRPC client for interacting with the Flow service. |
|
common/firmwarecomponents
Package firmwarecomponents converts the lowercase component-name strings accepted by the REST/Flow firmware-update API into the per-tray-type enum values used by each downstream component manager.
|
Package firmwarecomponents converts the lowercase component-name strings accepted by the REST/Flow firmware-update API into the per-tray-type enum values used by each downstream component manager. |
|
metadata
Package metadata contains build-time metadata for the Flow service.
|
Package metadata contains build-time metadata for the Flow service. |
|
types
Package types provides public domain types for the Flow client.
|
Package types provides public domain types for the Flow client. |
Click to show internal directories.
Click to hide internal directories.