sdk

package module

v0.12.0 Latest Latest Go to latest Published: Aug 27, 2026 License: Apache-2.0 Imports: 0 Imported by: 0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/donaldgifford/proxmox-go-sdk

Links

Open Source Insights

README ¶

proxmox-go-sdk

An idiomatic Go SDK for Proxmox VE 9.x. The public API lives in the proxmox package — a unified client plus typed per-domain services (qemu, lxc, storage, ha, …) — with an importable in-memory mock (mockpve) so consumers can integration-test without a live cluster.

Install

go get github.com/donaldgifford/proxmox-go-sdk/proxmox@latest

Quickstart (development)

mise install                  # toolchain
just                          # task menu
just build                    # compiles every package + the mockpve helper
just test                     # race + coverage
just run -- --help            # run the mockpve server via `go run`

See DEVELOPMENT.md for the full workflow and TESTING.md for live-node testing + cassette recording.

Release

Releases are automatic: merging a PR to main mints the next tag from the PR's semver label (major/minor/patch/dont-release) and CI runs goreleaser — no manual tagging.

The SDK is released by the git tag itself — consumers pin github.com/donaldgifford/proxmox-go-sdk/proxmox@vX.Y.Z; there is no library binary. The tag also builds the mockpve test-helper: multi-arch archives land on the Forgejo (or GitHub) release page, with version metadata (version, commit, date) embedded via -ldflags.

Container

The image packages the mockpve test-helper server (not the SDK):

docker build -t mockpve:dev \
  --build-arg VERSION=$(git describe --tags --always) \
  --build-arg COMMIT=$(git rev-parse --short HEAD) \
  --build-arg DATE=$(date -u +%Y-%m-%dT%H:%M:%SZ) .

Image is distroless + nonroot; entrypoint is mockpve.

Layout

doc.go                  module root — doc-only package, points at proxmox/
proxmox/                the SDK: unified client + per-domain services
├── api/                low-level transport (auth, retry, failover)
├── qemu/ lxc/ storage/ ha/ sdn/ …   typed per-domain services
├── mockpve/            importable in-memory PVE responder for tests
└── integration/        live-node suite + recorded go-vcr cassettes
cmd/mockpve/            runnable mockpve server (the only SHIPPED binary)
cmd/pvelab/             nested-PVE dogfood lab CLI (go run-only dev tool)
Dockerfile              multi-stage distroless build (mockpve image)
.goreleaser.yml         release config
mise.toml               pinned toolchain
justfile                task runner

Conventions

See CLAUDE.md for the full operating notes (Go-specific + homelab universals).

License

Apache-2.0

Documentation ¶

Overview ¶

Package sdk is the module root for the Proxmox VE 9.x Go SDK. It carries no API surface itself — the client lives in package proxmox:

import "github.com/donaldgifford/proxmox-go-sdk/proxmox"

client, err := proxmox.NewClient(ctx, endpoint, creds)

Typed per-domain services hang off the client (proxmox/qemu, proxmox/lxc, proxmox/storage, proxmox/ha, ...); operations that start a PVE task return a tasks.Ref the caller awaits. An in-memory PVE responder for consumer tests lives in proxmox/mockpve and is also runnable as a standalone server via cmd/mockpve.

See docs/design/0001-proxmox-sdk-package-layout.md for the public contract, docs/impl/0001-proxmox-ve-9x-sdk-coverage.md for the capability ledger, and docs/adr/ for the decisions behind the SDK split and the PVE 9.x-only floor.

Source Files ¶

View all Source files

doc.go

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
cmd
mockpve command Command mockpve runs the in-memory Proxmox VE responder as a standalone server, so consumers can integration-test against a fake PVE without a live cluster.	Command mockpve runs the in-memory Proxmox VE responder as a standalone server, so consumers can integration-test against a fake PVE without a live cluster.
pve-schemadiff command Command pve-schemadiff guards this repo's picture of the Proxmox VE REST API against reality.	Command pve-schemadiff guards this repo's picture of the Proxmox VE REST API against reality.
pve-schemadiff/coverage Package coverage measures the SDK's REST surface against the real Proxmox VE API and renders docs/COVERAGE.md, the committed coverage report (DESIGN-0005).	Package coverage measures the SDK's REST surface against the real Proxmox VE API and renders docs/COVERAGE.md, the committed coverage report (DESIGN-0005).
pve-schemadiff/schema Package schema parses a Proxmox VE apidoc.js API-schema dump into a flat set of (method, path) endpoints and diffs it against a stored baseline, so CI can flag when the 9.x REST surface drifts across minor releases (OQ-7 / IMPL-0001).	Package schema parses a Proxmox VE apidoc.js API-schema dump into a flat set of (method, path) endpoints and diffs it against a stored baseline, so CI can flag when the 9.x REST surface drifts across minor releases (OQ-7 / IMPL-0001).
pvelab command Command pvelab provisions the ephemeral nested-PVE dogfood lab this repo's integration suite runs against (DESIGN-0002 / IMPL-0002): it prepares the auto-install ISO on the outer host, creates and boots the nested node VMs, forms the cluster, and tears everything down again.	Command pvelab provisions the ephemeral nested-PVE dogfood lab this repo's integration suite runs against (DESIGN-0002 / IMPL-0002): it prepares the auto-install ISO on the outer host, creates and boots the nested node VMs, forms the cluster, and tears everything down again.
pvelab/lab Package lab is the importable logic behind the pvelab CLI (DESIGN-0002 / IMPL-0002): YAML config loading + validation, auto-install ISO preparation on the outer host, per-node answer rendering and the embedded answer server, node-VM provisioning and readiness, cluster formation, teardown with blast-radius guards, and the state/env handoff to the integration suite.	Package lab is the importable logic behind the pvelab CLI (DESIGN-0002 / IMPL-0002): YAML config loading + validation, auto-install ISO preparation on the outer host, per-node answer rendering and the embedded answer server, node-VM provisioning and readiness, cluster formation, teardown with blast-radius guards, and the state/env handoff to the integration suite.
hack
pvelab-spike command Command pvelab-spike is the THROWAWAY Phase 0 driver for IMPL-0002's dogfood harness: it creates one nested PVE node VM on the outer host from a prepared auto-install ISO, times the unattended install until the nested API answers with password credentials, and tears the VM down again.	Command pvelab-spike is the THROWAWAY Phase 0 driver for IMPL-0002's dogfood harness: it creates one nested PVE node VM on the outer host from a prepared auto-install ISO, times the unattended install until the nested API answers with password credentials, and tears the VM down again.
proxmox Package proxmox is the unified Proxmox VE 9.x SDK client.	Package proxmox is the unified Proxmox VE 9.x SDK client.
access Package access wraps PVE access control: users, groups, roles, ACLs, and API tokens, all under the 9.x privilege model.	Package access wraps PVE access control: users, groups, roles, ACLs, and API tokens, all under the 9.x privilege model.
api Package api is the low-level Proxmox VE transport that every service package is built on.	Package api is the low-level Proxmox VE transport that every service package is built on.
ceph Package ceph wraps Proxmox VE 9.x (Squid) Ceph management: pools, OSDs, and cluster status.	Package ceph wraps Proxmox VE 9.x (Squid) Ceph management: pools, OSDs, and cluster status.
cluster Package cluster wraps cluster-wide reads and the datacenter options.	Package cluster wraps cluster-wide reads and the datacenter options.
console Package console wraps the Proxmox VE 9.x console surface: minting console tickets and opening a VNC console session.	Package console wraps the Proxmox VE 9.x console surface: minting console tickets and opening a VNC console session.
firewall Package firewall wraps the Proxmox VE firewall at any of its three scopes — the datacenter (cluster), a node, or a single guest.	Package firewall wraps the Proxmox VE firewall at any of its three scopes — the datacenter (cluster), a node, or a single guest.
ha Package ha wraps Proxmox VE high availability.	Package ha wraps Proxmox VE high availability.
integration Package integration holds the opt-in, live-node integration suite for the SDK (OQ-5 / IMPL-0001 Testing Plan).	Package integration holds the opt-in, live-node integration suite for the SDK (OQ-5 / IMPL-0001 Testing Plan).
internal/svcutil Package svcutil holds unexported helpers shared by the typed service packages (qemu, lxc, storage, …).	Package svcutil holds unexported helpers shared by the typed service packages (qemu, lxc, storage, …).
lxc Package lxc wraps the PVE LXC container endpoints under /nodes/{node}/lxc.	Package lxc wraps the PVE LXC container endpoints under /nodes/{node}/lxc.
metrics Package metrics wraps Proxmox VE 9.x metric reads and external metric-server configuration.	Package metrics wraps Proxmox VE 9.x metric reads and external metric-server configuration.
mockpve Package mockpve is an in-memory Proxmox VE responder for tests.	Package mockpve is an in-memory Proxmox VE responder for tests.
nodes Package nodes wraps per-node administration.	Package nodes wraps per-node administration.
pbs Package pbs wraps the Proxmox VE 9.x PVE-side backup surface: scheduled backup jobs, immediate (vzdump) backups, backup listing, and restore.	Package pbs wraps the Proxmox VE 9.x PVE-side backup surface: scheduled backup jobs, immediate (vzdump) backups, backup listing, and restore.
pverr Package pverr is the Proxmox VE SDK error taxonomy.	Package pverr is the Proxmox VE SDK error taxonomy.
qemu Package qemu wraps the PVE QEMU/VM endpoints under /nodes/{node}/qemu.	Package qemu wraps the PVE QEMU/VM endpoints under /nodes/{node}/qemu.
sdn Package sdn wraps Proxmox VE software-defined networking: zones, VNets and their subnets, fabrics and their node membership, the cluster-wide apply that activates staged changes, and the node-scoped live-status reads.	Package sdn wraps Proxmox VE software-defined networking: zones, VNets and their subnets, fabrics and their node membership, the cluster-wide apply that activates staged changes, and the node-scoped live-status reads.
ssh Package ssh is the SFTP/exec side-channel for the few Proxmox operations the REST API cannot do — uploading snippets and backup archives to a node's storage via SFTP under a PAM account, and running the occasional command over SSH.	Package ssh is the SFTP/exec side-channel for the few Proxmox operations the REST API cannot do — uploading snippets and backup archives to a node's storage via SFTP under a PAM account, and running the occasional command over SSH.
storage Package storage wraps PVE storage: datastore configuration (reads and writes), per-node status, content/volume management, streaming uploads, volume snapshots, and ZFS pools.	Package storage wraps PVE storage: datastore configuration (reads and writes), per-node status, content/volume management, streaming uploads, volume snapshots, and ZFS pools.
tasks Package tasks decodes PVE worker identifiers (UPIDs) and waits on the asynchronous tasks they name.	Package tasks decodes PVE worker identifiers (UPIDs) and waits on the asynchronous tasks they name.
types Package types holds the primitive value types shared across the Proxmox VE SDK: identifiers (VMID, NodeName, GuestRef), the PowerState enum, and PVEBool.	Package types holds the primitive value types shared across the Proxmox VE SDK: identifiers (VMID, NodeName, GuestRef), the PowerState enum, and PVEBool.
version Package version reports the running PVE release and gates per-minor 9.x capabilities against the SDK's 9.0 floor (ADR-0002).	Package version reports the running PVE release and gates per-minor 9.x capabilities against the SDK's 9.0 floor (ADR-0002).