feat: Proxmox VE LXC provider

[mzyy94]

Lets Sablier manage LXC containers via the Proxmox API, following the same patterns as existing providers.

• Uses github.com/luthermonson/go-proxmox with API token auth
• Auto-discovers containers across all cluster nodes
• Tags for opt-in (sablier) and grouping (sablier-group-<name>)
  • Proxmox tags don't support key=value, so prefix convention is used
• Instance lookup by hostname, VMID (100), or node/VMID (pve1/100)
• Readiness based on network interface IP assignment (LXC has no healthcheck)
• Stop events via polling (Proxmox has no event stream)

Design: comparison with Docker provider

Feature	Docker	Proxmox LXC
Discovery	sablier.enable=true label (server-side filter)	sablier tag (client-side filter, no API-level tag filtering)
Grouping	sablier.group=<name> label	sablier-group-<name> tag
Instance naming	Container name	Hostname, VMID, or node/vmid
Readiness	Docker healthcheck	Non-loopback NIC IP check
Start	Synchronous ContainerStart	Async task (UPID); tracked in pendingTasks, polled via InstanceInspect
Start failure	Returns error immediately	InstanceInspect reports UnrecoverableInstanceState
Stop events	Real-time event stream	Polling (10s interval, closes after 5 consecutive failures)

Configuration

provider:
  name: proxmox_lxc
  proxmox-lxc:
    url: "https://proxmox.local:8006/api2/json"
    token-id: "root@pam!sablier"
    token-secret: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
    tls-insecure: false

How it's tested

Unit tests cover all provider methods with an httptest mock server. Integration tests run against a real Proxmox VE cluster (template clone, full start/inspect/stop lifecycle, stop notification).

Been running this on a real cluster for a few days. Everything works fine.

[acouvreur]

Impressive work @mzyy94

Thank you for contributing! I will review, but it will take some time. I will also ask github copilot to review it, but it doees not mean that each comment made by Copilot must be resolved.

[Copilot]

Pull request overview

Adds a new proxmox_lxc instance provider so Sablier can start/stop and discover Proxmox VE LXC containers via the Proxmox API, aligning behavior with existing provider patterns (discovery, grouping, readiness, and stop notifications).

Changes:

• Introduces the Proxmox LXC provider implementation (discovery via tags, start/stop, inspect/readiness, stop-event polling) plus unit/integration tests.
• Extends config/CLI/docs to support Proxmox API token auth and TLS settings.
• Updates module dependencies to include github.com/luthermonson/go-proxmox.

Reviewed changes

Copilot reviewed 32 out of 34 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
pkg/sabliercmd/testdata/config_yaml_wanted.json	Updates expected config JSON to include ProxmoxLXC defaults.
pkg/sabliercmd/testdata/config_env_wanted.json	Updates expected config JSON to include ProxmoxLXC defaults.
pkg/sabliercmd/testdata/config_default.json	Updates default config JSON to include ProxmoxLXC defaults.
pkg/sabliercmd/testdata/config_cli_wanted.json	Updates expected config JSON to include ProxmoxLXC defaults.
pkg/sabliercmd/root.go	Adds CLI flags and viper bindings for Proxmox LXC config.
pkg/sabliercmd/provider.go	Wires proxmox_lxc into provider setup and constructs the Proxmox client.
pkg/provider/proxmoxlxc/proxmox_lxc.go	Core provider: discovery across nodes, caching, instance resolution.
pkg/provider/proxmoxlxc/tags.go	Implements tag parsing and group extraction conventions.
pkg/provider/proxmoxlxc/container_list.go	Implements InstanceList and InstanceGroups.
pkg/provider/proxmoxlxc/container_start.go	Implements InstanceStart with async task tracking.
pkg/provider/proxmoxlxc/container_stop.go	Implements InstanceStop and task wait.
pkg/provider/proxmoxlxc/container_inspect.go	Implements InstanceInspect, readiness via NIC IP, and pending-task polling/TTL.
pkg/provider/proxmoxlxc/events.go	Implements stop notifications via polling.
pkg/provider/proxmoxlxc/testhelper_test.go	Mock Proxmox API server for unit tests.
pkg/provider/proxmoxlxc/export_test.go	Exports test helpers for external test packages.
pkg/provider/proxmoxlxc/tags_test.go	Unit tests for tag parsing/group extraction.
pkg/provider/proxmoxlxc/container_list_test.go	Unit tests for list/groups behavior, multi-node, duplicate hostname detection.
pkg/provider/proxmoxlxc/container_start_test.go	Unit tests for start behavior and task failure/in-progress handling.
pkg/provider/proxmoxlxc/container_stop_test.go	Unit tests for stop behavior.
pkg/provider/proxmoxlxc/container_inspect_test.go	Unit tests for inspect behavior and lookup modes.
pkg/provider/proxmoxlxc/events_test.go	Unit test ensuring notify loop closes channel on ctx cancel.
pkg/provider/proxmoxlxc/integration_test.go	Integration test suite against a real Proxmox cluster (env-gated).
pkg/provider/proxmoxlxc/testcontainers_test.go	Integration helper to clone/tag/cleanup a real LXC container.
pkg/config/provider.go	Adds ProxmoxLXC config struct, provider list entry, and validation.
pkg/config/provider_test.go	Adds validation test cases for the new provider config.
docs/providers/proxmox_lxc.md	New provider documentation (config, tagging, readiness, naming).
docs/providers/overview.md	Adds Proxmox LXC to providers overview table.
docs/configuration.md	Updates configuration docs and CLI help listing to include proxmox_lxc.
docs/assets/img/proxmox.png	Adds Proxmox icon used by docs.
docs/_sidebar.md	Adds Proxmox LXC entry to docs sidebar.
docs/README.md	Updates terminology to include Proxmox LXC containers as instances.
README.md	Adds Proxmox LXC section and updates config examples/provider list.
go.mod	Adds new indirect requirements related to Proxmox client usage.
go.sum	Adds checksums for new dependencies.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[codecov]

Codecov Report

❌ Patch coverage is 68.49711% with 109 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
pkg/provider/proxmoxlxc/events.go	30.95%	28 Missing and 1 partial ⚠️
pkg/provider/proxmoxlxc/container_inspect.go	69.89%	21 Missing and 7 partials ⚠️
pkg/provider/proxmoxlxc/proxmox_lxc.go	74.19%	14 Missing and 10 partials ⚠️
pkg/sabliercmd/provider.go	0.00%	12 Missing ⚠️
pkg/provider/proxmoxlxc/container_stop.go	57.14%	5 Missing and 4 partials ⚠️
pkg/provider/proxmoxlxc/container_start.go	82.60%	2 Missing and 2 partials ⚠️
pkg/provider/proxmoxlxc/container_list.go	92.30%	1 Missing and 1 partial ⚠️
pkg/config/provider.go	91.66%	1 Missing ⚠️

Files with missing lines	Coverage Δ
pkg/provider/proxmoxlxc/tags.go	100.00% <100.00%> (ø)
pkg/sabliercmd/root.go	97.70% <100.00%> (+0.23%)	⬆️
pkg/config/provider.go	58.53% <91.66%> (+13.70%)	⬆️
pkg/provider/proxmoxlxc/container_list.go	92.30% <92.30%> (ø)
pkg/provider/proxmoxlxc/container_start.go	82.60% <82.60%> (ø)
pkg/provider/proxmoxlxc/container_stop.go	57.14% <57.14%> (ø)
pkg/sabliercmd/provider.go	0.00% <0.00%> (ø)
pkg/provider/proxmoxlxc/proxmox_lxc.go	74.19% <74.19%> (ø)
pkg/provider/proxmoxlxc/container_inspect.go	69.89% <69.89%> (ø)
pkg/provider/proxmoxlxc/events.go	30.95% <30.95%> (ø)

[sonarqubecloud]

Quality Gate failed

Failed conditions
5.7% Duplication on New Code (required ≤ 3%)
D Security Rating on New Code (required ≥ A)

See analysis details on SonarQube Cloud

Catch issues before they fail your Quality Gate with our IDE extension SonarQube for IDE

[acouvreur]

@mzyy94 I think we can merge this PR if you think it is ready?

People can then contribute further to improve it as needed

[mzyy94]

I made it ready 🚀

[acouvreur]

@mzyy94 can you please resolve conflicts with the latest changes ?

[mzyy94]

'main' merged 🆗