Keep API not-found and 401 responses usable behind Ingress and in the Web UI.

Return native JSON with the missing id in the message, clear stale sessions on 401, and document ingress-nginx annotations so branded HTML 404/405 pages do not rewrite simulator bodies.
2026-07-22 06:52:35 +03:00
parent 131e2e63d2
commit e8b08526d1
13 changed files with 260 additions and 62 deletions
@@ -31,6 +31,60 @@ DB-backed стаб — 501 не должен появляться для изв
  base64 от `user:password`).
 - Отказ по правам — попробуйте сравнить `administrator@vsphere.local` и
  `readonly@vsphere.local` (см. [Авторизация](domains/authz.md)).
+- В Web UI ответ 401 очищает сохранённую сессию и переключает бейдж в шапке
+  на **Guest** с toast «Session expired — sign in again».
+
+## Ingress возвращает брендированный HTML 404 / nginx 405 вместо JSON
+
+Симулятор отвечает на API-ошибки JSON (`detail` / `error_type` /
+`messages`). Если вы видите HTML «page not found» сайта или голую страницу
+nginx **405**, **Ingress / reverse proxy** подменил тело upstream (часто через
+`custom-http-errors` у ingress-nginx).
+
+Исправьте аннотации Ingress для этого хоста (см.
+`helm/vmware-api-simulator/values-ingress-example.yaml`):
+
+```yaml
+annotations:
+  nginx.ingress.kubernetes.io/proxy-intercept-errors: "false"
+  nginx.ingress.kubernetes.io/custom-http-errors: "502,503"
+```
+
+Затем перепроверьте с `Accept: application/json`. Отсутствующий host должен
+выглядеть так:
+
+```json
+{
+  "detail": {
+    "error_type": "not_found",
+    "messages": [
+      {
+        "default_message": "No such host ('host-999')",
+        "id": "com.vmware.vapi.std.errors.not_found",
+        "args": ["host-999"]
+      }
+    ],
+    "data": { "host": "No such host ('host-999')" }
+  }
+}
+```
+
+Seeded id хостов для `small` / `large` / `big` начинаются с `host-11`.
+Cookbook-ВМ включают `vm-101` (`web-01`).
+
+### Корректная authenticated-мутация (vSphere Automation)
+
+Сессия в заголовке/cookie + JSON-тело (не form-urlencoded):
+
+```bash
+SID=$(curl -sk -u 'administrator@vsphere.local:VMware1!' -X POST \
+  "https://HOST/api/session" | tr -d '"')
+curl -sk -X POST "https://HOST/api/vcenter/vm" \
+  -H "Accept: application/json" \
+  -H "Content-Type: application/json" \
+  -H "vmware-api-session-id: $SID" \
+  -d '{"name":"lab-vm","guest_os":"OTHER_GUEST_64","placement":{"folder":"group-v23","host":"host-11","datastore":"datastore-31","resource_pool":"resgroup-22"}}'
+```

 ## Задача никогда не завершается

@@ -31,6 +31,59 @@ should not appear for a known path. If you see it:
  `user:password` base64).
 - Privilege denial — try `administrator@vsphere.local` vs
  `readonly@vsphere.local` to compare (see [Authorization](domains/authz.md)).
+- In the Web UI, a 401 clears the stored session and switches the header badge
+  to **Guest** with a “Session expired — sign in again” toast.
+
+## Ingress returns branded HTML 404 / nginx 405 instead of JSON
+
+The simulator answers API errors as JSON (`detail` / `error_type` /
+`messages`). If you see a site HTML “page not found” or plain nginx **405**
+page, the **Ingress / reverse proxy** replaced the upstream body (often via
+`custom-http-errors` on the ingress-nginx controller).
+
+Fix on the Ingress for this host (see
+`helm/vmware-api-simulator/values-ingress-example.yaml`):
+
+```yaml
+annotations:
+  nginx.ingress.kubernetes.io/proxy-intercept-errors: "false"
+  nginx.ingress.kubernetes.io/custom-http-errors: "502,503"
+```
+
+Then re-check with `Accept: application/json`. A missing host should look like:
+
+```json
+{
+  "detail": {
+    "error_type": "not_found",
+    "messages": [
+      {
+        "default_message": "No such host ('host-999')",
+        "id": "com.vmware.vapi.std.errors.not_found",
+        "args": ["host-999"]
+      }
+    ],
+    "data": { "host": "No such host ('host-999')" }
+  }
+}
+```
+
+Seeded host ids for `small` / `large` / `big` start at `host-11`. Cookbook VMs
+include `vm-101` (`web-01`).
+
+### Correct authenticated mutation (vSphere Automation)
+
+Session cookie/header + JSON body (not form-urlencoded):
+
+```bash
+SID=$(curl -sk -u 'administrator@vsphere.local:VMware1!' -X POST \
+  "https://HOST/api/session" | tr -d '"')
+curl -sk -X POST "https://HOST/api/vcenter/vm" \
+  -H "Accept: application/json" \
+  -H "Content-Type: application/json" \
+  -H "vmware-api-session-id: $SID" \
+  -d '{"name":"lab-vm","guest_os":"OTHER_GUEST_64","placement":{"folder":"group-v23","host":"host-11","datastore":"datastore-31","resource_pool":"resgroup-22"}}'
+```

 ## Task never finishes