Sergey Antropoff
777926487b
initial QEMU slice, backed by imported contracts for majors 6–9. - Implement durable handlers for access/auth, cluster, LXC, storage, HA, firewall, Ceph, SDN, ACME, notifications, pools, mapping, and node ops - Serve an interactive Web UI with catalog browsing, demo seed controls, and OpenAPI/help surfaces - Bundle PVE 6.4-15, 7.4-16, and 8.4.5 contract revisions alongside 9.2.3 - Support in-memory runtime contract Apply (POST /ui/api/contract/apply) so /version and /api2 routes follow the selected major until restart - Expand seed profiles (including demo-cluster), migrations 007–008, TLS gateway config, Compose/Makefile tooling, and compatibility evidence - Tighten .gitignore for macOS, hidden directories (.*/), and local secrets
58 lines
2.0 KiB
Markdown
58 lines
2.0 KiB
Markdown
# Troubleshooting
|
||
|
||
## Ready stays unavailable
|
||
|
||
1. Confirm Postgres: `make logs` / Compose health.
|
||
2. Run `make db-migrate`.
|
||
3. Hit `/health/ready` again.
|
||
|
||
Workers may retry until migrations catch up after a late migrate.
|
||
|
||
## Unexpected HTTP 501
|
||
|
||
Declared methods on majors **6–9** should have handlers. If you see 501:
|
||
|
||
- Confirm the active runtime (`/api2/json/version` and Web UI runtime label).
|
||
- Confirm you are calling the path/verb exactly as declared for that major.
|
||
- Check `CONTRACT_FALLBACK` is not masking a different issue with fixture mode.
|
||
- Report a regression — full registry coverage is expected.
|
||
|
||
## 401 / 403
|
||
|
||
- Ticket expired or cookie not sent.
|
||
- Mutation missing `CSRFPreventionToken` on a ticket session.
|
||
- API token malformed (`PVEAPIToken=user@realm!id=secret`).
|
||
- ACL denial (try `auditor@pve` vs `root@pam` to compare).
|
||
|
||
## Task never finishes
|
||
|
||
- Inspect `/nodes/{node}/tasks/{upid}/status` and `/log`.
|
||
- Check worker logs (`make logs`).
|
||
- Verify `TASK_WORKER_CONCURRENCY` > 0 and database leases can be claimed.
|
||
- Extremely high `SIMULATION_TIME_SCALE` slowdowns are unusual (higher = faster
|
||
simulation); mis-set worker leases are more common culprits.
|
||
|
||
## proxmoxer / TLS failures
|
||
|
||
- Use host port **8007** (gateway), not 8006, for TLS clients.
|
||
- Set `verify_ssl=False` **only** for the local self-signed cert.
|
||
- Inside Compose, target `tls-gateway:8443`.
|
||
- Seeded node name for `small` is `pve01`, not `pve1`.
|
||
|
||
## Terraform / Pulumi drift after reseed
|
||
|
||
Reseed replaces PostgreSQL guests; tool state files do not. Refresh, import, or
|
||
rebuild stacks after `make seed`.
|
||
|
||
## Hot-swap “did nothing”
|
||
|
||
- Catalog browse ≠ apply. Use **Apply as runtime** or
|
||
`POST /ui/api/contract/apply?major=N`.
|
||
- Confirm with `/api2/json/version`.
|
||
- Remember apply is process-local; Compose restart restores `CONTRACT_SNAPSHOT`.
|
||
|
||
## Demo unload surprised you
|
||
|
||
`POST /ui/api/demo/unload` clears API-created state and loads `minimal`. Re-run
|
||
`make seed PROFILE=small` (or load demo again) to restore richer fixtures.
|