From cd3f6576c93df1f066b65eccc4a879ee91d4b5c8 Mon Sep 17 00:00:00 2001 From: Claudio Date: Tue, 21 Oct 2025 17:12:12 +0200 Subject: [PATCH] docs: document Aleph VM orchestrator endpoints --- docs/.vitepress/config.mts | 3 +- docs/devhub/api/aleph-vm-orchestrator.md | 89 ++++++++++++++++++++++++ docs/devhub/compute-resources/index.md | 2 + 3 files changed, 93 insertions(+), 1 deletion(-) create mode 100644 docs/devhub/api/aleph-vm-orchestrator.md diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts index 537ca84..e8e3307 100644 --- a/docs/.vitepress/config.mts +++ b/docs/.vitepress/config.mts @@ -340,7 +340,8 @@ export default defineConfig({ text: 'API Reference', collapsed: true, items: [ - { text: 'REST API', link: '/devhub/api-reference/rest' } + { text: 'REST API', link: '/devhub/api-reference/rest' }, + { text: 'Aleph VM Orchestrator API', link: '/devhub/api/aleph-vm-orchestrator' } ] }, { diff --git a/docs/devhub/api/aleph-vm-orchestrator.md b/docs/devhub/api/aleph-vm-orchestrator.md new file mode 100644 index 0000000..f379a24 --- /dev/null +++ b/docs/devhub/api/aleph-vm-orchestrator.md @@ -0,0 +1,89 @@ +# Aleph VM Orchestrator API + +The Aleph VM orchestrator exposes HTTP endpoints on each Compute Resource Node (CRN) to manage virtual machines and retrieve operational data. Use this reference when you need to automate instance lifecycle tasks or inspect node health. + +## Base URL + +Replace `` with the public hostname or IP address of the target CRN: + +```text +https:// +``` + +## Authentication + +Control endpoints require a valid allocation token signature. Include your token in the `X-Auth-Signature` header, as illustrated in the [local testing guide](/nodes/compute/advanced/local-testing/). + +## Control endpoints + +| Method | Path | Description | Auth | +| --- | --- | --- | --- | +| `POST` | `/control/reserve_resources` | Reserve capacity for upcoming executions. | Required | +| `POST` | `/control/allocations` | Submit allocation updates, including VM start requests. | Required | +| `POST` | `/control/allocation/notify` | Notify the orchestrator about allocation events. | Required | + +## Machine lifecycle endpoints + +| Method | Path | Description | Auth | +| --- | --- | --- | --- | +| `POST` | `/control/machine/{ref}/update` | Apply configuration updates to the VM identified by `{ref}`. | Required | +| `POST` | `/control/machine/{ref}/stop` | Gracefully stop the VM. | Required | +| `POST` | `/control/machine/{ref}/erase` | Remove VM data from the node. | Required | +| `POST` | `/control/machine/{ref}/reboot` | Reboot the VM. | Required | +| `POST` | `/control/machine/{ref}/expire` | Mark the VM as expired so it can be reclaimed. | Required | + +## Log streaming endpoints + +| Method | Path | Description | Auth | +| --- | --- | --- | --- | +| `GET` | `/control/machine/{ref}/logs` | Fetch recent execution logs as JSON. | Required | +| `GET` | `/control/machine/{ref}/stream_logs` | Stream live logs over an HTTP connection. | Required | + +## Confidential computing endpoints + +| Method | Path | Description | Auth | +| --- | --- | --- | --- | +| `POST` | `/control/machine/{ref}/confidential/initialize` | Initialize the confidential execution environment. | Required | +| `GET` | `/control/machine/{ref}/confidential/measurement` | Retrieve measurement data for attestation. | Required | +| `POST` | `/control/machine/{ref}/confidential/inject_secret` | Inject encrypted secrets into the VM. | Required | + +## Status endpoints + +These endpoints are useful for health checks and diagnostics. + +| Method | Path | Description | +| --- | --- | --- | +| `GET` | `/status/check/fastapi` | Confirms the FastAPI worker is reachable. | +| `GET` | `/status/check/fastapi/legacy` | Backward-compatible FastAPI health check. | +| `GET` | `/status/check/host` | Reports host-level availability. | +| `GET` | `/status/check/version` | Returns the orchestrator build version. | +| `GET` | `/status/check/ipv6` | Confirms IPv6 connectivity. | +| `GET` | `/status/config` | Provides a sanitized view of public configuration. | + +## About endpoints + +Use these read-only endpoints to inspect running executions and node metadata. + +| Method | Path | Description | +| --- | --- | --- | +| `GET` | `/about/login` | Retrieves the token-gated login form for operator pages. | +| `GET` | `/about/executions/list` | Lists current executions. | +| `GET` | `/v2/about/executions/list` | Lists executions using the v2 schema. | +| `GET` | `/about/executions/details` | Returns details for a specific execution. | +| `GET` | `/about/executions/records` | Provides execution history records. | +| `GET` | `/about/usage/system` | Reports system usage metrics. | +| `GET` | `/about/certificates` | Shows TLS certificates managed by the node. | +| `GET` | `/about/capability` | Enumerates node capabilities. | +| `GET` | `/about/config` | Displays operator configuration. | + +## Debug endpoints + +| Method | Path | Description | +| --- | --- | --- | +| `GET` | `/debug/haproxy` | Exposes HAProxy statistics for debugging. | + +## Related resources + +- [REST API documentation](/devhub/api/rest) +- [Compute resources overview](/devhub/compute-resources/) +- [Local testing with Aleph VM](/nodes/compute/advanced/local-testing/) diff --git a/docs/devhub/compute-resources/index.md b/docs/devhub/compute-resources/index.md index 0d895dc..0236f33 100644 --- a/docs/devhub/compute-resources/index.md +++ b/docs/devhub/compute-resources/index.md @@ -15,6 +15,8 @@ Functions can be executed in parallel on multiple Compute Resource Nodes while t In both cases, user workloads are executed inside virtual machines (VMs) isolated from each other. +For automation against Compute Resource Nodes, refer to the [Aleph VM Orchestrator API](/devhub/api/aleph-vm-orchestrator) reference. + ## Overview of VMs There are several types of VMs available on the network: