Skip to content

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 (CnuasSwitch, CnuasLink, CnuasGPU, CnuasNIC, 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<br/>(Typer + Rich)"] REST["cnuas-api<br/>(FastAPI, OpenAPI at /docs)"] end SVC["CnuasService<br/>(shared facade)"] subgraph adapters["Adapters"] A1["Switch adapter"] A2["CnuasLink adapter"] A3["GPU adapter"] A4["NIC adapter"] A5["VM adapter"] A6["System adapter"] end subgraph backends["Backends"] B1["cnuas-vswitchd<br/>UNIX socket, JSON + newline"] B2["cnuasgpu-link-switchd<br/>UNIX socket, JSON"] B3["/dev/cnuasgpuN + sysfs<br/>CNUASGPU_IOC_INFO ioctl"] B4["/sys/class/infiniband<br/>RDMA sysfs"] B5["cnuas-tools vm<br/>state files + subprocess"] B6["git tags<br/>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 cnuas superproject repository.

python3 -m venv --system-site-packages .venv
. .venv/bin/activate
pip install -e cnuas

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

The test extra adds pytest and httpx, which are needed only to run the test suite described in section 7. Installing the package to use it does not need them.

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
CNUAS_RUN_DIR /var/run/cnuas Switch run directory holding mgmt.sock
CNUASLINK_RUN_DIR /var/run/cnuaslink CnuasLink run directory
CNUAS_SWITCH_SOCKET $CNUAS_RUN_DIR/mgmt.sock Switch management socket
CNUAS_CNUASLINK_SOCKET $CNUASLINK_RUN_DIR/mgmt.sock CnuasLink management socket
CNUAS_GPU_SYSFS /sys/class/cnuasgpu CnuasGPU sysfs class root
CNUAS_GPU_DEV_DIR /dev CnuasGPU character device directory
CNUAS_NIC_SYSFS /sys/class/infiniband RDMA sysfs class root
CNUAS_DATA_DIR XDG data home VM state root (<dir>/vms/<name>/state.json)
CNUAS_VM_TOOL cnuas-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                      ┃
┡━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ cnuas       │ v0.1.0                       │
│ cnuasnic    │ v0.1.0-23-gd97b1c9           │
│ cnuasswitch │ v0.1.0-4-g1700b86            │
│ cnuasgpu    │ v0.2.0-3-g4104982            │
│ cnuaslink   │ v0.1.0                       │
│ kernel      │ cnuas-v6.19.0                │
│ qemu        │ cnuas-qemu-v0.1.0-2-g6b326b4 │
└─────────────┴──────────────────────────────┘

4.2 switch (CnuasSwitch 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
Command Purpose
cnuas fabric ports List CnuasLink GPU-fabric ports
cnuas fabric gpu-fdb Dump the GPU forwarding database
cnuas fabric set-link PORT --up/--down Set a CnuasLink port link state
cnuas fabric telemetry show\|clear CnuasLink telemetry counters
cnuas fabric version CnuasLink daemon version

4.4 gpu (CnuasGPU devices)

Command Purpose
cnuas gpu list List CnuasGPU devices
cnuas gpu info GPU_ID Detailed info for one GPU
cnuas gpu link GPU_ID CnuasLink status for one GPU

4.5 nic (CnuasNIC 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:

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 CnuasLink ports
GET /api/v1/fabric/gpu-fdb GPU forwarding database
PUT /api/v1/fabric/link Set a CnuasLink port link state
GET /api/v1/fabric/telemetry Telemetry counters
POST /api/v1/fabric/telemetry/clear Reset telemetry
GET /api/v1/fabric/version CnuasLink 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 CnuasLink 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