proxmoxpool

README

Proxmox Pool

Status: This project is under active development. Its API may change and breaking changes are possible. Do not use it in production yet.

go-proxmox-pool is a Go library that manages a pool of Proxmox REST clients for multiple clusters. It builds on top of go-proxmox-rest, a type-safe Go client for the Proxmox VE REST API.

Projects using this module

• Proxmox CCM
• Proxmox CSI
• Proxmox MCP server
• Karpenter for Proxmox

License

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

---

Proxmox® is a registered trademark of Proxmox Server Solutions GmbH.

Documentation

Overview

Package proxmoxpool provides a pool of github.com/sergelogvinov/go-proxmox-rest clients, one per configured Proxmox cluster: a client/cache per cluster, a fluent Cluster handle for per-cluster operations, and an opt-in, per-resource-kind TTL cache over the cluster-wide resource listing.

Index

• Variables
• type Cluster
  • func (c *Cluster) Check(ctx context.Context) error
  • func (c *Cluster) DeleteVM(ctx context.Context, vm *pxcluster.Resource) error
  • func (c *Cluster) Get(ctx context.Context, kind ResourceKind, id string) (*pxcluster.Resource, error)
  • func (c *Cluster) GetNextID(ctx context.Context, hint int) (int, error)
  • func (c *Cluster) GetNodeHAGroups(ctx context.Context, node string) ([]string, error)
  • func (c *Cluster) GetVMConfig(ctx context.Context, vmID int) (*VMDetails, error)
  • func (c *Cluster) List(ctx context.Context, kind ResourceKind, opts ...ListOption) ([]pxcluster.Resource, error)
• type ClusterConfig
• type ListOption
  • func SkipTemplates() ListOption
  • func WithMatch(fn func(*pxcluster.Resource) (bool, error)) ListOption
  • func WithStorageID(id string) ListOption
  • func WithUUID(uuid string) ListOption
  • func WithVMID(vmid int) ListOption
• type Option
  • func WithCacheTTL(kind ResourceKind, ttl time.Duration) Option
  • func WithRESTOption(opts ...proxmoxrest.Option) Option
• type ProxmoxPool
  • func NewProxmoxPool(config []*ClusterConfig, options ...Option) (*ProxmoxPool, error)
  • func (p *ProxmoxPool) Cluster(cluster string) *Cluster
  • func (p *ProxmoxPool) Get(cluster string) (*proxmoxrest.Client, error)
  • func (p *ProxmoxPool) List() []string
  • func (p *ProxmoxPool) Set(cluster string, client *proxmoxrest.Client)
• type ResourceKind
• type VMDetails

Variables

var (
	// ErrClustersNotFound is returned when no cluster configuration was
	// given to NewProxmoxPool.
	ErrClustersNotFound = errors.New("clusters not found")
	// ErrClusterNotFound is returned when a cluster name has no
	// configured client in the pool.
	ErrClusterNotFound = errors.New("cluster not found")
	// ErrInvalidClusterURL is returned when a ClusterConfig.URL using the
	// "<scheme>+srv://" convention does not encode a valid
	// _service._proto.domain SRV name.
	ErrInvalidClusterURL = errors.New("invalid cluster URL")
	// ErrHAGroupNotFound is returned when a node belongs to no HA group.
	ErrHAGroupNotFound = errors.New("ha-group not found")
	// ErrInstanceNotFound is returned when a VM/LXC instance is not found.
	ErrInstanceNotFound = errors.New("instance not found")
	// ErrNodeInaccessible is returned when a Proxmox node cannot be
	// reached or accessed.
	ErrNodeInaccessible = errors.New("node is inaccessible")
	// ErrResourceNotFound is returned by Cluster.Get when no resource
	// matches id — any ResourceKind, not just a VM/LXC instance (see
	// ErrInstanceNotFound for that narrower, guest-specific case).
	ErrResourceNotFound = errors.New("resource not found")
	// ErrZoneNotFound is returned when a zone is not found in the Proxmox
	// cluster. Currently unused by any exported method; carried forward
	// for compatibility with prior copies of this package.
	ErrZoneNotFound = errors.New("zone not found")
)

Types

type Cluster

type Cluster struct {
	// contains filtered or unexported fields
}

Cluster is a pool-bound handle scoped to one Proxmox cluster. It is cheap to create — Cluster(name) does no I/O — and holds no state of its own; the pool owns the underlying REST client and cache, so cache entries persist across separately-obtained Cluster values for the same name.

func (*Cluster) Check

func (c *Cluster) Check(ctx context.Context) error

Check probes the cluster's connectivity and permissions: it fetches the Proxmox version and lists VM resources, the same check today's CheckClusters performed per cluster.

func (*Cluster) DeleteVM

func (c *Cluster) DeleteVM(ctx context.Context, vm *pxcluster.Resource) error

DeleteVM stops (if running) and deletes a VM.

func (*Cluster) Get

func (c *Cluster) Get(ctx context.Context, kind ResourceKind, id string) (*pxcluster.Resource, error)

Get returns the single resource identified by id within kind: id is the VMID for ResourceKindVM/ResourceKindLXC, or the storage ID for ResourceKindStorage — whichever scalar identifier that kind's entries are addressed by. ResourceKindNode has none Get understands; calling Get with it (or passing a VMID that doesn't parse as an integer) is a documented no-op returning ErrResourceNotFound.

func (*Cluster) GetNextID

func (c *Cluster) GetNextID(ctx context.Context, hint int) (int, error)

GetNextID finds the next unused VMID starting at hint, incrementing and retrying on Proxmox's "already in use" (400) response, and skipping any VMID already reserved by a recent GetNextID call on this cluster (see nextIDReservationTTL) without spending an API call to find that out.

func (*Cluster) GetNodeHAGroups

func (c *Cluster) GetNodeHAGroups(ctx context.Context, node string) ([]string, error)

GetNodeHAGroups returns the sorted list of HA groups the given node belongs to, or ErrHAGroupNotFound if it belongs to none. HA groups aren't a cluster.Resources() shape, so this calls the HA API directly rather than going through Cluster.List/the resource cache.

Proxmox 9 replaced HA groups with HA rules: clusters that have been migrated reject GET /cluster/ha/groups with a 500 (see isHAGroupsMigrated), so on that specific error this falls back to listing "node-affinity" HA rules instead, which are the migrated equivalent of groups (Rule.Rule/Rule.Nodes standing in for Group.Group/Group.Nodes).

+proxmox:rbac:feature=hagroup

func (*Cluster) GetVMConfig

func (c *Cluster) GetVMConfig(ctx context.Context, vmID int) (*VMDetails, error)

GetVMConfig returns a VM's config and live status by its ID. Returns ErrNodeInaccessible if the VM's node is unreachable (reported as Status "unknown" in the cluster resource list). As a side effect, it warms the pool's UUID index whenever the VM's config carries an SMBIOS UUID, so a later WithUUID lookup for this VM is a free index hit.

+proxmox:rbac:feature=base

func (*Cluster) List

func (c *Cluster) List(ctx context.Context, kind ResourceKind, opts ...ListOption) ([]pxcluster.Resource, error)

List returns this cluster's kind-scoped resource listing, narrowed by opts. The underlying (kind, cluster) listing is cached per the pool's WithCacheTTL configuration for kind; opts are applied client-side against whatever the cache (or a live fetch, if caching is disabled) returned.

type ClusterConfig

type ClusterConfig struct {
	// Name is an optional display label — metadata only.
	Name string `yaml:"name,omitempty"`
	// Region is the selector: pool.List()/pool.Get()/pool.Cluster()
	// all key on this value.
	Region string `yaml:"region,omitempty"`

	// Proxmox REST API connection details. URL is either a plain endpoint
	// (e.g. https://10.0.0.1:8006/api2/json) or, using the
	// "<scheme>+srv://" convention, a DNS SRV name to resolve and load
	// balance across (e.g. https+srv://_pve._tcp.example.com/api2/json,
	// which looks up the "_pve._tcp.example.com" SRV record and balances
	// requests across the discovered hosts over https).
	URL string `yaml:"url"`
	// CAFile is a path, or comma-separated list of paths, to PEM CA bundle(s) to trust.
	CAFile string `yaml:"ca_file,omitempty"`

	Insecure        bool   `yaml:"insecure,omitempty"`
	TokenID         string `yaml:"token_id,omitempty"`
	TokenIDFile     string `yaml:"token_id_file,omitempty"`
	TokenSecret     string `yaml:"token_secret,omitempty"`
	TokenSecretFile string `yaml:"token_secret_file,omitempty"`
	Username        string `yaml:"username,omitempty"`
	Password        string `yaml:"password,omitempty"`
}

ClusterConfig defines a single Proxmox cluster's connection configuration.

type ListOption

type ListOption func(*listOptions)

ListOption narrows the entries Cluster.List returns.

func SkipTemplates

func SkipTemplates() ListOption

SkipTemplates excludes guests flagged as templates.

func WithMatch

func WithMatch(fn func(*pxcluster.Resource) (bool, error)) ListOption

WithMatch keeps only entries for which fn returns true. fn is evaluated against whatever Cluster.List's cache (or a live fetch) returned; an error return aborts List and is returned to the caller.

func WithStorageID

func WithStorageID(id string) ListOption

WithStorageID restricts results to the given storage ID. Meaningful for ResourceKindStorage only; ignored against other kinds.

func WithUUID

func WithUUID(uuid string) ListOption

WithUUID restricts ResourceKindVM entries to the single guest whose SMBIOS UUID matches uuid, resolved via the pool's UUID index (see resolveByUUID). Ignored against every other ResourceKind — LXC containers have no equivalent identity field.

func WithVMID

func WithVMID(vmid int) ListOption

WithVMID restricts results to the guest with the given VMID. Meaningful for ResourceKindVM/ResourceKindLXC only; ignored against other kinds.

type Option

type Option func(*poolOptions)

Option mutates a pool's construction-time configuration.

func WithCacheTTL

func WithCacheTTL(kind ResourceKind, ttl time.Duration) Option

WithCacheTTL sets the TTL used to cache Cluster.List's underlying per-(kind, cluster) listing. TTL 0 (the default) disables caching for that kind: every List call goes straight to the API. TTL applies uniformly across every cluster in the pool.

func WithRESTOption

func WithRESTOption(opts ...proxmoxrest.Option) Option

WithRESTOption forwards one or more proxmoxrest.Option values to every per-cluster proxmoxrest.New call this pool makes — the escape hatch for WithRoundRobin, WithTimeout, WithLogger, and any other client-level option not otherwise exposed here.

type ProxmoxPool

type ProxmoxPool struct {
	// contains filtered or unexported fields
}

ProxmoxPool is a pool of Proxmox REST clients, one per configured cluster, plus the shared resource cache, UUID index, and next-ID reservation cache every Cluster handle obtained from it reads and writes.

func NewProxmoxPool

func NewProxmoxPool(config []*ClusterConfig, options ...Option) (*ProxmoxPool, error)

NewProxmoxPool creates a new Proxmox cluster client pool.

func (*ProxmoxPool) Cluster

func (p *ProxmoxPool) Cluster(cluster string) *Cluster

Cluster returns a handle scoped to the named cluster. It never itself fails — no client-side existence check is performed; ErrClusterNotFound surfaces from the handle's first actual call instead.

func (*ProxmoxPool) Get

func (p *ProxmoxPool) Get(cluster string) (*proxmoxrest.Client, error)

Get returns the raw go-proxmox-rest client for the named cluster — the escape hatch for call sites that need the full client surface.

func (*ProxmoxPool) List

func (p *ProxmoxPool) List() []string

List returns the names of every cluster configured in the pool.

func (*ProxmoxPool) Set

func (p *ProxmoxPool) Set(cluster string, client *proxmoxrest.Client)

Set overrides (or injects) the REST client for a cluster. Intended for tests that point a cluster at an in-memory fake server after the pool was already built from static config.

type ResourceKind

type ResourceKind int

ResourceKind selects which shape of GET /cluster/resources entry Cluster.List/Get fetches.

const (
	// ResourceKindVM matches QEMU virtual machines.
	ResourceKindVM ResourceKind = iota
	// ResourceKindLXC matches LXC containers.
	ResourceKindLXC
	// ResourceKindNode matches cluster nodes.
	ResourceKindNode
	// ResourceKindStorage matches storages.
	ResourceKindStorage
)

type VMDetails

type VMDetails struct {
	VMID   int
	Node   string
	Name   string
	CPUs   int
	MaxMem int64
	UUID   string
	Type   string
}

VMDetails holds the VM config/status fields consumers need to build instance metadata: its node, live CPU/memory, and SMBIOS-derived UUID and instance type.