Fixes

• AgentFileWrite no longer double-encodes content (#343). It base64-encoded the payload and sent PVE's encode=1, so PVE encoded it a second time and QGA's single decode left base64 text on disk — corrupting any file written this way (configs, keys). Now sends the base64 payload with encode=0 so QGA reproduces the original bytes. Binary-safe.

v0.8.1 Latest

Latest

Compare

Choose a tag to compare

Breaking changes

VirtualMachine.Delete signature change — gains a second parameter *VirtualMachineDeleteOptions. Pass nil to preserve existing behaviour. See migration/v0.8.0.md for details and before/after examples.

// before
task, err := vm.Delete(ctx)

// after
task, err := vm.Delete(ctx, nil)                       // same behaviour
task, err := vm.Delete(ctx, &proxmox.VirtualMachineDeleteOptions{
    Purge: true,
    DestroyUnreferencedDisks: true,
})

What's new

• VirtualMachineDeleteOptions — pass purge, skiplock, destroy-unreferenced-disks to VirtualMachine.Delete (#340)
• VirtualMachine.Ping now correctly propagates config-fetch errors (#339)
• golangci-lint config expanded: gofmt enforced, 10 additional linters enabled, minor findings fixed (TLS MinVersion, websocket body close, errors.Is) (#341)

Migration guide

See migration/v0.8.0.md.

Full changelog: v0.7.1...v0.8.0

v0.8.0

Compare

Choose a tag to compare

Highlights

v0.7.1 is a correctness patch. A full audit of every exported response type in types.go against PVE's apidoc.json and QGA's qga/qapi-schema.json surfaced eight long-standing schema mismatches — six of them silently no-op'd on the wire (wrong JSON tag, wrong scalar type, or a field name PVE never emitted). The apparent breaks below are functionally additive: the new field is the first one that has ever worked.

⚠️ Breaking changes & migration

Two source-level breaks, both on StorageContent. See migration/v0.7.1.md for the full upgrade walkthrough.

Deprecate-and-replace (no compile break)

The Go field still exists and code still compiles; only the wire format changed. Switch to the replacement to get real behavior.

• AgentNetworkIPAddress.MacAddress deprecated → read iface.HardwareAddress (the QGA schema has never had a per-IP mac-address field). Closes #336.
• FirewallNodeOption.Ntp / FirewallVirtualMachineOption.Ntp deprecated → use NDP. The PVE option is ndp (Neighbor Discovery Protocol); ntp was a typo shipped since v0.1.x and never had any effect.

Internal-only JSON tag fixes (no caller impact)

Tags fixed so the fields finally unmarshal from PVE:

• CephMonMap.DisallowedLeaders — strip trailing ": " inside the quoted tag
• CephMonMap.RemovedRanks — same
• FirewallRule.IcmpType — icmp_type → icmp-type (ICMP rules now round-trip correctly)

What didn't change

• Wire format for everything not listed above
• NewClient(...) with no options still behaves identically to v0.7.0
• All v0.7.0 client options (WithProxy, WithRetry, WithEagerAuth, …) unchanged
• v0.7.0 instance-handle patterns (snapshots, firewall rules, SDN, etc.) unchanged

What's Changed

See v0.7.0...v0.7.1 once tagged.

Full Changelog: v0.7.0...v0.7.1

v0.7.1

Compare

Choose a tag to compare

Highlights

v0.7.0 is the major cleanup release. Three years of accumulated patterns get
resolved into a consistent shape:

• 100% PVE API coverage — every endpoint in the upstream schema is wrapped, with three documented exceptions for streaming endpoints (mtunnelwebsocket builders and file-restore/download). The v0.6.0 release sat at 81%; the v0.7.x cycle closed the cluster gap entirely with the SDN sweep (#320), the bulk-action / ceph-flags / qemu-cpu-models / options / log / notifications / HA arm-disarm cleanup (#322), and the rest.
• Twelve new client options for transport, auth, and middleware: WithTimeout, WithInsecureSkipVerify, WithRootCAs, WithRootCAFile, WithClientCertificate, WithOTP, WithDefaultRealm, WithEagerAuth, WithProxy, WithProxyFromEnvironment, WithRetry (+ helpers), WithRequestInterceptor. All compose with WithHTTPClient regardless of option order. README has lab + production usage examples.
• Consistent instance-handle pattern across the library. VM/container snapshots, firewall rules, and the new SDN resources (controllers, DNS, fabrics, IPAMs, prefix-lists, route-maps) all follow the parent.Resource(id) → *Resource getter shape that ceph already used in v0.6.0. The full inventory is in AGENTS.md.
• Config-struct defaults stop biting. Issue #199 is closed. ~30 fields where the Go zero value would silently override a PVE server default are now *T; ~25 bool-on-wire fields are now IntOrBool so they round-trip both true/false and 1/0. proxmox.Ptr(v) is the inline helper for the pointer fields.
• Indexed device fields dropped from VirtualMachineConfig / ContainerConfig. Every numbered Net0..9, SCSI0..30, IDE0..3, SATA0..5, VirtIO0..15, USB0..14, HostPCI0..9, IPConfig0..9, Numa0..9, Parallel0..2, Serial0..3, Unused0..9 is gone. The maps populated by UnmarshalJSON (Nets, SCSIs, IPConfigs, …) are now the authoritative shape. PVE actually returns more indices than the explicit fields ever covered (net0..net31, scsi0..scsi30, unused0..unused255) — the old shape was silently dropping data.
• proxmox.CSV type for PVE fields serialized as comma-joined strings on the wire (most notably SDNZone.Nodes and .Peers).
• Subdirs methods on *Cluster and *Node for ACL-filtered directory-index probes. Use them to discover what an API token actually has permission to read without try-and-403 against every endpoint.
• Unit-test coverage pushed from ~30% to ~88%+. The remaining gap is websocket dialers, file-restore streaming, and time-loop poller bodies — all better covered by integration tests.

⚠️ Breaking changes & migration

This is a heavy release for source compatibility. The breaks are concentrated in three areas: the snapshot/firewall instance-pattern refactors, the dropped indexed device fields, and the config-struct pointerization sweep. Most fixes are mechanical.

Read migration/v0.7.0.md for the complete walkthrough — themed sections with before/after code for each break. The short version:

If you're upgrading from v0.5.x, also read migration/v0.6.0.md for the small set of v0.6.0 breaks.

What didn't change

• Wire format. Every request/response is bit-identical to v0.6.0. PVE doesn't see anything new.
• NewClient(url, WithCredentials(...)) and NewClient(url, WithAPIToken(...)) with no other options — every new client field has a zero-value-safe code path. Upgrading without adopting any new option produces no behavior change.
• The lazy 401-retry auth flow. If you didn't add WithEagerAuth, the existing /access/ticket-after-401 sequence is unchanged.

What's Changed

• refactor!: drop explicit indexed device fields, follow-up to #260 by @luthermonson in #261
• refactor!: VM/container snapshots → instance-type pattern by @luthermonson in #311
• refactor!: firewall rules → getter + *FirewallRule instance methods by @luthermonson in #310
• feat: cluster API coverage — firewall main, HA, backup jobs, replication by @luthermonson in #274
• docs(types): explain rationale on pointer fields tied to PVE defaults by @luthermonson in #268
• feat(mage): teach endpoints:coverage about diridx helpers, Upload, and by-design exclusions by @luthermonson in #318
• feat: wrap PVE directory-index (diridx) endpoints - permission/capability probes by @luthermonson in #319
• feat(cluster): wrap /cluster/sdn — controllers, dns, fabrics, ipams, prefix-lists, route-maps, vnets/firewall+ips+subnets by @luthermonson in #320
• fix(mage): scanner picks up Client.UploadReader and multi-line Upload calls by @luthermonson in #321
• feat(cluster): close remaining /cluster/* coverage gap - config, custom CPU models, bulk-action, ceph flags, backup-info, options, ha arm/disarm, log, notifications by @luthermonson in #322
• feat(options): TLS + timeout + auth ergonomics (Tier 1 + Tier 2) by @luthermonson in #327
• feat(options): add WithRetry — transient-failure retries with exponential backoff by @luthermonson in #326
• feat(options): add WithProxy and WithProxyFromEnvironment by @luthermonson in #324
• feat(options): add WithRequestInterceptor — middleware hook for outgoing requests by @luthermonson in #325
• docs: polish AGENTS.md + README for v0.7.x conventions; add examples/sdn by @luthermonson in #323
• fix(test): make TestWithProxyFromEnvironment order-independent by @luthermonson in #333
• test: cover containers.go (~60% -> ~95%) by @luthermonson in #328
• test: cover cluster_sdn*.go (close the post-#320 gap) by @luthermonson in #329
• test: cover nodes.go + nodes_{network,disks,admin,metrics}.go + storage.go by @luthermonson in #330
• test: cover types custom marshal + cluster_{acme,mapping,notifications} + access + misc by @luthermonson in #331
• test: cover virtual_machine.go + virtual_machine_agent.go (~73% -> ~90%) by @luthermonson in #332
• docs(readme): add usage examples for Tier 3 client options by @luthermonson in #334
• docs: add migration/v0.6.0.md, migration/v0.7.0.md, codify the convention by @luthermonson in #335

Full Changelog: v0.6.0...v0.7.0

v0.7.0

Compare

Choose a tag to compare

Highlights

This is a coverage-and-correctness release. v0.6.0 lifts overall PVE API coverage substantially — /access, /pools, /nodes/{qemu,lxc,ceph,sdn,disks,apt,services,subscription,replication,time,dns,certificates,storage,agent,disks}, and /cluster/{acme,jobs,mapping,metrics,notifications} are now fully or nearly fully wrapped — and fixes a handful of latent bugs that hand-written PVE response assumptions had been hiding.

A new mage endpoints:coverage tool is included for tracking progress against the live PVE schema. AGENTS.md codifies the conventions (singleton-vs-instance handles, pointer fields for PVE-defaulted attributes) used across the new wrappers.

⚠️ Breaking changes & migration

Four exported-surface changes require source updates:

1. Container.Delete requires options

// before
task, err := container.Delete(ctx)

// after
task, err := container.Delete(ctx, nil)
// or, to exercise the new flags:
task, err := container.Delete(ctx, &proxmox.ContainerDeleteOptions{
    Force:                    proxmox.IntOrBool(true),
    Purge:                    proxmox.IntOrBool(true),
    DestroyUnreferencedDisks: proxmox.IntOrBool(true),
})

Closes #149 — previously there was no way to force-delete a locked container or purge job entries. See #262.

2. Container.UpdateSnapshot requires options

// before
err := container.UpdateSnapshot(ctx, "snap1")

// after
err := container.UpdateSnapshot(ctx, "snap1", nil)
// or to set a description:
err := container.UpdateSnapshot(ctx, "snap1", &proxmox.ContainerSnapshotUpdateOptions{
    Description: "pre-upgrade baseline",
})

From #277.

3. CephMon reshape

CephMon was previously the /cluster/ceph status row shape; in v0.6.0 it is the instance handle for /nodes/{node}/ceph/mon/{monid} endpoints. The cluster-status reader fields (CrushLocation, Priority, Weight, PublicAddr, PublicAddrs) are gone.

If you were reading mon status from /cluster/ceph results, the equivalent shape now lives in the appropriate cluster ceph response type. For the node-level mon API:

mon := node.CephMon("0")          // *CephMon instance handle
task, err := mon.Delete(ctx)      // node-level mon operations

From the /nodes/{node}/ceph 100% sweep — see #307.

4. SDNZone.Nodes type change + new CSV type

PVE returns nodes (and peers) as a comma-joined string, not a JSON array. v0.5.x's []string typing caused cluster.SDNZones() to fail outright on any zone with assigned nodes:

json: cannot unmarshal string into Go struct field SDNZone.nodes of type []string

// before — actually broken at runtime
zones, _ := cluster.SDNZones(ctx)
for _, n := range zones[0].Nodes { ... } // []string

// after
zones, _ := cluster.SDNZones(ctx)
for _, n := range zones[0].Nodes { ... } // proxmox.CSV — still iterates fine

// callers passing zone.Nodes to []string-typed APIs need an explicit conversion:
manyNodes := []string(zones[0].Nodes)

CSV is a []string named type with custom Marshal/Unmarshal that accepts both "a,b,c" and ["a","b","c"] on the wire and emits comma-joined strings. From #297 (thanks @kernel-sanders).

What's Changed

• feat: support string-based upload by @luthermonson in #257
• docs: add AGENTS.md and CLAUDE.md for AI coding agents by @luthermonson in #264
• feat: add Spice field to VirtualMachine struct by @luthermonson in #263
• fix: make TermWebSocket/VNCWebSocket actually work, surface API-token limits by @luthermonson in #259
• fix: accept JSON null in StringOrInt/StringOrUint64/StringOrFloat64 (#198) by @luthermonson in #265
• docs: audit PVE-default and schema-type mismatches on config structs (#199, #178) by @luthermonson in #266
• feat: ticket renewal via existing ticket by @luthermonson in #267
• feat: cluster backup schedules by @luthermonson in #270
• docs(agents): require pointer fields for non-zero PVE defaults by @luthermonson in #271
• feat(cloud-init): selectable iso storage + cross-storage deletion by @luthermonson in #272
• feat: EncodeSSHKeys helper for PVE's strict url-encoding by @luthermonson in #273
• feat(pools): 100% endpoint coverage; migrate Update/Delete to non-deprecated paths by @luthermonson in #275
• feat: add prune-backups and import-metadata storage endpoints by @luthermonson in #276
• feat: wrap /nodes/{node}/dns by @luthermonson in #281
• feat: wrap /nodes/{node}/time by @luthermonson in #278
• feat: wrap /nodes/{node}/services by @luthermonson in #279
• feat: wrap /nodes/{node}/subscription by @luthermonson in #283
• feat: wrap node-wide mass operations by @luthermonson in #282
• feat: wrap /nodes/{node}/replication by @luthermonson in #280
• feat: wrap /nodes/{node}/apt — repositories, update, versions, changelog by @luthermonson in #285
• feat: wrap /nodes/{node}/qemu/{vmid}/agent/* — read/freeze/trim/shutdown/file I/O by @luthermonson in #286
• refactor(qga): use typed result envelope in agent helpers by @luthermonson in #288
• deps: bump go-diskfs to v1.9.3 — fixes Joliet ISO label/filename mangling by @luthermonson in #289
• deps: bump go-diskfs to v1.9.3 — fixes Joliet label / filename mangli… by @luthermonson in #290
• feat: wrap /cluster/metrics, /cluster/mapping, /cluster/notifications by @luthermonson in #287
• feat: wrap /nodes/{node}/certificates/acme — order/renew/revoke by @luthermonson in #284
• fix!: expose force/purge/destroy-unreferenced-disks on Container.Delete (#149) by @luthermonson in #262
• feat(lxc): close /nodes/{node}/lxc coverage gaps + bug fixes by @luthermonson in #277
• fix: capture all indexed device entries in VirtualMachineConfig/ContainerConfig (#211) by @luthermonson in #260
• feat: wrap /cluster/acme — accounts, plugins, directories, meta, ToS by @luthermonson in #291
• feat: wrap remaining /nodes/{node}/qemu/{vmid} — firewall, cloudinit, snapshot config by @luthermonson in #292
• feat: wrap remaining /nodes/{node}/storage/{storage}/* — content alloc/update/copy, OCI pull, file-restore, RRD by @luthermonson in #296
• feat: wrap /access/tfa and /access/openid — modern TFA + OIDC login by @luthermonson in #295
• feat: wrap /nodes/{node}/disks/* — list, SMART, GPT/wipe, directory/LVM/LVM-thin/ZFS CRUD by @luthermonson in #293
• feat: wrap /cluster/jobs — realm-sync CRUD + schedule-analyze by @luthermonson in #294
• fix: UnlockTFA calls PUT /access/users/{userid}/unlock-tfa by @luthermonson in #299
• feat(mage): endpoints — snapshot PVE API surface + coverage diff by @luthermonson in #298
• fix(mage): endpoints:coverage recognizes url.URL{Path:...}.String() pattern by @luthermonson in #300
• feat: nodes/qemu → 99% (100% real) — combined sweep of #301-#305 by @luthermonson in #306
• feat: nodes/ceph → 100% — combined sweep by @luthermonson in #307
• refactor: node replication → node.Replication(id) + *NodeReplicationJob instance methods by @luthermonson in #308
• refactor: node services → node.Service(name) + *NodeService instance methods by @luthermonson in #309
• docs(agents): codify the singleton-vs-instance-type rule for new endpoints by @luthermonson in #312
• feat: nodes/lxc → 100% (98.4% tool / 100% real) + scanner fix for *WithParams by @luthermonson in #313
• feat: wrap /nodes/{node}/sdn — runtime status (12 endpoints) by @luthermonson in #314
• feat: wrap nodes/{scan,capabilities,hardware} read-only endpoints by @luthermonson in #315
• feat: wrap the 'loose' /nodes/{node}/* endpoints + storage extras by @luthermonson in #316
• feat: wrap remaining /access/* endpoints by @luthermonson in #317
• Fix SDN zone nodes unmarshaling and add Peers field with test cases by @kernel-sanders in #297

Full Changelog: v0.5.1...v0.6.0

v0.6.0

Compare

Choose a tag to compare

Full Changelog: v0.5.0...v0.5.1

• pins go-diskfs at v1.9.3 to fix joliet bugs

v0.5.1

Compare

Choose a tag to compare

What's Changed

• feat: add Joliet extension to cloud-init ISO for Windows support by @luthermonson in #256
• feat: Query vm hostname by @handsomexdd1024 in #190
• fix: ensure log watcher channel is closed when task is no longer running by @aisbergg in #255

New Contributors

• @handsomexdd1024 made their first contribution in #190
• @aisbergg made their first contribution in #255

Full Changelog: v0.4.1...v0.5.0

v0.5.0

Compare

Choose a tag to compare

What's Changed

• Update VNet Tag type to uint32 and add max VNet Tag test case by @kernel-sanders in #244
• Fix json struct tags for Container by @cmrtdev in #252
• Implement custom UnmarshalJSON method for VirtualMachineConfig by @kernel-sanders in #250
• Fix lxc/reize by using PUT instead of POST by @ptxmac in #247
• fix: session expiration time by @sergelogvinov in #239
• fix domain.Sync API path issue by @ltcptgeneral in #246
• feat: add alias field to VNet and VM Monitor Endpoint by @Melkor333 in #253

New Contributors

• @cmrtdev made their first contribution in #252
• @ptxmac made their first contribution in #247
• @ltcptgeneral made their first contribution in #246
• @Melkor333 made their first contribution in #253

Full Changelog: v0.4.0...v0.4.1

v0.4.1

Compare

Choose a tag to compare

What's Changed

• fix: vm merge devices by @sergelogvinov in #232
• Switch AgentExecStatus.OutTruncated to IntOrBool by @aeber in #231
• fixing pve8 unit test mocks by @luthermonson in #233
• adding pve9 mocks by @luthermonson in #234
• adding more test coverage by @luthermonson in #235
• adding cluster firewall coverage by @luthermonson in #236
• add large storage support by @luthermonson in #237
• bumping golang version in mod file by @luthermonson in #238
• feat: add Ping method to Container for retrieving current status by @alperencelik in #240
• fixing unmarshalling bug with new custom storage unmarshaller by @luthermonson in #243

New Contributors

• @aeber made their first contribution in #231

Full Changelog: v0.3.2...v0.3.3

v0.4.0

Compare

Choose a tag to compare

What's Changed

• fix: simplify network interface retrieval in AgentGetNetworkIFaces by @alperencelik in #230
• Add import content type by @ianberinger in #229

New Contributors

• @ianberinger made their first contribution in #229

Full Changelog: v0.3.1...v0.3.2

v0.3.2

Compare

Choose a tag to compare