Cnuas Programmability, CLI and REST API¶

This document is the complete reference for programmatic control of the Cnuas Virtual AI HPC Infrastructure. Cnuas ships a single control plane with two front ends, the cnuas command-line tool and the cnuas-api REST service. Both front ends call the same service layer, so every CLI capability is also a REST endpoint and the two never drift apart.

Relationship. The cnuas CLI and the cnuas-api REST service are thin clients over one shared service object. That service object owns a set of adapters, one per component (HiSwitch, HiLink, HiGPU, HiNIC, VM lifecycle), and translates each call into the native management protocol of that component.

1. Architecture¶

flowchart TB subgraph front["Front ends"] CLI["cnuas CLI (Typer + Rich)"] REST["cnuas-api (FastAPI, OpenAPI at /docs)"] end SVC["CnuasService (shared facade)"] subgraph adapters["Adapters"] A1["Switch adapter"] A2["HiLink adapter"] A3["GPU adapter"] A4["NIC adapter"] A5["VM adapter"] A6["System adapter"] end subgraph backends["Backends"] B1["hicain-vswitchd UNIX socket, JSON + newline"] B2["higpu-link-switchd UNIX socket, JSON"] B3["/dev/higpuN + sysfs HIGPU_IOC_INFO ioctl"] B4["/sys/class/infiniband RDMA sysfs"] B5["hicain-tools vm state files + subprocess"] B6["git tags component versions"] end CLI --> SVC REST --> SVC SVC --> A1 --> B1 SVC --> A2 --> B2 SVC --> A3 --> B3 SVC --> A4 --> B4 SVC --> A5 --> B5 SVC --> A6 --> B6

The design keeps a single source of truth. When a backend is not present on the current host, for example on a developer workstation with no daemons running, read commands degrade gracefully and state-changing commands return a clear 503 unavailable error instead of failing silently.

2. Installation¶

Cnuas is a Python package under cnuas/ in the vdc repository.

python3 -m venv --system-site-packages .venv
. .venv/bin/activate
pip install -e 'cnuas[test]'

This installs two entry points, cnuas (the CLI) and the importable cnuas.api.app:app ASGI application used by cnuas-api.

3. Configuration¶

Every setting is environment-driven, so the same binary runs unchanged on a workstation, a CI agent, or inside a lab VM.

Variable	Default	Meaning
`HICAIN_RUN_DIR`	`/var/run/hicain`	Switch run directory holding `mgmt.sock`
`HILINK_RUN_DIR`	`/var/run/hilink`	HiLink run directory
`CNUAS_SWITCH_SOCKET`	`$HICAIN_RUN_DIR/mgmt.sock`	Switch management socket
`CNUAS_HILINK_SOCKET`	`$HILINK_RUN_DIR/mgmt.sock`	HiLink management socket
`CNUAS_GPU_SYSFS`	`/sys/class/higpu`	HiGPU sysfs class root
`CNUAS_GPU_DEV_DIR`	`/dev`	HiGPU character device directory
`CNUAS_NIC_SYSFS`	`/sys/class/infiniband`	RDMA sysfs class root
`HICAIN_DATA_DIR`	XDG data home	VM state root (`<dir>/vms/<name>/state.json`)
`CNUAS_VM_TOOL`	`hicain-tools vm`	Command used for VM lifecycle actions
`CNUAS_API_HOST`	`0.0.0.0`	REST bind address
`CNUAS_API_PORT`	`8080`	REST bind port
`CNUAS_TIMEOUT`	`5.0`	Socket and subprocess timeout in seconds

4. Command-line interface¶

The CLI is organised into command groups, one per domain. Pass the global --json flag (before the subcommand) for machine-readable output suitable for scripting.

cnuas --json system health

4.1 system¶

Command	Purpose
`cnuas system health`	Probe every component and report reachability
`cnuas system inventory`	Snapshot of every reachable component
`cnuas system versions`	Per-component versions from git tags

$ cnuas system versions
┏━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Component ┃ Version                       ┃
┡━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ vdc       │ v0.1.0                        │
│ hinic     │ v0.1.0-23-gd97b1c9            │
│ hiswitch  │ v0.1.0-4-g1700b86             │
│ higpu     │ v0.2.0-3-g4104982             │
│ hilink    │ v0.1.0                        │
│ kernel    │ hicain-v6.19.0                │
│ qemu      │ hicain-qemu-v0.1.0-2-g6b326b4 │
└───────────┴───────────────────────────────┘

4.2 switch (HiSwitch RoCE/IB fabric)¶

Command	Purpose
`cnuas switch ports [PORT]`	List ports, or one port when PORT is given
`cnuas switch set-mode PORT MODE`	Set port mode (`STRICT_ETH`, `STRICT_IB`, `AUTO`)
`cnuas switch set-link PORT --up/--down`	Set a port link state
`cnuas switch set-pfc PORT --on/--off -p PRIO`	Configure Priority Flow Control
`cnuas switch set-ecn PORT --on/--off`	Configure ECN marking
`cnuas switch set-ets PORT SHARES...`	Configure ETS bandwidth shares
`cnuas switch fdb show\\|add\\|del`	Ethernet forwarding database
`cnuas switch lft show\\|add\\|del`	InfiniBand linear forwarding table
`cnuas switch sm status\\|enable\\|disable\\|trigger`	In-switch Subnet Manager
`cnuas switch telemetry show\\|clear`	Switch telemetry counters

4.3 fabric (HiLink GPU fabric)¶

Command	Purpose
`cnuas fabric ports`	List HiLink GPU-fabric ports
`cnuas fabric gpu-fdb`	Dump the GPU forwarding database
`cnuas fabric set-link PORT --up/--down`	Set a HiLink port link state
`cnuas fabric telemetry show\\|clear`	HiLink telemetry counters
`cnuas fabric version`	HiLink daemon version

4.4 gpu (HiGPU devices)¶

Command	Purpose
`cnuas gpu list`	List HiGPU devices
`cnuas gpu info GPU_ID`	Detailed info for one GPU
`cnuas gpu link GPU_ID`	HiLink status for one GPU

4.5 nic (HiNIC and RDMA devices)¶

Command	Purpose
`cnuas nic list`	List RDMA devices
`cnuas nic info DEVICE`	Detailed info for one RDMA device

4.6 vm (virtual-machine lifecycle)¶

Command	Purpose
`cnuas vm list`	List known VMs and their state
`cnuas vm status NAME`	Show one VM state
`cnuas vm up NAME --gpus N`	Bring up a VM from the golden image
`cnuas vm down NAME --force`	Shut down a VM
`cnuas vm lab`	Bring up the default two-VM lab

4.7 api¶

Command	Purpose
`cnuas api --host H --port P`	Run the REST service

5. REST API¶

Start the service and browse the interactive OpenAPI docs.

Interactive API reference hosted in these docs

You do not need a running service to explore the API. This documentation hosts the live schema in two interactive browsers:

Swagger UI, expand endpoints, schemas, and Try it out.
ReDoc, a three-pane reference view.
Raw schema, openapi.json.

A running service additionally serves Swagger UI at /docs, ReDoc at /redoc, and the schema at /openapi.json.

cnuas api --host 0.0.0.0 --port 8080
# interactive docs:  http://<host>:8080/docs
# schema:            http://<host>:8080/openapi.json

All resource endpoints live under the /api/v1 prefix. Request bodies are validated before they reach a daemon, so malformed input is rejected with 422.

5.1 Meta endpoints¶

Method	Path	Purpose
GET	`/`	Service banner and version
GET	`/health`	Component reachability probe
GET	`/api/v1/system/inventory`	Aggregated snapshot
GET	`/api/v1/system/versions`	Per-component versions

5.2 Switch endpoints¶

Method	Path	Purpose
GET	`/api/v1/switch/ports`	List all ports
GET	`/api/v1/switch/ports/{port}`	One port
PUT	`/api/v1/switch/ports/{port}/mode`	Set port mode
PUT	`/api/v1/switch/ports/{port}/link`	Set link state
PUT	`/api/v1/switch/ports/{port}/pfc`	Configure PFC
PUT	`/api/v1/switch/ports/{port}/ecn`	Configure ECN
PUT	`/api/v1/switch/ports/{port}/ets`	Configure ETS
GET, POST, DELETE	`/api/v1/switch/fdb`	Ethernet FDB
GET, POST, DELETE	`/api/v1/switch/lft`	InfiniBand LFT
GET	`/api/v1/switch/sm`	Subnet Manager status
POST	`/api/v1/switch/sm/{action}`	Subnet Manager action
GET	`/api/v1/switch/telemetry`	Telemetry counters
POST	`/api/v1/switch/telemetry/clear`	Reset telemetry

5.3 Fabric endpoints¶

Method	Path	Purpose
GET	`/api/v1/fabric/ports`	List HiLink ports
GET	`/api/v1/fabric/gpu-fdb`	GPU forwarding database
PUT	`/api/v1/fabric/link`	Set a HiLink port link state
GET	`/api/v1/fabric/telemetry`	Telemetry counters
POST	`/api/v1/fabric/telemetry/clear`	Reset telemetry
GET	`/api/v1/fabric/version`	HiLink daemon version

5.4 GPU, NIC and VM endpoints¶

Method	Path	Purpose
GET	`/api/v1/gpu`	List GPUs
GET	`/api/v1/gpu/{gpu_id}`	One GPU
GET	`/api/v1/gpu/{gpu_id}/link`	GPU HiLink status
GET	`/api/v1/nic`	List RDMA devices
GET	`/api/v1/nic/{device}`	One RDMA device
GET	`/api/v1/vm`	List VMs
GET	`/api/v1/vm/{name}`	One VM state
POST	`/api/v1/vm/{name}/up`	Bring up a VM
POST	`/api/v1/vm/{name}/down`	Shut down a VM

5.5 Examples¶

curl http://localhost:8080/health
curl http://localhost:8080/api/v1/switch/ports
curl -X PUT http://localhost:8080/api/v1/switch/ports/2/mode \
     -H 'content-type: application/json' \
     -d '{"mode": "STRICT_IB"}'
curl -X POST http://localhost:8080/api/v1/vm/vm-a/up?gpus=1

6. Error model¶

Every error is a typed CnuasError that the REST layer maps to an HTTP status.

Error	HTTP status	Meaning
`ComponentUnavailable`	503	A backend socket, device, or daemon could not be reached
`CommandError`	502	A backend accepted the request but reported an error
`NotFoundError`	404	A requested port, GPU, VM, or device does not exist
`InvalidRequest`	400	The caller supplied an invalid argument

The CLI prints the same errors to stderr and exits non-zero.

7. Testing¶

The package ships an offline test suite that stands up fake UNIX-socket daemons, temporary sysfs trees, and a temporary VM state directory, so the full control plane is exercised without any real hardware or running daemons.

pip install -e 'cnuas[test]'
pytest cnuas/tests -q