Surface-complete contract packs drive schema routes for every API-ref operation.
+
-
+
+ ${sizes.map((s) => {
+ const active = profile === s.id;
+ return `
+
+
+
${escapeHtml(s.label)}
+ ${escapeHtml(s.chip)}
+
+
+ - Hosts
- ${s.hosts}
+ - VMs
- ${s.vms}
+ - DC
- ${s.dc}
+ - Clusters
- ${s.clusters}
+
+ ${escapeHtml(s.note)}
+
+ `;
+ }).join("")}
+
+
@@ -5271,12 +5417,12 @@
renderDemoState(await res.json());
}
- async function loadDemoData() {
- const loadBtn = document.getElementById("btn-demo-load");
- if (loadBtn) loadBtn.disabled = true;
+ async function loadDemoData(size = "large") {
+ const loadBtns = document.querySelectorAll("[data-demo-size]");
+ loadBtns.forEach((btn) => { btn.disabled = true; });
setLoading(true);
try {
- const res = await fetch("/ui/api/demo/load", { method: "POST" });
+ const res = await fetch(`/ui/api/demo/load?size=${encodeURIComponent(size)}`, { method: "POST" });
const body = await res.json().catch(() => ({}));
if (!res.ok) {
const detail = Array.isArray(body.detail)
@@ -5293,20 +5439,24 @@
persistAuth();
}
await refreshOverview();
- toast("oVirt demo datacenter loaded (~1000 VMs)", "ok");
+ const seed = body.seed || body.summary || {};
+ toast(
+ `Cluster ${seed.profile || size} loaded (${seed.hosts ?? "?"} hosts · ${seed.vms ?? "?"} VMs)`,
+ "ok",
+ );
toast("Sign in again (admin@internal / secret) — tokens were reset with the seed", "warn");
} finally {
- if (loadBtn) loadBtn.disabled = false;
+ loadBtns.forEach((btn) => { btn.disabled = false; });
setLoading(false);
}
}
async function unloadDemoData() {
const confirmed = await showConfirm({
- title: "Remove demo data?",
- message: "This wipes simulator DB state (demo data and anything created via the API), then reloads a minimal cluster.",
- confirmLabel: "Remove demo data",
- cancelLabel: "Keep demo data",
+ title: "Reset to minimal?",
+ message: "This wipes current simulator DB state (sized demo and anything created via the API), then loads the minimal cluster (1 host · 1 VM).",
+ confirmLabel: "Reset to minimal",
+ cancelLabel: "Keep current data",
tone: "danger",
});
if (!confirmed) return;
@@ -5327,7 +5477,7 @@
persistAuth();
}
await refreshOverview();
- toast("Demo data removed — sign in again if needed", "info");
+ toast("Minimal cluster loaded — sign in again if needed", "info");
} finally {
if (unloadBtn) unloadBtn.disabled = false;
setLoading(false);
@@ -5704,14 +5854,18 @@
if (!els.dataPanel || els.dataPanel.dataset.demoBound) return;
els.dataPanel.dataset.demoBound = "1";
els.dataPanel.addEventListener("click", (event) => {
- const target = event.target.closest("#btn-demo-load, #btn-demo-unload, #btn-demo-refresh");
- if (!target) return;
- if (target.id === "btn-demo-load") {
- loadDemoData().catch((error) => {
+ const loadBtn = event.target.closest("[data-demo-size]");
+ if (loadBtn) {
+ const size = loadBtn.getAttribute("data-demo-size") || "large";
+ loadDemoData(size).catch((error) => {
showError(String(error));
toast("Failed to load demo data", "error");
});
- } else if (target.id === "btn-demo-unload") {
+ return;
+ }
+ const target = event.target.closest("#btn-demo-unload, #btn-demo-refresh");
+ if (!target) return;
+ if (target.id === "btn-demo-unload") {
unloadDemoData().catch((error) => {
showError(String(error));
toast("Failed to remove demo data", "error");
@@ -6421,9 +6575,11 @@
try {
const parsed = JSON.parse(body || "{}");
if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+ const { inner } = unwrapBodyExample(parsed);
for (const field of bodyFields) {
- if (Object.prototype.hasOwnProperty.call(parsed, field.name)) {
- state.bodyValues[field.name] = String(parsed[field.name] ?? "");
+ const value = getByPath(inner, field.name);
+ if (value !== undefined && value !== null) {
+ state.bodyValues[field.name] = String(value);
}
}
}
@@ -6496,31 +6652,95 @@
return target === "cluster" ? buildClusterUrl(apiPath) : buildEmulatorUrl(apiPath);
}
+ function deepCloneJson(value) {
+ if (value == null) return value;
+ return JSON.parse(JSON.stringify(value));
+ }
+
+ function getByPath(root, path) {
+ if (!path) return root;
+ const parts = String(path).split(".");
+ let cur = root;
+ for (const part of parts) {
+ if (cur == null || typeof cur !== "object") return undefined;
+ cur = cur[part];
+ }
+ return cur;
+ }
+
+ function setByPath(root, path, value) {
+ const parts = String(path).split(".");
+ let cur = root;
+ for (let i = 0; i < parts.length - 1; i += 1) {
+ const part = parts[i];
+ const next = parts[i + 1];
+ const wantArray = /^\d+$/.test(next);
+ if (cur[part] == null || typeof cur[part] !== "object") {
+ cur[part] = wantArray ? [] : {};
+ }
+ cur = cur[part];
+ }
+ cur[parts[parts.length - 1]] = value;
+ }
+
+ function deleteByPath(root, path) {
+ const parts = String(path).split(".");
+ let cur = root;
+ for (let i = 0; i < parts.length - 1; i += 1) {
+ if (cur == null || typeof cur !== "object") return;
+ cur = cur[parts[i]];
+ }
+ if (cur && typeof cur === "object") delete cur[parts[parts.length - 1]];
+ }
+
+ function unwrapBodyExample(example) {
+ if (!example || typeof example !== "object" || Array.isArray(example)) {
+ return { wrapKey: null, inner: {} };
+ }
+ const keys = Object.keys(example);
+ if (
+ keys.length === 1
+ && example[keys[0]]
+ && typeof example[keys[0]] === "object"
+ && !Array.isArray(example[keys[0]])
+ ) {
+ return { wrapKey: keys[0], inner: example[keys[0]] };
+ }
+ return { wrapKey: null, inner: example };
+ }
+
function syncBodyFromFields({ syncVisibility = true } = {}) {
if (!state.method) return;
const inputs = [...(els.bodyFields?.querySelectorAll("input[data-field]") || [])];
- const body = {};
+ const example = state.method.body_example;
+ const { wrapKey, inner } = unwrapBodyExample(example);
+ const root = deepCloneJson(inner) || {};
+ let touched = false;
inputs.forEach((input) => {
const name = input.dataset.field;
+ if (!name) return;
const raw = input.value.trim();
- if (!raw) return;
- if (raw === "true" || raw === "false") body[name] = raw === "true";
- else if (/^-?\d+$/.test(raw)) body[name] = Number(raw);
- else if (/^-?\d+\.\d+$/.test(raw)) body[name] = Number(raw);
- else body[name] = raw;
- });
- // If PARAM fields are empty, fall back to method body_example so the editor
- // updates when switching verbs / endpoints.
- if (!Object.keys(body).length) {
- const example = state.method.body_example;
- if (example && typeof example === "object" && !Array.isArray(example)) {
- for (const [key, value] of Object.entries(example)) {
- if (value === undefined || value === null || value === "") continue;
- body[key] = value;
- }
+ const existing = getByPath(root, name);
+ if (!raw && existing === undefined) return;
+ touched = true;
+ if (!raw) {
+ deleteByPath(root, name);
+ return;
}
+ let value = raw;
+ if (raw === "true" || raw === "false") value = raw === "true";
+ else if (/^-?\d+$/.test(raw)) value = Number(raw);
+ else if (/^-?\d+\.\d+$/.test(raw)) value = Number(raw);
+ setByPath(root, name, value);
+ });
+ // Empty PARAM inputs → keep full body_example; edits merge into the Engine root wrap.
+ if (!touched && example && typeof example === "object" && !Array.isArray(example)) {
+ els.body.value = Object.keys(example).length ? JSON.stringify(example, null, 2) : "";
+ updateBodyHighlight();
+ if (syncVisibility) updateBodyPaneVisibility(state.method);
+ return;
}
- // Keep empty object out of the editor — do not show `{}`.
+ const body = wrapKey ? { [wrapKey]: root } : root;
els.body.value = Object.keys(body).length ? JSON.stringify(body, null, 2) : "";
updateBodyHighlight();
if (syncVisibility) {
@@ -6748,7 +6968,6 @@
await loadVersions();
await loadCatalog({ major, preserveSelection: true, silent: true });
await refreshOverview();
- await refreshoVirtPack();
toast(`Runtime switched to ${state.runtimeVersion || seriesLabel(major)}`, "ok");
} finally {
setLoading(false);
@@ -6770,84 +6989,6 @@
applyMethodDetails(payload);
}
- async function refreshoVirtPack() {
- try {
- const res = await fetch("/ui/api/ovirt/contracts");
- if (!res.ok) return;
- const data = await res.json();
- const active = data.active || {};
- setText(els.statOsSeries, active.series || "—");
- setText(els.statOsOps, String(active.operation_count ?? data.schema_ops_mounted ?? "—"));
- setText(els.statOsServices, String(active.service_count ?? "—"));
- if (els.osSeriesSelect) {
- const available = data.available || [];
- els.osSeriesSelect.innerHTML = available.map((s) =>
- `
`
- ).join("");
- }
- if (els.osMvService) {
- const services = (active.services || []).filter((s) => s.max_microversion);
- els.osMvService.innerHTML = services.map((s) =>
- `
`
- ).join("");
- }
- if (els.osPackNote) {
- els.osPackNote.textContent = `Pack ${active.series || "—"} · ${active.operation_count || 0} operations · checksum ${(active.checksum || "").slice(0, 12)}…`;
- }
- } catch (e) {
- console.error(e);
- }
- }
-
- function bindoVirtPackActions() {
- els.btnOsSeriesActivate?.addEventListener("click", async () => {
- const series = els.osSeriesSelect?.value;
- if (!series) return;
- const res = await fetch("/ui/api/ovirt/contracts/activate", {
- method: "POST",
- headers: { "Content-Type": "application/json" },
- body: JSON.stringify({ series }),
- });
- const payload = await res.json().catch(() => ({}));
- if (!res.ok) {
- toast(payload.detail || `Activate failed: ${res.status}`, "error");
- return;
- }
- toast(`oVirt pack: ${payload.series} (${payload.operation_count} ops)`, "ok");
- await refreshoVirtPack();
- });
- els.btnOsMvSet?.addEventListener("click", async () => {
- const service = els.osMvService?.value;
- const version = els.osMvVersion?.value?.trim();
- if (!service || !version) {
- toast("Pick a service and microversion", "warn");
- return;
- }
- const res = await fetch("/ui/api/ovirt/microversions", {
- method: "POST",
- headers: { "Content-Type": "application/json" },
- body: JSON.stringify({ service, version }),
- });
- if (!res.ok) {
- toast(`Microversion set failed: ${res.status}`, "error");
- return;
- }
- toast(`${service} → ${version}`, "ok");
- await refreshoVirtPack();
- });
- els.btnOsMvClear?.addEventListener("click", async () => {
- const service = els.osMvService?.value;
- if (!service) return;
- await fetch("/ui/api/ovirt/microversions", {
- method: "POST",
- headers: { "Content-Type": "application/json" },
- body: JSON.stringify({ service, version: "default" }),
- });
- toast(`${service} microversion reset`, "ok");
- await refreshoVirtPack();
- });
- }
-
async function refreshOverview() {
try {
setText(
@@ -6856,7 +6997,6 @@
);
await refreshClusterStats();
await refreshCatalogCoverage();
- await refreshoVirtPack();
} catch (e) { console.error(e); }
}
@@ -7142,7 +7282,6 @@
bindCatalogOptions();
bindHelpNav();
bindDataPanelActions();
- bindoVirtPackActions();
bindModal();
bindTooltips();
bindEndpointTree();
diff --git a/app/web/ovirt_body_examples.py b/app/web/ovirt_body_examples.py
new file mode 100644
index 0000000..ccc9b17
--- /dev/null
+++ b/app/web/ovirt_body_examples.py
@@ -0,0 +1,327 @@
+"""Engine-shaped JSON request-body examples for the Web console.
+
+Bodies follow the oVirt Engine REST convention: a single root element wrapping
+the resource (or ``action``). Field shapes match what this simulator accepts and
+what the public Engine API model documents for common create/update/action calls.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from app.ovirt.ids import stable_id
+
+# Minimal-seed stable IDs (see app.ovirt.seed) — usable with `make seed`.
+_DC = str(stable_id("dc", "Default"))
+_CLUSTER = str(stable_id("cluster", "Default"))
+_HOST = str(stable_id("host", "host01"))
+_TEMPLATE = str(stable_id("template", "Blank"))
+_SD = str(stable_id("sd", "data1"))
+_NET = str(stable_id("net", "ovirtmgmt"))
+_VNIC = str(stable_id("vnic", "ovirtmgmt"))
+_VM = str(stable_id("vm", "lab-vm-01"))
+_DISK = str(stable_id("disk", "lab-vm-01"))
+_USER = str(stable_id("user", "admin"))
+_ROLE = str(stable_id("role", "SuperUser"))
+_DOMAIN = str(stable_id("domain", "internal"))
+
+
+def _ref(collection: str, object_id: str, *, name: str | None = None) -> dict[str, Any]:
+ entity: dict[str, Any] = {
+ "id": object_id,
+ "href": f"/ovirt-engine/api/{collection}/{object_id}",
+ }
+ if name is not None:
+ entity["name"] = name
+ return entity
+
+
+def _wrap(element: str, payload: dict[str, Any]) -> dict[str, Any]:
+ return {element: payload}
+
+
+def _entity_bodies() -> dict[str, dict[str, Any]]:
+ """Map contract ``element`` → inner payload (without root wrapper)."""
+
+ return {
+ "vm": {
+ "name": "example-vm",
+ "description": "Example virtual machine",
+ "type": "server",
+ "memory": 1073741824,
+ "cpu": {"topology": {"sockets": 1, "cores": 1, "threads": 1}},
+ "os": {"type": "other"},
+ "cluster": _ref("clusters", _CLUSTER, name="Default"),
+ "template": _ref("templates", _TEMPLATE, name="Blank"),
+ },
+ "host": {
+ "name": "host-02",
+ "address": "192.168.1.11",
+ "comment": "Example host",
+ "cluster": _ref("clusters", _CLUSTER, name="Default"),
+ },
+ "disk": {
+ "name": "example-disk",
+ "description": "Example virtual disk",
+ "provisioned_size": 10737418240,
+ "format": "cow",
+ "sparse": True,
+ "storage_domains": {
+ "storage_domain": [_ref("storagedomains", _SD, name="data1")],
+ },
+ },
+ # Inline disk create — seed disk is already attached to lab-vm-01.
+ "disk_attachment": {
+ "interface": "virtio_scsi",
+ "bootable": False,
+ "active": True,
+ "disk": {
+ "name": "example-attached-disk",
+ "provisioned_size": 10737418240,
+ "format": "cow",
+ "sparse": True,
+ "storage_domains": {
+ "storage_domain": [_ref("storagedomains", _SD, name="data1")],
+ },
+ },
+ },
+ "nic": {
+ "name": "nic1",
+ "interface": "virtio",
+ "linked": True,
+ "plugged": True,
+ "vnic_profile": _ref("vnicprofiles", _VNIC, name="ovirtmgmt"),
+ },
+ "network": {
+ "name": "vlan100",
+ "description": "Example VLAN network",
+ "stp": False,
+ "data_center": _ref("datacenters", _DC, name="Default"),
+ "vlan": {"id": 100},
+ },
+ "vnic_profile": {
+ "name": "example-profile",
+ "pass_through": {"mode": "disabled"},
+ "network": _ref("networks", _NET, name="ovirtmgmt"),
+ },
+ "data_center": {
+ "name": "example-dc",
+ "description": "Example data center",
+ "local": False,
+ "version": {"major": 4, "minor": 5},
+ },
+ "cluster": {
+ "name": "example-cluster",
+ "description": "Example cluster",
+ "data_center": _ref("datacenters", _DC, name="Default"),
+ "cpu": {"type": "Intel Conroe Family"},
+ },
+ "storage_domain": {
+ "name": "example-sd",
+ "type": "data",
+ "storage": {
+ "type": "nfs",
+ "address": "nfs.lab.local",
+ "path": "/export/example",
+ },
+ "host": _ref("hosts", _HOST, name="host01"),
+ },
+ "storage_connection": {
+ "type": "nfs",
+ "address": "nfs.lab.local",
+ "path": "/export/example",
+ },
+ "template": {
+ "name": "example-template",
+ "description": "Example template",
+ "vm": _ref("vms", _VM, name="lab-vm-01"),
+ "cluster": _ref("clusters", _CLUSTER, name="Default"),
+ },
+ "snapshot": {
+ "description": "example-snapshot",
+ "persist_memorystate": False,
+ },
+ "tag": {"name": "example-tag", "description": "Example tag"},
+ "bookmark": {"name": "example-bookmark", "value": "Vms: status=up"},
+ "affinity_group": {
+ "name": "example-affinity",
+ "description": "Example affinity group",
+ "enforcing": False,
+ "hosts_rule": {"enabled": True, "positive": True},
+ "vms_rule": {"enabled": True, "positive": True},
+ },
+ "affinity_label": {"name": "example-label"},
+ "permission": {
+ "role": _ref("roles", _ROLE, name="SuperUser"),
+ "user": _ref("users", _USER, name="admin"),
+ },
+ "user": {
+ "user_name": "example@internal",
+ "name": "example",
+ "domain": _ref("domains", _DOMAIN, name="internal"),
+ "password": "secret",
+ },
+ "group": {"name": "example-group", "domain": _ref("domains", _DOMAIN, name="internal")},
+ "role": {"name": "ExampleRole", "administrative": False},
+ "quota": {
+ "name": "example-quota",
+ "description": "Example quota",
+ "data_center": _ref("datacenters", _DC, name="Default"),
+ },
+ "vm_pool": {
+ "name": "example-pool",
+ "description": "Example VM pool",
+ "size": 1,
+ "cluster": _ref("clusters", _CLUSTER, name="Default"),
+ "template": _ref("templates", _TEMPLATE, name="Blank"),
+ },
+ "mac_pool": {
+ "name": "example-mac-pool",
+ "allow_duplicates": False,
+ "ranges": {
+ "range": [{"from": "00:1A:4A:16:01:00", "to": "00:1A:4A:16:01:FF"}],
+ },
+ },
+ "cdrom": {"file": {"id": ""}},
+ "graphics_console": {"protocol": "spice"},
+ "host_nic": {
+ "name": "eth1",
+ "boot_protocol": "none",
+ "network": _ref("networks", _NET, name="ovirtmgmt"),
+ },
+ "scheduling_policy": {"name": "example-policy", "description": "Example policy"},
+ "instance_type": {
+ "name": "example-instancetype",
+ "memory": 1073741824,
+ "cpu": {"topology": {"sockets": 1, "cores": 1, "threads": 1}},
+ },
+ "image_transfer": {
+ "disk": _ref("disks", _DISK),
+ "direction": "upload",
+ "format": "raw",
+ },
+ "event": {
+ "description": "Example event",
+ "severity": 1,
+ "origin": "ovirt-api-simulator",
+ },
+ "job": {"description": "Example job"},
+ "step": {"description": "Example step", "type": "VALIDATING"},
+ "icon": {"media_type": "image/png", "data": ""},
+ "file": {"name": "example.iso"},
+ "cluster_level": {"id": "4.5"},
+ "operating_system": {"name": "other"},
+ "domain": {"name": "example.local"},
+ "external_host_provider": {
+ "name": "example-foreman",
+ "url": "https://foreman.example.local",
+ "username": "admin",
+ "password": "secret",
+ },
+ "openstack_image_provider": {
+ "name": "example-glance",
+ "url": "https://glance.example.local:9292",
+ "username": "admin",
+ "password": "secret",
+ "authentication_url": "https://keystone.example.local:5000/v3",
+ "tenant_name": "admin",
+ },
+ "openstack_network_provider": {
+ "name": "example-neutron",
+ "url": "https://neutron.example.local:9696",
+ "username": "admin",
+ "password": "secret",
+ "authentication_url": "https://keystone.example.local:5000/v3",
+ "tenant_name": "admin",
+ "plugin_type": "open_vswitch",
+ "type": "external",
+ },
+ "openstack_volume_provider": {
+ "name": "example-cinder",
+ "url": "https://cinder.example.local:8776/v3",
+ "username": "admin",
+ "password": "secret",
+ "authentication_url": "https://keystone.example.local:5000/v3",
+ "tenant_name": "admin",
+ },
+ "network_filter": {"name": "example-filter"},
+ "engine_option": {"name": "ExampleOption", "value": "true"},
+ "katello_erratum": {"id": "example-erratum"},
+ "statistic": {"name": "example.stat", "type": "GAUGE", "unit": "NONE"},
+ "scheduling_policy_unit": {"name": "example-unit", "type": "filter"},
+ }
+
+
+def _action_name(path: str) -> str:
+ return path.rstrip("/").rsplit("/", 1)[-1].lower()
+
+
+def _action_body(path: str) -> dict[str, Any]:
+ """Real Engine actions use a root ``action`` element."""
+
+ name = _action_name(path)
+ action: dict[str, Any] = {}
+ if name == "clone":
+ action["vm"] = {"name": "example-vm-clone"}
+ elif name == "migrate":
+ action["host"] = _ref("hosts", _HOST, name="host01")
+ elif name in {"move", "copy"}:
+ action["storage_domain"] = _ref("storagedomains", _SD, name="data1")
+ elif name == "export":
+ action["storage_domain"] = _ref("storagedomains", _SD, name="data1")
+ action["exclusive"] = False
+ elif name == "import":
+ action["cluster"] = _ref("clusters", _CLUSTER, name="Default")
+ action["storage_domain"] = _ref("storagedomains", _SD, name="data1")
+ elif name == "attach":
+ action["disk"] = _ref("disks", _DISK)
+ elif name == "detach":
+ action["detach_only"] = True
+ elif name in {"start", "stop", "shutdown", "reboot", "suspend", "activate", "deactivate"}:
+ action["async"] = True
+ elif name == "ticket":
+ action["ticket"] = {"value": ""}
+ elif name == "preview_snapshot":
+ action["restore_memory"] = False
+ return {"action": action}
+
+
+def _generic_entity(element: str) -> dict[str, Any]:
+ return {
+ "name": f"example-{element.replace('_', '-')}",
+ "description": f"Example {element.replace('_', ' ')}",
+ }
+
+
+def body_example_for(
+ *,
+ method: str,
+ kind: str,
+ element: str,
+ path: str,
+) -> dict[str, Any] | None:
+ """Return a full JSON request body example, or ``None`` when no body is used."""
+
+ method_u = method.upper()
+ kind_l = (kind or "").lower()
+ element_l = (element or "").strip()
+ if method_u not in {"POST", "PUT"}:
+ return None
+ if kind_l == "action":
+ return _action_body(path)
+ if kind_l not in {"collection", "item"}:
+ return None
+ if not element_l:
+ return None
+ bodies = _entity_bodies()
+ inner = dict(bodies.get(element_l) or _generic_entity(element_l))
+ if method_u == "PUT":
+ # Partial update: avoid renaming path-param seed entities via console Try-it.
+ inner.pop("name", None)
+ if "description" in inner or element_l not in {"cdrom", "graphics_console", "permission"}:
+ inner["description"] = f"Updated {element_l.replace('_', ' ')}"
+ if element_l == "vm" and "memory" in inner:
+ inner["memory"] = 2147483648
+ if element_l == "disk" and "provisioned_size" in inner:
+ inner["provisioned_size"] = 21474836480
+ return _wrap(element_l, inner)
diff --git a/app/web/ovirt_catalog.py b/app/web/ovirt_catalog.py
index f95da0d..f170282 100644
--- a/app/web/ovirt_catalog.py
+++ b/app/web/ovirt_catalog.py
@@ -11,30 +11,42 @@ from app.ovirt.contract_loader import (
load_series_pack,
series_for_major,
)
+from app.ovirt.ids import stable_id
+from app.web.ovirt_body_examples import body_example_for
_PATH_PARAM = re.compile(r"\{([^{}]+)\}")
+# Prefer minimal-seed UUIDs so console Try-it requests resolve against `make seed`.
_PATH_PARAM_EXAMPLES: dict[str, object] = {
- "vm": "vm-001",
- "vmId": "00000000-0000-0000-0000-000000000001",
- "host": "host-01",
- "hostId": "00000000-0000-0000-0000-000000000011",
+ "vm": "lab-vm-01",
+ "vm_id": str(stable_id("vm", "lab-vm-01")),
+ "vmId": str(stable_id("vm", "lab-vm-01")),
+ "host": "host01",
+ "host_id": str(stable_id("host", "host01")),
+ "hostId": str(stable_id("host", "host01")),
"cluster": "Default",
- "clusterId": "00000000-0000-0000-0000-000000000021",
+ "cluster_id": str(stable_id("cluster", "Default")),
+ "clusterId": str(stable_id("cluster", "Default")),
+ "datacenter_id": str(stable_id("dc", "Default")),
"dataCenter": "Default",
- "dataCenterId": "00000000-0000-0000-0000-000000000031",
- "disk": "disk-001",
- "diskId": "00000000-0000-0000-0000-000000000041",
+ "dataCenterId": str(stable_id("dc", "Default")),
+ "disk": "lab-vm-01-disk",
+ "disk_id": str(stable_id("disk", "lab-vm-01")),
+ "diskId": str(stable_id("disk", "lab-vm-01")),
"network": "ovirtmgmt",
- "networkId": "00000000-0000-0000-0000-000000000051",
- "storageDomain": "data",
- "storageDomainId": "00000000-0000-0000-0000-000000000061",
+ "network_id": str(stable_id("net", "ovirtmgmt")),
+ "networkId": str(stable_id("net", "ovirtmgmt")),
+ "storagedomain_id": str(stable_id("sd", "data1")),
+ "storageDomain": "data1",
+ "storageDomainId": str(stable_id("sd", "data1")),
"template": "Blank",
- "templateId": "00000000-0000-0000-0000-000000000071",
+ "template_id": str(stable_id("template", "Blank")),
+ "templateId": str(stable_id("template", "Blank")),
"user": "admin@internal",
- "userId": "00000000-0000-0000-0000-000000000081",
+ "user_id": str(stable_id("user", "admin")),
+ "userId": str(stable_id("user", "admin")),
"jobId": "00000000-0000-0000-0000-000000000091",
- "id": "00000000-0000-0000-0000-000000000001",
+ "id": str(stable_id("vm", "lab-vm-01")),
}
@@ -43,6 +55,65 @@ def path_param_example(name: str) -> object | None:
return _PATH_PARAM_EXAMPLES.get(name)
+
+def _body_fields_from_example(
+ body_example: dict[str, Any] | None, *, element: str
+) -> list[dict[str, Any]]:
+ """PARAM inputs derived from body_example, including nested scalar paths."""
+
+ if not isinstance(body_example, dict) or not body_example:
+ return []
+ inner: Any = body_example
+ if (
+ element
+ and element in body_example
+ and isinstance(body_example[element], dict)
+ ):
+ inner = body_example[element]
+ elif len(body_example) == 1:
+ only = next(iter(body_example.values()))
+ if isinstance(only, dict):
+ inner = only
+ if not isinstance(inner, dict):
+ return []
+
+ fields: list[dict[str, Any]] = []
+
+ def _leaf_type(value: Any) -> str:
+ if isinstance(value, bool):
+ return "boolean"
+ if isinstance(value, int) and not isinstance(value, bool):
+ return "integer"
+ if isinstance(value, float):
+ return "number"
+ return "string"
+
+ def _walk(prefix: str, value: Any) -> None:
+ if isinstance(value, dict):
+ for key, child in value.items():
+ path = f"{prefix}.{key}" if prefix else str(key)
+ _walk(path, child)
+ return
+ if isinstance(value, list):
+ for index, child in enumerate(value):
+ path = f"{prefix}.{index}" if prefix else str(index)
+ _walk(path, child)
+ return
+ desc = f"{element}.{prefix}" if element else prefix
+ fields.append(
+ {
+ "name": prefix,
+ "type": _leaf_type(value),
+ "description": desc,
+ "optional": True,
+ "enum": [],
+ "example": value,
+ }
+ )
+
+ _walk("", inner)
+ return fields
+
_SERIES_LABELS = {
"3.0": "Engine 3.0",
"3.1": "Engine 3.1",
@@ -146,18 +217,16 @@ def ovirt_method_payload(
}
for name in path_params
]
- body_fields: list[dict[str, Any]] = []
- if op.method in {"POST", "PUT"} and op.kind in {"collection", "item", "action"}:
- body_fields.append(
- {
- "name": op.element,
- "type": "object",
- "description": f"{op.element} payload (XML or JSON)",
- "optional": op.kind == "action",
- "enum": [],
- "example": {op.element: {"name": "example"}},
- }
- )
+ # Full Engine-shaped JSON lives in body_example (root-wrapped entity / action).
+ # PARAM drawer flattens nested scalars from that example (dotted paths).
+ body_example = body_example_for(
+ method=op.method,
+ kind=op.kind,
+ element=op.element,
+ path=op.path,
+ )
+ # Scalar fields for the PARAMS drawer; full nested JSON stays in body_example.
+ body_fields = _body_fields_from_example(body_example, element=op.element or "")
query_fields = []
if op.search:
query_fields.extend(
@@ -200,6 +269,7 @@ def ovirt_method_payload(
"path_fields": path_fields,
"query_fields": query_fields,
"body_fields": body_fields,
+ "body_example": body_example,
"runtime_version": runtime_version,
}
return {
@@ -214,6 +284,7 @@ def ovirt_method_payload(
"path_fields": [],
"query_fields": [],
"body_fields": [],
+ "body_example": None,
"runtime_version": runtime_version,
}
diff --git a/app/web/routes.py b/app/web/routes.py
index 14040e0..63c623e 100644
--- a/app/web/routes.py
+++ b/app/web/routes.py
@@ -10,7 +10,7 @@ from fastapi.responses import HTMLResponse, JSONResponse
from app.db.pool import AsyncpgDatabase
from app.dependencies import get_database
-from app.ovirt.demo_datacenter import seed_ovirt_demo
+from app.ovirt.demo_datacenter import CLUSTER_SIZES, normalize_cluster_size, seed_ovirt_demo
from app.ovirt.seed import clear_ovirt_state, ovirt_demo_summary, seed_ovirt
from app.web.assets import console_html
@@ -175,13 +175,29 @@ async def ui_ovirt_contracts_activate(request: Request) -> JSONResponse:
@router.post("/ui/api/demo/load", include_in_schema=False)
async def ui_demo_load(request: Request) -> JSONResponse:
- """Load synthetic oVirt datacenter (~1000 VMs + full inventory)."""
+ """Load a sized demo cluster: small (3h/50vm), large (10h/1000vm), big (30h/2000vm)."""
+
+ size_raw = request.query_params.get("size") or request.query_params.get("profile")
+ if size_raw is None:
+ try:
+ body = await request.json()
+ except Exception:
+ body = {}
+ if isinstance(body, dict):
+ size_raw = body.get("size") or body.get("profile")
+ try:
+ size = normalize_cluster_size(str(size_raw) if size_raw else "large")
+ except ValueError as error:
+ raise HTTPException(
+ status_code=400,
+ detail=f"{error}; sizes: {', '.join(sorted(CLUSTER_SIZES))}",
+ ) from error
pool = _database_pool(request)
try:
async with pool.acquire() as connection:
async with connection.transaction():
- result = await seed_ovirt_demo(connection)
+ result = await seed_ovirt_demo(connection, size=size)
summary = await ovirt_demo_summary(connection)
except Exception as error:
raise HTTPException(
diff --git a/docs/getting-started.md b/docs/getting-started.md
index a8dcb50..3010269 100644
--- a/docs/getting-started.md
+++ b/docs/getting-started.md
@@ -66,6 +66,9 @@ curl -skf https://127.0.0.1/health/ready
curl -sf http://127.0.0.1:5000/health/live
```
+Open the console at [http://127.0.0.1:5000/](http://127.0.0.1:5000/) — see
+[Web UI](web-ui.md) for screenshots of Try-it, catalog, and data drawers.
+
`/health/ready` returns HTTP 503 until PostgreSQL is reachable **and** the
latest packaged migration is applied.
diff --git a/docs/images/web-ui/api-catalog.png b/docs/images/web-ui/api-catalog.png
new file mode 100644
index 0000000..0615282
Binary files /dev/null and b/docs/images/web-ui/api-catalog.png differ
diff --git a/docs/images/web-ui/authentication.png b/docs/images/web-ui/authentication.png
new file mode 100644
index 0000000..fb85975
Binary files /dev/null and b/docs/images/web-ui/authentication.png differ
diff --git a/docs/images/web-ui/console.png b/docs/images/web-ui/console.png
new file mode 100644
index 0000000..1b9dadf
Binary files /dev/null and b/docs/images/web-ui/console.png differ
diff --git a/docs/images/web-ui/data.png b/docs/images/web-ui/data.png
new file mode 100644
index 0000000..f2b1be3
Binary files /dev/null and b/docs/images/web-ui/data.png differ
diff --git a/docs/images/web-ui/endpoints.png b/docs/images/web-ui/endpoints.png
new file mode 100644
index 0000000..cfcd64b
Binary files /dev/null and b/docs/images/web-ui/endpoints.png differ
diff --git a/docs/images/web-ui/environment.png b/docs/images/web-ui/environment.png
new file mode 100644
index 0000000..80ac622
Binary files /dev/null and b/docs/images/web-ui/environment.png differ
diff --git a/docs/images/web-ui/help-compatibility.png b/docs/images/web-ui/help-compatibility.png
new file mode 100644
index 0000000..7edc2f1
Binary files /dev/null and b/docs/images/web-ui/help-compatibility.png differ
diff --git a/docs/images/web-ui/history.png b/docs/images/web-ui/history.png
new file mode 100644
index 0000000..7cdc89d
Binary files /dev/null and b/docs/images/web-ui/history.png differ
diff --git a/docs/images/web-ui/request-body.png b/docs/images/web-ui/request-body.png
new file mode 100644
index 0000000..955477c
Binary files /dev/null and b/docs/images/web-ui/request-body.png differ
diff --git a/docs/images/web-ui/request-params.png b/docs/images/web-ui/request-params.png
new file mode 100644
index 0000000..547117b
Binary files /dev/null and b/docs/images/web-ui/request-params.png differ
diff --git a/docs/operations.md b/docs/operations.md
index d4f310f..0d3e15e 100644
--- a/docs/operations.md
+++ b/docs/operations.md
@@ -46,7 +46,7 @@ make seed-demo
OVIRT_SERIES=4.4 make restart
```
-**Hot-swap** (in-memory, no rebuild) — Web UI Environment → Apply pack, or:
+**Hot-swap** (in-memory, no rebuild) — Web UI **API catalog** → **Apply as runtime**, or:
```bash
curl -s http://127.0.0.1:5000/ui/api/ovirt/contracts/activate \
diff --git a/docs/ru/getting-started.md b/docs/ru/getting-started.md
index 0f3645d..7876470 100644
--- a/docs/ru/getting-started.md
+++ b/docs/ru/getting-started.md
@@ -66,6 +66,9 @@ curl -skf https://127.0.0.1/health/ready
curl -sf http://127.0.0.1:5000/health/live
```
+Консоль: [http://127.0.0.1:5000/](http://127.0.0.1:5000/) — скриншоты Try-it,
+каталога и ящиков Data см. в [Web UI](web-ui.md).
+
`/health/ready` возвращает HTTP 503, пока PostgreSQL недоступен **или** не
применена последняя упакованная миграция.
diff --git a/docs/ru/operations.md b/docs/ru/operations.md
index 329fa89..115d129 100644
--- a/docs/ru/operations.md
+++ b/docs/ru/operations.md
@@ -46,7 +46,7 @@ make seed-demo
OVIRT_SERIES=4.4 make restart
```
-**Hot-swap** (in-memory, без пересборки) — Web UI Environment → Apply pack, или:
+**Hot-swap** (in-memory, без пересборки) — Web UI **API catalog** → **Apply as runtime**, или:
```bash
curl -s http://127.0.0.1:5000/ui/api/ovirt/contracts/activate \
diff --git a/docs/ru/seed-profiles.md b/docs/ru/seed-profiles.md
index 2c30569..739dcc0 100644
--- a/docs/ru/seed-profiles.md
+++ b/docs/ru/seed-profiles.md
@@ -4,38 +4,38 @@
| Профиль | Как загрузить | Содержимое |
|---|---|---|
-| `minimal` | Startup симулятора (если БД ещё не `demo`) / `make seed` / `python -m app.ovirt.seed_cli --profile minimal` / Helm seed Job | 1 datacenter, 1 cluster, 1 host, Blank template, 4 пользователя, небольшой sample инвентаря |
-| `demo` | `make seed-demo` / ящик Data в UI / Helm `seed.profile=demo` / `--profile demo` | ~1000 ВМ, multi-host DC, сети, storage domains, диски, nested samples |
+| `minimal` | Старт (если БД не sized-demo) / `make seed` / `--profile minimal` | 1 DC, 1 cluster, 1 host, Blank, 4 пользователя |
+| `small` | `make seed-small` / DATA → **Load small** / `--profile small` | **3 host · 50 ВМ** · 1 DC · 1 cluster · 2 сети · 2 SD |
+| `large` | `make seed-large` / DATA → **Load large** / `--profile large` | **10 host · 1000 ВМ** · 2 DC · 2 cluster · пропорциональный инвентарь |
+| `big` | `make seed-big` / DATA → **Load big** / `--profile big` | **30 host · 2000 ВМ** · 3 DC · 6 cluster · больше tags/events/jobs |
+| `demo` | `make seed-demo` (alias) / `--profile demo` | То же, что **`large`** (старое имя) |
-В Compose lifespan FastAPI загружает **`minimal`**, если БД пуста или не
-помечена как `demo`. Для большого профиля — `make seed-demo` (или ящик Data в
-UI). Helm дополнительно может запускать seed Job (`seed.enabled`).
+Sized-demo масштабируют DC, clusters, hosts, VMs, сети, storage domains,
+templates, tags, events, jobs и nested samples вместе. Lifespan сохраняет
+`small` / `large` / `big` / `demo` при рестарте.
-Пароль для всех пользователей: **`secret`**. Домен: **`internal`**.
-
-Principals: `admin@internal`, `ops@internal`, `developer@internal`,
-`demo@internal`.
+Пароль всех пользователей: **`secret`**. Домен: **`internal`**.
## CLI
```bash
make seed
-make seed-demo
-
-# эквивалент
-docker compose run --rm --entrypoint python simulator \
- -m app.ovirt.seed_cli --profile demo
+make seed-small
+make seed-large # или: make seed-demo
+make seed-big
```
+## UI
+
+Ящик **DATA** → **Load small** / **Load large** / **Load big**, либо
+**Reset to minimal**.
+
+API: `POST /ui/api/demo/load?size=small|large|big`
+
## Helm
```yaml
seed:
enabled: true
- profile: demo # или minimal
+ profile: large # minimal | small | large | big | demo
```
-
-## Поведение
-
-Оба профиля **очищают** (truncate) лабораторные таблицы oVirt и загружают данные
-заново. `demo` — для плотности и nested GET; `minimal` — для быстрого CI.
diff --git a/docs/ru/web-ui.md b/docs/ru/web-ui.md
index 371ca2c..1bae528 100644
--- a/docs/ru/web-ui.md
+++ b/docs/ru/web-ui.md
@@ -2,32 +2,74 @@
# Web UI
-URL консоли (Compose по умолчанию): [http://127.0.0.1:5000/](http://127.0.0.1:5000/)
+Интерактивная консоль: обзор операций контракта Engine, лабораторные токены,
+Try-it запросы и управление seed-данными.
-UX ящиков совпадает с другими лабораторными симуляторами этого семейства:
+URL по умолчанию (Compose): [http://127.0.0.1:5000/](http://127.0.0.1:5000/)
+(При `make up-local` — локальный UI-порт из `.env`, например `6080` / `7080`.)
+
+
+
+## Рабочая область
| Область | Назначение |
|---|---|
-| Auth | Выдача лабораторных токенов / показ principal |
-| API catalog | Обзор операций контракта активного series |
-| Coverage | Сводка покрытия pack / handlers |
-| Help | Краткие заметки оператора |
-| Data | Reseed `minimal` / `demo` |
-| Environment | Активный series, runtime-подсказки, hot-swap **Apply pack** |
+| Выбор endpoint | Поиск по путям контракта (series pack Engine) |
+| Вкладки методов | `GET` / `POST` / `PUT` / `DELETE` для выбранного пути |
+| Request body | JSON-пример в форме Engine для create/update/action |
+| Params | Плоские path/body-поля для быстрых правок |
+| Response | Статус + JSON-дерево последнего ответа |
+| History | Недавние Try-it запросы (повтор / восстановление) |
+
+
+
+
+
+
+
+Тела запросов соответствуют соглашению Engine (root-wrapper сущности или
+`action`). В примерах — вложенные ссылки (`cluster`, `template`, CPU topology,
+storage domains) под seed-инвентарь лаборатории, а не однополевой stub.
+
+
+
+## Ящики (drawers)
+
+| Ящик | Назначение |
+|---|---|
+| Authentication | SSO password grant / вставка Bearer-токена |
+| API catalog | Обзор series packs; **Apply as runtime** — hot-swap |
+| Help → Compatibility | Сводка declared / implemented / verified |
+| Data | Reseed `minimal` / `small` / `large` / `big` |
+| Environment | Runtime series + обзор инвентаря datacenter |
+
+
+
+Лабораторные учётки: `admin@internal`, `ops@internal`, `developer@internal`,
+`demo@internal` / `secret`. Scope: `ovirt-app-api`.
+
+
+
+
+
+
+
+
## Hot-swap series
-Из Environment (или UI API):
+Из **API catalog** → **Apply as runtime** (или UI API):
- `POST /ui/api/ovirt/contracts/activate` с `{"series":"4.4"}`
- `POST /ui/api/contract/apply?major=N`
Перемонтирует in-memory контрактные маршруты без пересборки образа. Рестарт
-процесса возвращает cold-start значение `OVIRT_SERIES`. См.
-[Версии API](api-versions.md).
+процесса возвращает cold-start `OVIRT_SERIES`. См. [Версии API](api-versions.md).
-Брендинг: oVirt blue `#0076B6` и charcoal `#1D2226`.
+## Заметки
-UI обращается к тому же процессу симулятора, что и Engine API; отличается только
-опубликованный listener ([ports.md](ports.md)). Схема OpenAPI:
-[http://127.0.0.1:5000/docs](http://127.0.0.1:5000/docs) (также на порту Engine).
+- Брендинг: oVirt blue `#0076B6` и charcoal `#1D2226`.
+- UI ходит в тот же процесс симулятора, что и Engine API; отличается только
+ опубликованный listener ([порты](ports.md)).
+- OpenAPI: [http://127.0.0.1:5000/docs](http://127.0.0.1:5000/docs)
+ (также на HTTPS-порту Engine).
diff --git a/docs/seed-profiles.md b/docs/seed-profiles.md
index a5cbc03..c8ed6fc 100644
--- a/docs/seed-profiles.md
+++ b/docs/seed-profiles.md
@@ -4,12 +4,16 @@
| Profile | How to load | Contents |
|---|---|---|
-| `minimal` | Simulator startup (if DB is not already `demo`) / `make seed` / `python -m app.ovirt.seed_cli --profile minimal` / Helm seed Job | 1 datacenter, 1 cluster, 1 host, Blank template, 4 users, small inventory sample |
-| `demo` | `make seed-demo` / UI Data drawer / Helm `seed.profile=demo` / `--profile demo` | ~1000 VMs, multi-host DC, networks, storage domains, disks, nested samples |
+| `minimal` | Startup (if DB is not a sized demo) / `make seed` / `--profile minimal` | 1 DC, 1 cluster, 1 host, Blank template, 4 users |
+| `small` | `make seed-small` / DATA → **Load small** / `--profile small` | **3 hosts · 50 VMs** · 1 DC · 1 cluster · 2 networks · 2 SD |
+| `large` | `make seed-large` / DATA → **Load large** / `--profile large` | **10 hosts · 1000 VMs** · 2 DC · 2 clusters · proportional inventory |
+| `big` | `make seed-big` / DATA → **Load big** / `--profile big` | **30 hosts · 2000 VMs** · 3 DC · 6 clusters · denser tags/events/jobs |
+| `demo` | `make seed-demo` (alias) / `--profile demo` | Same as **`large`** (legacy name) |
-On Compose, the FastAPI lifespan loads **`minimal`** automatically when the DB
-is empty or not marked as `demo`. Use `make seed-demo` (or the UI Data drawer)
-for the large profile. Helm can also run a seed Job (`seed.enabled`).
+Sized demos scale datacenters, clusters, hosts, VMs, networks, storage domains,
+templates, tags, events, jobs, and nested samples together. On Compose, lifespan
+keeps any of `small` / `large` / `big` / `demo` across restarts (does not wipe to
+minimal).
Password for all users: **`secret`**. Domain: **`internal`**.
@@ -20,22 +24,30 @@ Principals: `admin@internal`, `ops@internal`, `developer@internal`,
```bash
make seed
-make seed-demo
+make seed-small
+make seed-large # or: make seed-demo
+make seed-big
-# equivalent
docker compose run --rm --entrypoint python simulator \
- -m app.ovirt.seed_cli --profile demo
+ -m app.ovirt.seed_cli --profile large
```
+## UI
+
+Open the **DATA** drawer → **Load small** / **Load large** / **Load big**, or
+**Reset to minimal**.
+
+API: `POST /ui/api/demo/load?size=small|large|big`
+
## Helm
```yaml
seed:
enabled: true
- profile: demo # or minimal
+ profile: large # minimal | small | large | big | demo
```
## Behaviour
-Both profiles **truncate** oVirt lab tables then reload. Prefer `demo` for
-density and nested GET probes; `minimal` for fast CI.
+All profiles **truncate** oVirt lab tables then reload. Prefer `large`/`big` for
+density; `minimal` / `small` for fast CI and light labs.
diff --git a/docs/web-ui.md b/docs/web-ui.md
index 0d321c0..82a7e97 100644
--- a/docs/web-ui.md
+++ b/docs/web-ui.md
@@ -2,22 +2,63 @@
# Web UI
-Console URL (Compose default): [http://127.0.0.1:5000/](http://127.0.0.1:5000/)
+Interactive console for browsing Engine contract operations, issuing lab tokens,
+sending Try-it requests, and managing seed data.
-Drawer UX matches the other laboratory simulators in this family:
+Compose default URL: [http://127.0.0.1:5000/](http://127.0.0.1:5000/)
+(With `make up-local`, use the local UI port from your `.env`, e.g. `6080` / `7080`.)
+
+
+
+## Workspace
| Area | Purpose |
|---|---|
-| Auth | Issue lab tokens / show principal |
-| API catalog | Browse contract operations for the active series |
-| Coverage | Pack / handler coverage summary |
-| Help | Short operator notes |
-| Data | Reseed `minimal` / `demo` |
-| Environment | Active series, runtime hints, **Apply pack** hot-swap |
+| Endpoint picker | Searchable catalog of contract paths (Engine series pack) |
+| Method tabs | `GET` / `POST` / `PUT` / `DELETE` for the selected path |
+| Request body | Engine-shaped JSON sample for create/update/action |
+| Params | Flattened path + body fields for quick edits |
+| Response | Status + JSON tree for the last call |
+| History | Recent Try-it requests (replay / restore) |
+
+
+
+
+
+
+
+Request bodies follow the real Engine convention (root-wrapped entity or
+`action`). Samples include nested refs (`cluster`, `template`, CPU topology,
+storage domains) aligned with the seeded lab inventory — not a one-field stub.
+
+
+
+## Drawers
+
+| Drawer | Purpose |
+|---|---|
+| Authentication | Engine SSO password grant / paste Bearer token |
+| API catalog | Browse series packs; **Apply as runtime** hot-swap |
+| Help → Compatibility | Declared / implemented / verified surface summary |
+| Data | Reseed `minimal` / `small` / `large` / `big` |
+| Environment | Runtime series + datacenter inventory overview |
+
+
+
+Default lab principals: `admin@internal`, `ops@internal`, `developer@internal`,
+`demo@internal` / `secret`. Scope: `ovirt-app-api`.
+
+
+
+
+
+
+
+
## Series hot-swap
-From Environment (or UI API):
+From **API catalog** → **Apply as runtime** (or UI API):
- `POST /ui/api/ovirt/contracts/activate` with `{"series":"4.4"}`
- `POST /ui/api/contract/apply?major=N`
@@ -26,8 +67,10 @@ This remounts the in-memory contract routes without rebuilding the image. A
process restart restores the cold-start `OVIRT_SERIES` value. See
[API versions](api-versions.md).
-Branding uses oVirt blue `#0076B6` and charcoal `#1D2226`.
+## Notes
-The UI talks to the same simulator process as the Engine API; only the published
-listener differs ([ports.md](ports.md)). OpenAPI schema:
-[http://127.0.0.1:5000/docs](http://127.0.0.1:5000/docs) (also on Engine port).
+- Branding uses oVirt blue `#0076B6` and charcoal `#1D2226`.
+- The UI talks to the same simulator process as the Engine API; only the
+ published listener differs ([ports.md](ports.md)).
+- OpenAPI schema: [http://127.0.0.1:5000/docs](http://127.0.0.1:5000/docs)
+ (also available on the Engine HTTPS port).
diff --git a/pulumi-tests/README.md b/pulumi-tests/README.md
index 3b5ef8b..41c86a8 100644
--- a/pulumi-tests/README.md
+++ b/pulumi-tests/README.md
@@ -2,10 +2,10 @@
# oVirt Pulumi contract-coverage lab
-Pulumi Automation API suite that exercises **every operation** declared in
-`contracts/ovirt/
/api.json` across **all Engine series packs**, plus a
-**synthetic HEAD** request for each GET path (contracts omit HEAD; the Engine
-accepts it).
+**100% coverage** here means the **HTTP contract matrix**: every operation
+declared in `contracts/ovirt//api.json` for **all Engine series packs**,
+plus a **synthetic HEAD** for each GET path (contracts omit HEAD; the Engine
+accepts it). It is **not** a count of Pulumi provider resources.
| Series | Ops (approx.) |
|--------|--------------:|
@@ -16,10 +16,22 @@ make test-pulumi-smoke # 3.6 + 4.5 sample (fast)
make pulumi-tests # full matrix (alias: make test-pulumi)
```
+Layer B (optional): provider lifecycle smoke only — do not treat it as API
+parity.
+
Reports (written under `reports/`):
-- `pulumi-contract-coverage.html` — human-readable summary (includes methods histogram)
-- `pulumi-contract-coverage.json` — machine-readable results
+- `pulumi-contract-coverage.html` — human-readable summary (method histogram
+ includes GET/PUT/POST/DELETE/HEAD)
+- `pulumi-contract-coverage.json` — machine-readable results + `coverage`
+ (`probed/declared`, `critical`)
+
+Pass line example:
+
+```text
+COVERAGE 9150/9150 (critical=0)
+METHODS {"DELETE":1146,"GET":2314,"HEAD":2314,"POST":2230,"PUT":1146}
+```
Optional filters:
@@ -29,11 +41,14 @@ OVIRT_METHODS_FILTER=GET make pulumi-tests
SMOKE_ONLY=1 make test-pulumi-smoke
```
-All suites run **only in Docker**. Pass criteria:
+All suites run **only in Docker** (lab compose seeds **minimal** inventory).
+Pass criteria:
- The Engine route is reachable and returns a handled status (`200`/`201`/`202`/`204`,
`400`/`403`/`404`/`405`/`409`/`415`/`422`/`501`) — **not** `401` (the suite
re-authenticates after each series unload) and not a transport/`5xx` failure.
- For `200`/`201`/`202` the response body must be non-empty (HEAD exempt).
-- Full runs must exercise **GET, POST, PUT, DELETE, and HEAD**; any failures or
- missing methods fail the suite.
+- Successful **collection** GETs must return a **non-empty** list with `id`
+ (empty `[]` is a seed/`ov_api_objects` gap — fix data, do not skip).
+- Full runs must exercise **GET, POST, PUT, DELETE, and HEAD**; any failures,
+ missing methods, or `probed != declared` fail the suite (`critical=0` required).
diff --git a/pulumi-tests/README.ru.md b/pulumi-tests/README.ru.md
index 8640528..8ff5fc3 100644
--- a/pulumi-tests/README.ru.md
+++ b/pulumi-tests/README.ru.md
@@ -2,10 +2,10 @@
# Лаборатория Pulumi: покрытие контрактов oVirt
-Suite на Pulumi Automation API, который вызывает **каждую операцию** из
+**100% coverage** здесь — это **HTTP contract matrix**: каждая операция из
`contracts/ovirt//api.json` для **всех series packs** Engine, плюс
**синтетический HEAD** для каждого GET-пути (в contracts нет HEAD; Engine его
-принимает).
+принимает). Это **не** число ресурсов Pulumi provider.
| Series | Операций (примерно) |
|--------|--------------------:|
@@ -16,10 +16,22 @@ make test-pulumi-smoke # выборка 3.6 + 4.5 (быстро)
make pulumi-tests # полная матрица (alias: make test-pulumi)
```
+Layer B (опционально): только smoke lifecycle провайдера — не выдавать за
+полноту API.
+
Отчёты (в `reports/`):
-- `pulumi-contract-coverage.html` — сводка для человека (включая гистограмму методов)
-- `pulumi-contract-coverage.json` — машиночитаемый результат
+- `pulumi-contract-coverage.html` — сводка (гистограмма методов:
+ GET/PUT/POST/DELETE/HEAD)
+- `pulumi-contract-coverage.json` — результат + `coverage`
+ (`probed/declared`, `critical`)
+
+Пример pass-строки:
+
+```text
+COVERAGE 9150/9150 (critical=0)
+METHODS {"DELETE":1146,"GET":2314,"HEAD":2314,"POST":2230,"PUT":1146}
+```
Фильтры:
@@ -29,11 +41,14 @@ OVIRT_METHODS_FILTER=GET make pulumi-tests
SMOKE_ONLY=1 make test-pulumi-smoke
```
-Все suites — **только в Docker**. Критерии pass:
+Все suites — **только в Docker** (lab compose сидит **minimal** seed).
+Критерии pass:
- Маршрут Engine достижим и возвращает обработанный статус (`200`/`201`/`202`/`204`,
`400`/`403`/`404`/`405`/`409`/`415`/`422`/`501`) — **не** `401` (после unload
каждой series suite заново логинится) и не транспортную / `5xx` ошибку.
- Для `200`/`201`/`202` тело ответа должно быть непустым (HEAD исключён).
-- Полный прогон должен покрыть **GET, POST, PUT, DELETE и HEAD**; любые failures
- или отсутствующие методы валят suite.
+- Успешные **collection** GET должны возвращать **непустой** список с `id`
+ (пустой `[]` — дыра seed/`ov_api_objects`, чинить данные, не skip).
+- Полный прогон должен покрыть **GET, POST, PUT, DELETE и HEAD**; любые failures,
+ отсутствующие методы или `probed != declared` валят suite (`critical=0`).
diff --git a/pulumi-tests/docker-compose.yml b/pulumi-tests/docker-compose.yml
index da4c69d..d685032 100644
--- a/pulumi-tests/docker-compose.yml
+++ b/pulumi-tests/docker-compose.yml
@@ -51,7 +51,7 @@ services:
depends_on:
simulator:
condition: service_healthy
- entrypoint: ["python", "-m", "app.ovirt.seed_cli", "--profile", "demo"]
+ entrypoint: ["python", "-m", "app.ovirt.seed_cli", "--profile", "minimal"]
api-gateway:
image: nginx:1.28.0-alpine
diff --git a/pulumi-tests/pulumi/coverage/executor.py b/pulumi-tests/pulumi/coverage/executor.py
index e2ff9c0..9a3efad 100644
--- a/pulumi-tests/pulumi/coverage/executor.py
+++ b/pulumi-tests/pulumi/coverage/executor.py
@@ -42,7 +42,7 @@ def _value_empty(value: Any) -> bool:
return value is None or value == "" or value == [] or value == {}
-def _payload_nonempty(response: Any, *, method: str) -> tuple[bool, str]:
+def _payload_nonempty(response: Any, *, method: str, kind: str = "") -> tuple[bool, str]:
"""Require non-empty response data for successful body-bearing statuses."""
# HEAD has no body; DELETE often returns 200 with an empty body (Engine-style).
if method in {"HEAD", "DELETE"}:
@@ -61,10 +61,17 @@ def _payload_nonempty(response: Any, *, method: str) -> tuple[bool, str]:
return False, "null JSON body"
if isinstance(data, (list, dict)) and len(data) == 0:
return False, "empty JSON body"
+ # Declared collection GETs must return durable lab samples (not []).
+ if method == "GET" and kind == "collection" and isinstance(data, dict):
+ for value in data.values():
+ if isinstance(value, list):
+ if len(value) == 0:
+ return False, "empty collection list"
+ first = value[0]
+ if isinstance(first, dict) and not first.get("id"):
+ return False, "collection item missing id"
+ break
if isinstance(data, dict) and all(_value_empty(v) for v in data.values()):
- # Allow Engine empty collections: {"vms": []} has structure but no rows.
- if len(data) == 1 and isinstance(next(iter(data.values())), list):
- return True, ""
return False, "JSON body has only empty fields"
return True, ""
@@ -146,7 +153,47 @@ def synthesize_head_ops(ops: list[dict[str, Any]]) -> list[dict[str, Any]]:
class Inventory:
- """Cache of collection → first entity id for path placeholder expansion."""
+ """Cache of collection → entity ids for path placeholder expansion.
+
+ PUT/DELETE resolve to *disposable* entities created for the op so the
+ minimal seed (lab-vm-01, Default DC/cluster, …) is not wiped before later
+ collection GETs run in contract order.
+ """
+
+ _ELEMENT = {
+ "vms": "vm",
+ "hosts": "host",
+ "clusters": "cluster",
+ "datacenters": "data_center",
+ "networks": "network",
+ "disks": "disk",
+ "templates": "template",
+ "storagedomains": "storage_domain",
+ "storageconnections": "storage_connection",
+ "vnicprofiles": "vnic_profile",
+ "users": "user",
+ "groups": "group",
+ "roles": "role",
+ "tags": "tag",
+ "bookmarks": "bookmark",
+ "affinitylabels": "affinity_label",
+ "instancetypes": "instance_type",
+ "macpools": "mac_pool",
+ "schedulingpolicies": "scheduling_policy",
+ "vmpools": "vm_pool",
+ "permissions": "permission",
+ "domains": "domain",
+ "icons": "icon",
+ "jobs": "job",
+ "events": "event",
+ "nics": "nic",
+ "snapshots": "snapshot",
+ "diskattachments": "disk_attachment",
+ "cdroms": "cdrom",
+ "graphicsconsoles": "graphics_console",
+ "quotas": "quota",
+ "affinitygroups": "affinity_group",
+ }
def __init__(self, client: OVirtClient, version: str) -> None:
self.client = client
@@ -154,8 +201,12 @@ class Inventory:
self._ids: dict[str, str] = {}
self._listed: set[str] = set()
- def id_for(self, collection: str) -> str | None:
+ def id_for(self, collection: str, *, method: str = "GET") -> str | None:
collection = collection.strip("/")
+ if method in {"DELETE", "PUT"}:
+ created = self.create_disposable(collection)
+ if created:
+ return created
if collection in self._ids:
return self._ids[collection]
if collection in self._listed:
@@ -172,7 +223,6 @@ class Inventory:
body = r.json()
except Exception:
return None
- # Engine collections are usually { "": [ {...}, ... ] }
for value in body.values() if isinstance(body, dict) else []:
if isinstance(value, list) and value:
first = value[0]
@@ -184,6 +234,129 @@ class Inventory:
return self._ids[collection]
return None
+ def create_disposable(self, collection: str) -> str | None:
+ """POST a throwaway entity and return its id (best-effort)."""
+
+ element = self._ELEMENT.get(collection) or collection.rstrip("s") or "object"
+ name = f"pulumi-{uuid4().hex[:8]}"
+ payload: dict[str, Any] = {
+ "name": name,
+ "description": "pulumi disposable",
+ }
+ if collection == "clusters":
+ dc = self.id_for("datacenters", method="GET")
+ if dc:
+ payload["data_center"] = {"id": dc}
+ elif collection == "hosts":
+ cl = self.id_for("clusters", method="GET")
+ if cl:
+ payload["cluster"] = {"id": cl}
+ payload["address"] = "127.0.0.1"
+ elif collection == "networks":
+ dc = self.id_for("datacenters", method="GET")
+ if dc:
+ payload["data_center"] = {"id": dc}
+ elif collection == "vms":
+ cl = self.id_for("clusters", method="GET")
+ if cl:
+ payload["cluster"] = {"id": cl}
+ tpl = self.id_for("templates", method="GET")
+ if tpl:
+ payload["template"] = {"id": tpl}
+ elif collection == "disks":
+ sd = self.id_for("storagedomains", method="GET")
+ if sd:
+ payload["storage_domains"] = {"storage_domain": [{"id": sd}]}
+ payload["provisioned_size"] = 1073741824
+ elif collection == "vnicprofiles":
+ net = self.id_for("networks", method="GET")
+ if net:
+ payload["network"] = {"id": net}
+ elif collection == "templates":
+ cl = self.id_for("clusters", method="GET")
+ if cl:
+ payload["cluster"] = {"id": cl}
+ elif collection == "storageconnections":
+ payload = {
+ "type": "nfs",
+ "address": "nfs.pulumi.local",
+ "path": f"/export/{name}",
+ }
+ elif collection == "storagedomains":
+ payload["type"] = "data"
+ payload["storage"] = {
+ "type": "nfs",
+ "address": "nfs.pulumi.local",
+ "path": f"/export/{name}",
+ }
+ elif collection == "users":
+ payload = {
+ "user_name": f"{name}@internal",
+ "name": name,
+ "password": "secret",
+ }
+ domain = self.id_for("domains", method="GET")
+ if domain:
+ payload["domain"] = {"id": domain}
+ elif collection == "bookmarks":
+ payload["value"] = "Vms:"
+
+ path = f"/ovirt-engine/api/{collection}"
+ return self._post_for_id(path, element, payload)
+
+ def create_disposable_at(self, collection_path: str, collection: str) -> str | None:
+ """POST under an already-resolved collection path (nested resources)."""
+
+ element = self._ELEMENT.get(collection) or collection.rstrip("s") or "object"
+ name = f"pulumi-{uuid4().hex[:8]}"
+ payload: dict[str, Any] = {"name": name, "description": "pulumi disposable"}
+ if collection == "snapshots":
+ payload = {"description": name}
+ elif collection == "diskattachments":
+ payload = {
+ "interface": "virtio_scsi",
+ "bootable": False,
+ "active": True,
+ "disk": {
+ "name": f"{name}-disk",
+ "provisioned_size": 1073741824,
+ "format": "cow",
+ },
+ }
+ elif collection == "cdroms":
+ payload = {"file": {"id": ""}}
+ elif collection == "graphicsconsoles":
+ payload = {"protocol": "spice"}
+ elif collection == "nics":
+ payload = {"name": name, "interface": "virtio"}
+ return self._post_for_id(collection_path, element, payload)
+
+ def _post_for_id(
+ self, path: str, element: str, payload: dict[str, Any]
+ ) -> str | None:
+ try:
+ r = self.client.request(
+ "POST",
+ path,
+ headers=self.client.headers(version=self.version),
+ json={element: payload},
+ )
+ except Exception:
+ return None
+ if r.status_code not in {200, 201, 202}:
+ return None
+ try:
+ body = r.json()
+ except Exception:
+ return None
+ entity = body.get(element) if isinstance(body, dict) else None
+ if isinstance(entity, dict) and entity.get("id"):
+ return str(entity["id"])
+ for value in body.values() if isinstance(body, dict) else []:
+ if isinstance(value, dict) and value.get("id"):
+ return str(value["id"])
+ return None
+
def _collection_before_param(parts: list[str], index: int) -> str | None:
# /ovirt-engine/api/vms/{id}/nics/{id} → for first {id} use vms, for second use nics
@@ -195,10 +368,11 @@ def _collection_before_param(parts: list[str], index: int) -> str | None:
return prev
-def resolve_path(template: str, inventory: Inventory) -> tuple[str, bool]:
+def resolve_path(template: str, inventory: Inventory, *, method: str = "GET") -> tuple[str, bool]:
"""Return resolved path and whether every placeholder was satisfied from inventory."""
parts = template.strip("/").split("/")
+ param_indices = [i for i, part in enumerate(parts) if _PATH_PARAM.fullmatch(part)]
resolved: list[str] = []
complete = True
for i, part in enumerate(parts):
@@ -207,7 +381,29 @@ def resolve_path(template: str, inventory: Inventory) -> tuple[str, bool]:
resolved.append(part)
continue
collection = _collection_before_param(parts, i)
- entity_id = inventory.id_for(collection) if collection else None
+ is_leaf = bool(param_indices) and i == param_indices[-1]
+ entity_id = None
+ if collection:
+ if method in {"DELETE", "PUT"} and is_leaf:
+ # Only the leaf id is disposable — parents keep seed inventory.
+ # Never fall back to seed ids for DELETE (would wipe minimal lab).
+ if collection in Inventory._ELEMENT and collection not in {
+ "nics",
+ "snapshots",
+ "diskattachments",
+ "cdroms",
+ "graphicsconsoles",
+ "quotas",
+ "affinitygroups",
+ }:
+ entity_id = inventory.create_disposable(collection)
+ else:
+ parent_path = "/" + "/".join(resolved)
+ entity_id = inventory.create_disposable_at(parent_path, collection)
+ if not entity_id and method == "PUT":
+ entity_id = inventory.id_for(collection, method="GET")
+ else:
+ entity_id = inventory.id_for(collection, method="GET")
if entity_id:
resolved.append(entity_id)
else:
@@ -242,7 +438,7 @@ def execute_operation(
expected = int(op.get("create_status") or op.get("status_code") or 200) if method == "POST" else int(
op.get("status_code") or 200
)
- path, _complete = resolve_path(template, inventory)
+ path, _complete = resolve_path(template, inventory, method=method)
body = _minimal_body(op)
started = time.perf_counter()
try:
@@ -254,7 +450,9 @@ def execute_operation(
ok = response.status_code in _PASS_STATUSES
detail = ""
if ok:
- body_ok, body_detail = _payload_nonempty(response, method=method)
+ body_ok, body_detail = _payload_nonempty(
+ response, method=method, kind=kind
+ )
if not body_ok:
ok = False
detail = body_detail
@@ -400,11 +598,32 @@ def run_coverage(cfg: SuiteConfig) -> CoverageReport:
def report_to_dict(report: CoverageReport) -> dict[str, Any]:
+ totals = report.totals
+ declared = totals["total"]
+ probed = totals["passed"] + totals["failed"] + totals["skipped"]
+ critical = totals["failed"]
+ series_coverage = []
+ for s in report.series:
+ series_coverage.append(
+ {
+ "series": s.series,
+ "declared": s.total,
+ "probed": s.passed + s.failed + s.skipped,
+ "critical": s.failed,
+ }
+ )
return {
"generated_at": report.generated_at,
"engine_url": report.engine_url,
- "totals": report.totals,
+ "totals": totals,
"methods": report.methods,
+ "coverage": {
+ "declared": declared,
+ "probed": probed,
+ "critical": critical,
+ "line": f"{probed}/{declared}",
+ "series": series_coverage,
+ },
"series": [asdict(s) for s in report.series],
"results": [asdict(r) for r in report.results],
}
diff --git a/pulumi-tests/pulumi/coverage/report.py b/pulumi-tests/pulumi/coverage/report.py
index 29e1bff..dda7686 100644
--- a/pulumi-tests/pulumi/coverage/report.py
+++ b/pulumi-tests/pulumi/coverage/report.py
@@ -121,10 +121,10 @@ def render_html(payload: dict[str, Any]) -> str:
· Engine {html.escape(str(payload.get('engine_url')))}
- Generated 2026-07-17T12:32:43Z
+ Generated 2026-07-18T03:44:48Z
· Engine https://api-gateway