Skip to content

Commit 4f05c22

Browse files
AlchemiistCreativeAlchemiistCreative
committed
Documenting
1 parent 9cf8f53 commit 4f05c22

File tree

5 files changed

+261
-40
lines changed

5 files changed

+261
-40
lines changed

‎docs/.vitepress/config.ts‎

Lines changed: 2 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,6 @@ export default defineConfig({
1818

1919
nav: [
2020
{ text: "Home", link: "/" },
21-
{ text: "Architecture", link: "/architecture" },
2221
{ text: "API", link: "/api" },
2322
{ text: "Agents", link: "/agents" },
2423
{ text: "GitHub", link: "https://github.com/openhvx" },
@@ -29,17 +28,9 @@ export default defineConfig({
2928
text: "Getting Started",
3029
items: [
3130
{ text: "Overview", link: "/index" },
32-
{ text: "Workflow Example", link: "/workflow-example" }, // 👈 ajouté ici
3331
{ text: "Quick Start", link: "/getting-started" },
34-
],
35-
},
36-
{
37-
text: "Architecture",
38-
items: [
39-
{ text: "High-level Design", link: "/architecture" },
40-
{ text: "Control Plane", link: "/control-plane" },
41-
{ text: "Agent Lifecycle", link: "/agent-lifecycle" },
42-
{ text: "Inventory Merge Logic", link: "/inventory-merge" },
32+
{ text: "Workflow Example", link: "/workflow-example" },
33+
{ text: "Environment variables", link: "/environment-variables" },
4334
],
4435
},
4536
{
@@ -50,14 +41,6 @@ export default defineConfig({
5041
{ text: "Errors", link: "/errors" },
5142
],
5243
},
53-
{
54-
text: "Agents",
55-
items: [
56-
{ text: "Overview", link: "/agents" },
57-
{ text: "Hyper-V Agent", link: "/agents/hyperv" },
58-
{ text: "Tasks & Inventory", link: "/agents/tasks" },
59-
],
60-
},
6144
{
6245
text: "Contributing",
6346
items: [

‎docs/environment-variables.md‎

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
### 3. Environment Variables
2+
3+
Each service has its own `.env` file:
4+
5+
| Service | File | Description |
6+
| ------------ | ----------------- | ------------------------------ |
7+
| Auth Service | `.env.auth` | JWT and Mongo configuration |
8+
| API Gateway | `.env.gateway` | HTTP gateway + CORS |
9+
| Controller | `.env.controller` | Core logic, RabbitMQ, MongoDB |
10+
| WS Broker | `.env.ws` | WebSocket broker configuration |
11+
12+
---
13+
14+
### 🧩 Example configuration
15+
16+
#### **WS Broker**
17+
18+
| Variable | Example | Description |
19+
| -------------------- | --------------------- | ------------------------------- |
20+
| `PORT` | `8081` | HTTP port exposed by the broker |
21+
| `JWT_AGENT_SECRET` | `supersecret_agent` | Token for agent auth |
22+
| `JWT_BROWSER_SECRET` | `supersecret_browser` | Token for browser sessions |
23+
24+
---
25+
26+
#### **API Gateway**
27+
28+
| Variable | Example | Description |
29+
| ---------------- | --------------------------------------------- | ----------------------------------- |
30+
| `PORT` | `8080` | API Gateway port |
31+
| `AUTH_URL` | `http://auth:4000` | Internal service URL for Auth |
32+
| `CONTROLLER_URL` | `http://controller:3000` | Internal service URL for Controller |
33+
| `CORS_ORIGIN` | `http://localhost:5173,http://127.0.0.1:5173` | Allowed origins for web UI |
34+
| `BROKER_URL` | `http://ws-broker:8081` | Internal URL to WebSocket broker |
35+
36+
---
37+
38+
#### **Controller**
39+
40+
| Variable | Example | Description |
41+
| -------------------- | ----------------------------------- | ------------------------------- |
42+
| `PORT` | `3000` | HTTP port for Controller |
43+
| `CORS_ORIGIN` | `*` | Allowed origins |
44+
| `LOG_LEVEL` | `info` | Logging verbosity |
45+
| `MONGO_URL` | `mongodb://mongo:27017/hvwm` | Mongo connection string |
46+
| `MONGO_DB` | `openhvx` | Database name |
47+
| `RMQ_URL` | `amqp://guest:guest@rabbitmq:5672/` | RabbitMQ connection |
48+
| `JOBS_EXCHANGE` | `jobs` | Exchange for async jobs |
49+
| `TELEMETRY_EXCHANGE` | `agent.telemetry` | Exchange for telemetry |
50+
| `RESULTS_EXCHANGE` | `results` | Exchange for agent task results |
51+
| `HEARTBEATS_QUEUE` | `agent.heartbeats` | Queue for agent heartbeats |
52+
| `HEARTBEATS_TTL_MS` | `120000` | Heartbeat timeout (ms) |
53+
| `INVENTORIES_QUEUE` | `agent.inventories` | Queue for agent inventories |
54+
| `RESULTS_QUEUE` | `results.controller` | Queue consumed by controller |
55+
| `RESULTS_BINDING` | `results.*` | Routing key pattern |
56+
| `AGENT_STALE_MS` | `120000` | Delay to mark agent as offline |
57+
| `IMAGES_INDEX_PATH` | `/share/_index/images.json` | Path to shared image index |
58+
| `JWT_AGENT_SECRET` | `supersecret_agent` | JWT secret for agents |
59+
| `JWT_BROWSER_SECRET` | `supersecret_browser` | JWT secret for browsers |
60+
| `PUBLIC_WS_BASE` | `wss://console.openhvx.local/api` | Browser WebSocket endpoint |
61+
| `BROKER_WS_BASE` | `wss://ws.openhvx.local` | Direct agent WebSocket endpoint |
62+
63+
---
64+
65+
#### **Auth Service**
66+
67+
| Variable | Example | Description |
68+
| -------------------- | --------------------------------- | --------------------------- |
69+
| `PORT` | `4000` | HTTP port |
70+
| `MONGO_URL` | `mongodb://mongo:27017/hvwm_auth` | Auth DB connection |
71+
| `JWT_SECRET` | `change-me` | Main signing secret |
72+
| `JWT_EXPIRES` | `8h` | Default token lifetime |
73+
| `AUTH_DEBUG` | `true` | Enable verbose logs |
74+
| `JWT_TENANT_ISS` | `auth-service/tenant` | JWT issuer (tenant) |
75+
| `JWT_TENANT_AUD` | `api://tenant` | JWT audience (tenant) |
76+
| `JWT_TENANT_SECRET` | `example_secret` | Tenant token secret |
77+
| `JWT_TENANT_EXPIRES` | `8h` | Tenant token lifetime |
78+
| `JWT_ADMIN_ISS` | `auth-service/admin` | JWT issuer (admin) |
79+
| `JWT_ADMIN_AUD` | `api://admin` | JWT audience (admin) |
80+
| `JWT_ADMIN_SECRET` | `example_secret` | Admin token secret |
81+
| `JWT_ADMIN_EXPIRES` | `30m` | Admin token lifetime |
82+
| `REGISTER_ENABLED` | `true` | Allow new user registration |
83+
| `REGISTER_API_KEY` | `example_api_key` | Optional registration key |
84+
85+
---

‎docs/getting-started.md‎

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
# Getting Started (Developer Preview)
2+
3+
> ⚠️ **Active Development:** OpenHVX is not production‑ready. This guide targets **contributors and early testers**.
4+
5+
## Prerequisites
6+
7+
- Windows host with **Hyper‑V** (for Agent tests)
8+
- **Docker/Podman & Docker Compose**
9+
- **Node.js 20+** and **npm**
10+
- **Go 1.21+** (to build Agent tools)
11+
12+
---
13+
14+
## Quick Start (Backend)
15+
16+
```bash
17+
# 1) Clone
18+
git clone https://github.com/openhvx/openhvx-backend.git
19+
cd openhvx-backend
20+
Pour cette partie, comment on fait le lien?
21+
# 2) Env
22+
Create and fill env files (.env.auth, .env.controller, .env.gateway, .env.ws)
23+
All variables and examples are documented in [Environment variables](https://openhvx.org/docs/environment-variables.html).
24+
25+
# 3) Run services
26+
docker compose up -d
27+
28+
```
29+
30+
---
31+
32+
## Build Agent Tools (Windows helpers)
33+
34+
These binaries are required by the PowerShell Agent to create cloud‑init ISOs and to bridge serial consoles.
35+
36+
**Layout:**
37+
38+
```
39+
/tools/
40+
cloudinit-iso/
41+
src/ # Go project
42+
serial-bridge/
43+
src/ # Go project
44+
/src/powershell/bin/ # ← final target for the built .exe files
45+
```
46+
47+
Use the provided **Makefile**:
48+
49+
```bash
50+
# From repo root
51+
make agent-bin
52+
```
53+
54+
This will:
55+
56+
1. Build Go projects in `/tools/cloudinit-iso/src` and `/tools/serial-bridge/src`
57+
2. Place the resulting binaries into `/src/powershell/bin`
58+
59+
> If you build manually, ensure you build `src/` first, then the tools, then move outputs to `/src/powershell/bin`.
60+
61+
---
62+
63+
## Running the Agent (on a Hyper‑V host)
64+
65+
1. Copy the folder `src/powershell/` and its `bin/` subfolder (containing the built `.exe`) to the Windows host.
66+
2. Open an elevated PowerShell.
67+
3. Create and configure the **config.json** file with your environment.
68+
69+
### Example `config.json`
70+
71+
```json
72+
{
73+
"agentId": "HOST-HVX-TEST-001",
74+
"rabbitmqUrl": "amqp://guest:guest@10.0.0.15:5672/",
75+
"heartbeatIntervalSec": 30,
76+
"inventoryIntervalSec": 90,
77+
"basePath": "D:\\VM-REPO",
78+
"capabilities": [
79+
"inventory",
80+
"vm.power",
81+
"vm.create",
82+
"vm.delete",
83+
"console",
84+
"vm.edit"
85+
]
86+
}
87+
```
88+
89+
### Start the Agent
90+
91+
```powershell
92+
# Example (adapt to your parameters)
93+
# .\openhvx-agent.exe
94+
```
95+
96+
---
97+
98+
## Next Steps
99+
100+
- Read: **Overview → Architecture & Features**
101+
- Contribute: open issues/PRs on GitHub: [https://github.com/openhvx](https://github.com/openhvx)
102+
- Roadmap & known limitations: _(coming soon)_

‎docs/index.md‎

Lines changed: 46 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,46 @@
1-
# Work in Progress
1+
# Overview
2+
3+
OpenHVX is an open-source orchestration platform for **multi-tenant Hyper-V infrastructures**. It provides a unified control plane to manage virtual machines, quotas, and networking across distributed hosts, built on a lightweight and modular design.
4+
5+
> ⚠️ **Active Development Notice:** OpenHVX is under active development and not yet production-ready.
6+
> Expect rapid iteration and potential breaking changes between releases.
7+
> Community testing and contributions are highly encouraged!
8+
9+
---
10+
11+
## Architecture
12+
13+
OpenHVX separates orchestration and execution into clear layers.
14+
15+
The architecture is divided into four functional layers:
16+
17+
### Architecture Diagram
18+
19+
![Architecture Diagram Placeholder](/assets/schema.openhvx.dark.png)
20+
21+
- **Control Plane:** Includes the API Gateway, Authentication Service, Controller, Quota Service, WS-Broker (console tunneling), MongoDB, and RabbitMQ. It handles orchestration logic, workflows, multi-tenancy and quota enforcement.
22+
- **Data Plane:** Consists of lightweight PowerShell Agents running on Hyper-V hosts. Agents execute tasks, collect inventory, and stream console sessions.
23+
- **Integration Plane:** Manages tenant networking and routing through the Network Orchestrator (VyOS API, IPAM).
24+
- **Storage Layer:** SMB/NFS repositories store public and tenant-specific VM images.
25+
26+
The design emphasizes **asynchronous communication**, **tenant isolation**, and **extensibility** through modular services.
27+
28+
---
29+
30+
## Features
31+
32+
- **VM Lifecycle:** Create, edit, clone, and manage VMs with cloud-init and console access via WS-Broker.
33+
- **Quotas:** Per-tenant CPU, RAM, storage, and VM limits with atomic reservation (hold → execute → release).
34+
- **Multi-Tenancy:** Logical separation of compute, storage, and network resources per tenant.
35+
- **Networking:** Automated provisioning via VyOS API and IPAM integration for NAT, routing, and isolation. (Still under development)
36+
- **Authentication:** Admin and tenant login flows with JWT tokens and different audiences.
37+
- **Agents:** Lightweight, host-based agents for secure orchestration and telemetry.
38+
- **Extensible:** Modular microservice architecture, event-driven.
39+
40+
---
41+
42+
### 🤝 Contributing
43+
44+
We welcome contributions from the community! Whether it’s documentation improvements, feature suggestions, or bug reports — every input helps make OpenHVX better. Visit the [GitHub organization](https://github.com/openhvx) to get started.
45+
46+
> **Built for Hyper-V. Driven by automation. Empowered by simplicity.**

‎docs/workflow-example.md‎

Lines changed: 26 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -27,16 +27,18 @@ Authorization: Bearer <JWT>
2727
```
2828
2929
### Gateway actions
30-
1. **Validate JWT** using the appropriate audience (`tenant` or `admin`) via the **Auth Service**, depending on the host (`api.` or `api-admin.`).
31-
2. **Check roles and scopes** according to the request domain.
32-
3. Run **anti-spoofing and policy checks** (e.g., tenant ID consistency).
30+
31+
1. **Validate JWT** using the appropriate audience (`tenant` or `admin`) via the **Auth Service**, depending on the host (`api.` or `api-admin.`).
32+
2. **Check roles and scopes** according to the request domain.
33+
3. Run **anti-spoofing and policy checks** (e.g., tenant ID consistency).
3334
4. **Proxy the request** to the **Controller** service at `controller:[PORT]/api/admin/tasks`.
3435
3536
---
3637
3738
## 2. API Gateway → Controller
3839
3940
### Middleware & context setup
41+
4042
- **accessMode middleware**: sets `req.isAdmin = true|false`.
4143
- **Envelope validation**: ensures presence of `kind`, `refId`, and `target`.
4244
- **Schema pre-validation**: uses `src/lib/schemas/task.js` (per action, e.g. `vm.create`).
@@ -50,6 +52,7 @@ Authorization: Bearer <JWT>
5052
## 3. Agent Selection & Ownership
5153
5254
The **Controller** performs **agent election** based on:
55+
5356
- Agent heartbeat freshness.
5457
- Available resources (CPU, RAM, storage).
5558
- Advertised capabilities (`vm.create`, `network.*`, etc.).
@@ -61,6 +64,7 @@ If the selected agent already satisfies capability and availability requirements
6164
## 4. Payload Enrichment
6265
6366
**Controller** enriches and normalizes the incoming payload through `src/lib/enrich.js (vm.create)`:
67+
6468
- Sets default values for RAM, CPU, and storage.
6569
- Ensures proper image ID and generation type.
6670
- Adds default `cloud-init` configuration when missing.
@@ -69,16 +73,16 @@ If the selected agent already satisfies capability and availability requirements
6973
7074
## 5. Quota Reservation
7175
72-
1. Compute **resource deltas** (vCPU, RAM, storage).
73-
2. Perform a **quota hold** with TTL to reserve capacity temporarily.
74-
3. If limits are exceeded → respond with `ERR_QUOTA_EXCEEDED`.
76+
1. Compute **resource deltas** (vCPU, RAM, storage).
77+
2. Perform a **quota hold** with TTL to reserve capacity temporarily.
78+
3. If limits are exceeded → respond with `ERR_QUOTA_EXCEEDED`.
7579
4. If successful → continue with persistence and dispatch.
7680
7781
---
7882
7983
## 6. Task Persistence & Dispatch
8084
81-
- Persist the new Task document in MongoDB with `status: "sent"`.
85+
- Persist the new Task document in MongoDB with `status: "sent"`.
8286
- Publish the message to RabbitMQ:
8387
8488
```
@@ -109,34 +113,36 @@ If the selected agent already satisfies capability and availability requirements
109113
## 8. Result Handling
110114
111115
The **Controller** consumes results from the `results` exchange:
116+
112117
- Updates the Task document with final status (`SUCCESS` or `FAILED`).
113118
- Stores logs and execution metadata.
114119
115120
Depending on the result:
116-
- **Success** → consume the quota hold (commit resources).
121+
122+
- **Success** → consume the quota hold (commit resources).
117123
- **Failure** → release the quota hold (rollback).
118124
119125
---
120126
121127
## 9. Resource Linking
122128
123-
- Link the newly created VM to the corresponding **TenantResource** entry.
129+
- Link the newly created VM to the corresponding **TenantResource** entry.
124130
125131
---
126132
127133
## ✅ Summary (High-Level Flow)
128134
129-
| Step | Service | Description |
130-
|------|----------|-------------|
131-
| 1 | API Gateway | Auth, scopes, anti-spoofing, proxy |
132-
| 2 | Controller | Envelope & schema validation |
133-
| 3 | Controller | Agent election & ownership checks |
134-
| 4 | Controller | Payload enrichment |
135-
| 5 | Controller | Quota hold reservation |
136-
| 6 | Controller + MQ | Persist and publish task to agent queue |
137-
| 7 | Agent | Execute PowerShell script on Hyper-V |
138-
| 8 | Controller | Process result and adjust quota |
139-
| 9 | Controller | Link resources |
135+
| Step | Service | Description |
136+
| ---- | --------------- | --------------------------------------- |
137+
| 1 | API Gateway | Auth, scopes, anti-spoofing, proxy |
138+
| 2 | Controller | Envelope & schema validation |
139+
| 3 | Controller | Agent election & ownership checks |
140+
| 4 | Controller | Payload enrichment & normalization |
141+
| 5 | Controller | Quota hold reservation |
142+
| 6 | Controller + MQ | Persist and publish task to agent queue |
143+
| 7 | Agent | Execute PowerShell script on Hyper-V |
144+
| 8 | Controller | Process result and adjust quota |
145+
| 9 | Controller | Link resources |
140146
141147
---
142148

0 commit comments

Comments
 (0)