feat: introduce Nest workspace for local Firecracker management
- Added a new server module for the Nest workspace, integrating with UVM's API. - Updated project description to reflect the new Nest functionality. - Created tests for the Nest server and CLI, ensuring proper functionality and error handling. - Refactored existing UVM server code to separate Nest and UVM functionalities. - Removed the old UVM dashboard assets package as it is now part of the Nest workspace. - Enhanced error messages for clarity regarding server shutdown commands.
This commit is contained in:
@@ -1,8 +1,8 @@
|
||||
# UVM Usage Guide
|
||||
# Nest and UVM Usage Guide
|
||||
|
||||
This guide explains how to install, operate, and troubleshoot UVM as an
|
||||
operator. It covers the command-line tool, the optional FastAPI server, common
|
||||
scenarios, and expected limitations.
|
||||
This guide explains how to install, operate, and troubleshoot Nest and its UVM
|
||||
machine-management backend. It covers the Nest dashboard, UVM command-line
|
||||
tool, FastAPI server, common scenarios, and expected limitations.
|
||||
|
||||
For the project architecture and contributor guidance, see
|
||||
[DEVELOPER.md](DEVELOPER.md). For a concise overview, see [README.md](README.md).
|
||||
@@ -68,20 +68,23 @@ lscpu | grep -i virtualization
|
||||
From this project root:
|
||||
|
||||
```sh
|
||||
./nest.py --help
|
||||
./uvm.py --help
|
||||
python3 -B -m uvm --help
|
||||
```
|
||||
|
||||
To install the optional HTTP API dependencies and the console command:
|
||||
To install the HTTP server dependencies and console commands:
|
||||
|
||||
```sh
|
||||
python3 -m pip install .
|
||||
nest --help
|
||||
uvm --help
|
||||
```
|
||||
|
||||
The rest of this guide uses `./uvm.py` so it works from a source checkout. If
|
||||
you installed the package, replace `./uvm.py` with `uvm`. For the API, use the
|
||||
Python environment containing the installed dependencies; under `sudo`, use
|
||||
you installed the package, replace `./uvm.py` with `uvm` and `./nest.py` with
|
||||
`nest`. For the server, use the Python environment containing the installed
|
||||
dependencies; under `sudo`, use
|
||||
the full path to that environment's console script when necessary.
|
||||
|
||||
### Privilege Rules
|
||||
@@ -107,6 +110,7 @@ Examples elsewhere are separate scenarios; substitute your VM identifiers
|
||||
and do not run every destructive example as a single script.
|
||||
|
||||
```text
|
||||
nest --serve [--host HOST] [--port PORT]
|
||||
uvm install [--force]
|
||||
uvm create [--name NAME] [--cpu CPU] [--ram RAM] [--storage STORAGE] [--guest-ip GUEST_IP]
|
||||
[--username USER] [--password PASSWORD | --password-stdin]
|
||||
@@ -144,7 +148,8 @@ not disable confirmations, and errors may still be plain text on stderr.
|
||||
### Stop the Management API
|
||||
|
||||
The API can be stopped remotely through its authenticated shutdown endpoint.
|
||||
This stops only the UVM API process; it does not stop or delete any VM:
|
||||
This stops the serving Nest or standalone UVM process; it does not stop or
|
||||
delete any VM:
|
||||
|
||||
```sh
|
||||
curl -X POST \
|
||||
@@ -766,31 +771,38 @@ UVM will not blindly signal that PID or delete a possibly in-use disk. Listing
|
||||
does not perform adoption. Inspect such failures rather than manually
|
||||
inventing identity fields in `state.json`.
|
||||
|
||||
## 10. Use the FastAPI Server
|
||||
## 10. Use the Nest Workspace and FastAPI Server
|
||||
|
||||
The API uses the same local lifecycle services and exposes health, installation,
|
||||
VM lifecycle, diagnostics, bounded VM-log tails, and managed private-port
|
||||
controls. The local dashboard at `/dashboard` uses those same endpoints. There
|
||||
API also supports fixed-target bulk actions; interactive SSH remains CLI-only.
|
||||
controls. Nest owns the local dashboard at `/dashboard` and serves it alongside
|
||||
these UVM-backed endpoints. The API also supports fixed-target bulk actions;
|
||||
interactive SSH remains CLI-only.
|
||||
The server does not autostart VMs or reconcile rules, and is not safe to expose
|
||||
directly to the public internet.
|
||||
|
||||
### Start a Local Server
|
||||
|
||||
After installing the project dependencies, start the server as root:
|
||||
After installing the project dependencies, start the Nest workspace as root:
|
||||
|
||||
```sh
|
||||
export UVM_API_TOKEN='replace-with-a-long-random-visible-ascii-token'
|
||||
|
||||
sudo env \
|
||||
UVM_API_TOKEN="$UVM_API_TOKEN" \
|
||||
./uvm.py --serve --host 127.0.0.1 --port 8000
|
||||
./nest.py --serve --host 127.0.0.1 --port 8000
|
||||
```
|
||||
|
||||
Liveness is at `http://127.0.0.1:8000/health`; the dashboard is at
|
||||
`http://127.0.0.1:8000/dashboard`; OpenAPI docs are at
|
||||
`http://127.0.0.1:8000/docs`. The default bind is `127.0.0.1:8000`.
|
||||
|
||||
The installed command is `nest --serve`; `python3 -B -m nest --serve` also
|
||||
works from the source checkout. Nest uses `UVM_API_TOKEN` and the `UVM_*` host
|
||||
settings for its machine-management backend. To launch the standalone UVM API,
|
||||
use `./uvm.py --serve` with the same host/port options and configuration. That
|
||||
server exposes the management endpoints and `/docs`; Nest serves the dashboard.
|
||||
|
||||
The API token is required even for a loopback server. All VM, diagnostics, and
|
||||
installation routes require it. The dashboard shell, liveness route, and FastAPI's
|
||||
informational `/docs`, `/redoc`, and `/openapi.json` endpoints are available
|
||||
@@ -814,7 +826,7 @@ sudo env \
|
||||
UVM_API_TOKEN="$UVM_API_TOKEN" \
|
||||
UVM_API_TLS_CERT="$UVM_API_TLS_CERT" \
|
||||
UVM_API_TLS_KEY="$UVM_API_TLS_KEY" \
|
||||
./uvm.py --serve --host 0.0.0.0 --port 8443
|
||||
./nest.py --serve --host 0.0.0.0 --port 8443
|
||||
```
|
||||
|
||||
For real remote use, use a certificate trusted by clients and restrict network
|
||||
@@ -845,8 +857,8 @@ curl --cacert /path/to/ca.pem \
|
||||
|
||||
| Method | Path | Operation |
|
||||
|---|---|---|
|
||||
| `GET` | `/` | Redirect to `/dashboard` |
|
||||
| `GET` | `/dashboard` | Serve the local management dashboard |
|
||||
| `GET` | `/` | Redirect to `/dashboard` (Nest server) |
|
||||
| `GET` | `/dashboard` | Serve the Nest workspace dashboard (Nest server) |
|
||||
| `GET` | `/health` | Unauthenticated liveness |
|
||||
| `GET` | `/diagnostics` | Run host readiness checks |
|
||||
| `POST` | `/install` | Install/refresh with a `force` boolean |
|
||||
@@ -1318,7 +1330,7 @@ matching checksum with the required drivers instead. For an explicitly
|
||||
unverified development installation, retain the existing
|
||||
`UVM_ALLOW_UNVERIFIED_DOWNLOADS=1` setting as described in the installation section.
|
||||
|
||||
Restart a running UVM API server to load the updated code before using dashboard
|
||||
Restart a running Nest server to load the updated code before using dashboard
|
||||
start/restart actions. Look for `Started OpenBSD Secure Shell server` in the new
|
||||
boot log and confirm an actual SSH connection. `start` on an already-running
|
||||
VM only refreshes networking; use a stopped VM or `restart` to attach the device.
|
||||
|
||||
Reference in New Issue
Block a user