Research: LXC path (Proxmox API vs liblxc, and LXD/Incus) #30
Loading…
Reference in a new issue
No description provided.
Delete branch "%!s()"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
DECISIONS Open item 3: "LXC path: Proxmox API first, or plain liblxc", plus item 4, whether LXD/Incus virtual machines appear. The owner asked when full LXC support arrives, so this needs a cited recommendation for the owner to decide on.
Starting research for kayg/infraternal#30 on branch
research-lxc, based ondevhead9688a2438a1c5bbeeb3326a5be8df58e5c4f9a0a. Scope is onlydocs/research/lxc.md; I will not push.Finding for #30: PVE-managed LXC has no arbitrary command-execution REST endpoint in the published API;
pct execis a local host command, while LXC console access usestermproxyfollowed byvncwebsocket. The API's guest-agentexecroutes are for QEMU VMs. Proxmox's late-2025 development series added token authentication to the terminal proxy flow, so the adapter should test the exact installed PVE release before advertising theexecchannel. Sources: https://pve.proxmox.com/pve-docs/api-viewer/ ; https://pve.proxmox.com/pve-docs-9-beta/pct.1.html ; https://lore.proxmox.com/pve-devel/fec81bb3-ed78-46c7-b6f0-bd899ae8da5f%40proxmox.com/t/Compatibility finding for #30: Debian 13 stable currently packages LXC 6.0.4, while upstream LXC 7.0 LTS is a separate release line supported through June 2031. The Debian 13 real-engine gate should claim 6.0.4 coverage; add a separate 7.0 test before claiming upstream 7.0 support. Sources: https://packages.debian.org/trixie/lxc and https://linuxcontainers.org/lxc/news/
Read-only independent review started for #30. Worktree: /home/kayg/wt/research-lxc, branch: research-lxc, base/head:
9688a2438a. Scope: review docs/research/lxc.md for source-backed factual accuracy and fit with the repo contract. No edits, product code, tests or push.Independent review of
docs/research/lxc.md: 3 findings (2 concrete gaps, 1 implementation risk). The requested date-sensitive version and release claims were consistent with the primary sources checked: PVE 9.2 release, Debian 13 LXC package, LXC releases, Incus releases, and LXD release policy.Medium — Stats mappings exceed the current Engine surface (lines 17–20, 33, 50, 62). The document marks PVE stats as supported and plans Incus/LXD/LXC stats through the JSON-lines channel, while line 3 says the recommendation follows the existing Engine capability model. The stream contract defines the stats payload shape, but the current Engine trait and Capabilities have no stats method or capability (stream contract). This makes the capability mapping and effort estimate depend on an unstated Engine API change. Mark stats as requiring that API/capability work, or describe an explicit extension to the current interface.
Medium — PVE terminal protocol omits its authentication handshake (lines 9, 17; effort line 65). The description covers the termproxy port/ticket and data/resize framing, but leaves out the initial WebSocket protocol message carrying
username:ticket\nand the server’sOKreply before terminal frames. Proxmox’s termproxy implementation implements this handshake. Without it, the proposed bridge description is incomplete for establishing the console, including the token-auth compatibility work mentioned at line 36.Risk — Plain LXC PTY setup is underspecified (lines 7, 18, 42, 61). The LXC manual says
lxc-attachautomatically allocates a PTY when an attached standard descriptor is already a terminal; a daemon’s stream-backed stdio may not meet that condition (lxc-attachmanual). The claim is feasible, but the adapter needs an explicit host-side PTY allocation and byte/resize/exit bridge (or a defined liblxc FD strategy) to satisfy the existing argv and PTY Engine contract. The research should make that dependency visible in the recommendation and estimate.Review only; no tests or verification gate run.
Finished the LXC management research in
docs/research/lxc.md(checked 2026-09-24; sources cited in the document).Recommendation: build a plain LXC adapter first for an explicitly configured path not owned by another control plane. Keep Proxmox VE separate because its LXC API offers a console but no argv exec route; a shared Incus/LXD REST and WebSocket core is practical with per-server extension checks.
The report records two implementation dependencies: plain LXC needs an explicit host PTY bridge for stream-backed exec, and native stats require adding a stats method/capability and stream path to the current Engine interface. It also documents the PVE terminal WebSocket auth exchange and test/version risks.
Commit:
ced3b80560291df38b78ee5c105c0082967c7274(docs: research LXC management adapters). No push.scripts/verify fastpassed (run before final documentation-only refinements):