goproxmox

package module
v0.3.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 10, 2026 License: Apache-2.0 Imports: 16 Imported by: 17

README

GO Proxmox

GO Proxmox is a Go client library for interacting with the Proxmox VE API. It provides a simple and efficient way to manage Proxmox virtual environments programmatically using Go.

It reuses the excellent Go-Proxmox library as its foundation.

This repository was created to share common functions between projects:

Documentation

Overview

Package goproxmox implements a proxmox api client.

Index

Constants

This section is empty.

Variables

View Source 
var (
	// ErrNodeNotFound is returned when a node is not found.
	ErrNodeNotFound = errors.New("node not found")

	// ErrVirtualMachineNotFound is returned when a virtual machine is not found.
	ErrVirtualMachineNotFound = errors.New("VM machine not found")
	// ErrVirtualMachineTemplateNotFound is returned when a virtual machine template is not found.
	ErrVirtualMachineTemplateNotFound = errors.New("VM template not found")
	// ErrVirtualMachineUnreachable is returned when a virtual machine is unreachable. And it has unknown status.
	ErrVirtualMachineUnreachable = errors.New("VM machine unreachable")

	// ErrNotFound is returned when a resource is not found.
	ErrNotFound = errors.New("not found")
)

Functions

func ClusterReadyLocal added in v0.3.0 

func ClusterReadyLocal(ctx context.Context) (bool, error)

func CreateLocalVM added in v0.2.0 

func CreateLocalVM(ctx context.Context, vmID int, options map[string]any) error

func DeleteLocalVM added in v0.2.0 

func DeleteLocalVM(ctx context.Context, vmID int) error

func GetLocalNextID added in v0.2.0 

func GetLocalNextID(ctx context.Context) (int, error)

GetLocalNextID retrieves the next available VM ID.

func GetLocalVMConfig added in v0.2.0 

func GetLocalVMConfig(vmID int) (*proxmox.VirtualMachineConfig, error)

GetLocalVMConfig retrieves the configuration of a VM by its ID.

func GetLocalVMConfigByFilter added in v0.2.0 

func GetLocalVMConfigByFilter(filter ...func(*proxmox.VirtualMachineConfig) (bool, error)) (int, *proxmox.VirtualMachineConfig, error)

func GetVMSKU 

func GetVMSKU(vm *proxmox.VirtualMachine) string

GetVMSKU returns the VM instance type name.

func GetVMUUID 

func GetVMUUID(vm *proxmox.VirtualMachine) string

GetVMUUID returns the VM UUID.

func NewIntOrBool 

func NewIntOrBool(b bool) *proxmox.IntOrBool

NewIntOrBool creates a new IntOrBool pointer from a boolean value.

func UpdateLocalVM added in v0.2.0 

func UpdateLocalVM(ctx context.Context, vmID int, options map[string]any) error

Types

type APIClient 

type APIClient struct {
	*proxmox.Client
	// contains filtered or unexported fields
}

APIClient Proxmox API client object.

func NewAPIClient 

func NewAPIClient(url string, options ...proxmox.Option) (*APIClient, error)

NewAPIClient initializes a GO-Proxmox API client.

func (*APIClient) AttachVMDisk 

func (c *APIClient) AttachVMDisk(ctx context.Context, vmID int, device, disk string) error

AttachVMDisk attaches an existing disk to the virtual machine.

func (*APIClient) CloneVM 

func (c *APIClient) CloneVM(ctx context.Context, templateID int, options VMCloneRequest) (int, error)

CloneVM clones a VM template to create a new VM with the specified options.

func (*APIClient) CreateVM 

func (c *APIClient) CreateVM(ctx context.Context, node string, options map[string]interface{}) error

CreateVM creates a new VM on the specified node with the given configuration.

func (*APIClient) CreateVMDisk 

func (c *APIClient) CreateVMDisk(ctx context.Context, vmid int, node string, storage string, disk string, sizeBytes int64) (string, error)

CreateVMDisk creates a new disk for the virtual machine.

func (*APIClient) CreateVMFirewallRules 

func (c *APIClient) CreateVMFirewallRules(ctx context.Context, vmID int, nodeName string, rules []*proxmox.FirewallRule) error

CreateVMFirewallRules creates firewall rules for the specified virtual machine.

func (*APIClient) DeleteVMByID 

func (c *APIClient) DeleteVMByID(ctx context.Context, nodeName string, vmID int) error

DeleteVMByID deletes a VM by its ID.

If the VM is running it is stopped first. We wait for the stop task to complete before issuing the delete so qemu-server has released the /var/lock/qemu-server/lock-<vmid>.conf file; otherwise the destroy task races against the still-running stop and fails with "can't lock file '/var/lock/qemu-server/lock-<vmid>.conf' - got timeout", leaving an orphan VM behind.

func (*APIClient) DeleteVMDisk 

func (c *APIClient) DeleteVMDisk(ctx context.Context, node string, storage string, disk string) error

DeleteVMDisk deletes a disk from the virtual machine.

func (*APIClient) DetachVMDisk 

func (c *APIClient) DetachVMDisk(ctx context.Context, vmID int, device string) error

DetachVMDisk detaches a disk from the virtual machine.

func (*APIClient) GetClusterStorage 

func (c *APIClient) GetClusterStorage(ctx context.Context, storage string) (*proxmox.ClusterResource, error)

GetClusterStorage returns the cluster storage resource by name.

func (*APIClient) GetClusterStoragesByFilter 

func (c *APIClient) GetClusterStoragesByFilter(ctx context.Context, filter ...func(*proxmox.ClusterResource) (bool, error)) (storages proxmox.ClusterResources, err error)

GetClusterStoragesByFilter returns cluster storage resources by applying the provided filter functions.

func (*APIClient) GetHAGroupList 

func (c *APIClient) GetHAGroupList(ctx context.Context) (groups []*HAGroup, err error)

GetHAGroupList retrieves the list of HA groups in the cluster.

func (*APIClient) GetNextID 

func (c *APIClient) GetNextID(ctx context.Context, vmid int) (int, error)

GetNextID retrieves the next available VM ID.

func (*APIClient) GetNodeByName added in v0.2.0 

func (c *APIClient) GetNodeByName(ctx context.Context, nodeName string) (*proxmox.ClusterResource, error)

func (*APIClient) GetNodeList 

func (c *APIClient) GetNodeList(ctx context.Context) ([]string, error)

GetNodeList returns a list of all node names in the cluster.

func (*APIClient) GetNodeListByFilter 

func (c *APIClient) GetNodeListByFilter(ctx context.Context, filter ...func(*proxmox.ClusterResource) (bool, error)) (nodes proxmox.ClusterResources, err error)

GetNodeListByFilter get cluster node resources by applying the provided filter functions.

func (*APIClient) GetNodesForStorage 

func (c *APIClient) GetNodesForStorage(ctx context.Context, storage string) ([]string, error)

GetNodesForStorage returns the node name list where the storage is available.

func (*APIClient) GetStorageContent 

func (c *APIClient) GetStorageContent(ctx context.Context, node string, storage string) (content []*proxmox.StorageContent, err error)

GetStorageContent returns the storage content for a given storage on a given node.

func (*APIClient) GetStorageListByFilter 

func (c *APIClient) GetStorageListByFilter(ctx context.Context, filter ...func(*proxmox.ClusterStorage) (bool, error)) (proxmox.ClusterStorages, error)

GetStorageListByFilter get cluster storage list by applying the provided filter functions.

func (*APIClient) GetStorageStatus 

func (c *APIClient) GetStorageStatus(ctx context.Context, node string, storage string) (st proxmox.Storage, err error)

GetStorageStatus returns the storage status for a given storage on a given node.

func (*APIClient) GetVMByFilter 

func (c *APIClient) GetVMByFilter(ctx context.Context, filter ...func(*proxmox.ClusterResource) (bool, error)) (*proxmox.ClusterResource, error)

GetVMByFilter returns a VM cluster resource by applying the provided filter functions.

func (*APIClient) GetVMByID 

func (c *APIClient) GetVMByID(ctx context.Context, vmID uint64) (*proxmox.ClusterResource, error)

GetVMByID returns a VM cluster resource by its ID.

func (*APIClient) GetVMConfig 

func (c *APIClient) GetVMConfig(ctx context.Context, vmID int) (*proxmox.VirtualMachine, error)

GetVMConfig retrieves the configuration of a VM by its ID.

func (*APIClient) GetVMTemplateByID 

func (c *APIClient) GetVMTemplateByID(ctx context.Context, vmID uint64) (*proxmox.ClusterResource, error)

GetVMTemplateByID returns a VM cluster resource by its ID.

func (*APIClient) GetVMTemplateConfig 

func (c *APIClient) GetVMTemplateConfig(ctx context.Context, vmID int) (*proxmox.VirtualMachine, error)

GetVMTemplateConfig retrieves the configuration of a VM template by its ID.

func (*APIClient) GetVMTemplatesByFilter 

func (c *APIClient) GetVMTemplatesByFilter(ctx context.Context, filter ...func(*proxmox.ClusterResource) (bool, error)) (proxmox.ClusterResources, error)

GetVMTemplatesByFilter returns a VM cluster resource by applying the provided filter functions. nolint: dupl

func (*APIClient) GetVMsByFilter 

func (c *APIClient) GetVMsByFilter(ctx context.Context, filter ...func(*proxmox.ClusterResource) (bool, error)) (proxmox.ClusterResources, error)

GetVMsByFilter returns a VM cluster resource by applying the provided filter functions. nolint: dupl

func (*APIClient) MigrateVMByID 

func (c *APIClient) MigrateVMByID(ctx context.Context, vmID int, dstNode string, online bool) error

MigrateVMByID migrates a VM to another node by its ID.

func (*APIClient) RegenerateVMCloudInit 

func (c *APIClient) RegenerateVMCloudInit(ctx context.Context, node string, vmID int) error

RegenerateVMCloudInit regenerates the Cloud-Init configuration for a VM.

func (*APIClient) ResizeVMDisk 

func (c *APIClient) ResizeVMDisk(ctx context.Context, vmID int, node, disk, size string) error

ResizeVMDisk resizes a disk for the virtual machine.

func (*APIClient) StartVMByID 

func (c *APIClient) StartVMByID(ctx context.Context, nodeName string, vmID int) (*proxmox.VirtualMachine, error)

StartVMByID starts a VM by its ID.

func (*APIClient) UpdateVMByID added in v0.2.0 

func (c *APIClient) UpdateVMByID(ctx context.Context, nodeName string, vmID int, options map[string]interface{}) error

UpdateVMByID updates an existing VM on the specified node with the given configuration.

func (*APIClient) UpdateVMFirewallRules 

func (c *APIClient) UpdateVMFirewallRules(ctx context.Context, vmID int, nodeName string, rules []*proxmox.FirewallRule) error

UpdateVMFirewallRules updates firewall rules for the specified virtual machine.

type HAGroup 

type HAGroup struct {
	Group      string             `json:"group"`
	Nodes      string             `json:"nodes"`
	Comment    string             `json:"comment,omitempty"`
	NoFailback *proxmox.IntOrBool `json:"nofailback,omitempty"`
	Restricted *proxmox.IntOrBool `json:"restricted,omitempty"`
	Type       string             `json:"type,omitempty"`
}

HAGroup represents a High Availability group configuration.

type NUMANodeState added in v0.2.0 

type NUMANodeState struct {
	CPUs   string `json:"cpus"`
	Memory uint64 `json:"memory,omitempty"` // in MiB
	Policy string `json:"policy,omitempty"`
}

NUMANodeState represents the state of a NUMA node for a VM.

type VMCPU 

type VMCPU struct {
	Flags []string `json:"flags,omitempty"`
	Type  string   `json:"cputype,omitempty"`
}

VMCPU represents the CPU configuration of a VM.

func (*VMCPU) ToString 

func (r *VMCPU) ToString() (string, error)

ToString converts the VMCPU struct to its string representation.

func (*VMCPU) UnmarshalString 

func (r *VMCPU) UnmarshalString(s string) error

type VMCloneRequest 

type VMCloneRequest struct {
	Node        string `json:"node"`
	NewID       int    `json:"newid"`
	Name        string `json:"name"`
	Description string `json:"description,omitempty"`
	Full        uint8  `json:"full,omitempty"`
	Pool        string `json:"pool,omitempty"`
	Storage     string `json:"storage,omitempty"`

	CPU          int                   `json:"cpu,omitempty"`
	CPUAffinity  string                `json:"cpuAffinity,omitempty"`
	Memory       uint32                `json:"memory,omitempty"`
	NUMANodes    map[int]NUMANodeState `json:"numanodes,omitempty"`
	DiskSize     string                `json:"diskSize,omitempty"`
	Tags         string                `json:"tags,omitempty"`
	InstanceType string                `json:"instanceType,omitempty"`
}

VMCloneRequest represents a request to clone a virtual machine.

type VMCloudInitIPConfig 

type VMCloudInitIPConfig struct {
	GatewayIPv4 string `json:"gw,omitempty"`
	GatewayIPv6 string `json:"gw6,omitempty"`
	IPv4        string `json:"ip,omitempty"`
	IPv6        string `json:"ip6,omitempty"`
}

VMCloudInitIPConfig represents the cloud-init IP configuration for a VM.

func (*VMCloudInitIPConfig) ToString 

func (r *VMCloudInitIPConfig) ToString() (string, error)

ToString converts the VMCloudInitIPConfig struct to its string representation.

func (*VMCloudInitIPConfig) UnmarshalString 

func (r *VMCloudInitIPConfig) UnmarshalString(s string) error

type VMHostPCI 

type VMHostPCI struct {
	DeviceID string             `json:"device-id,omitempty"`
	Mapping  string             `json:"mapping,omitempty"`
	MDev     string             `json:"mdev,omitempty"`
	PCIe     *proxmox.IntOrBool `json:"pcie,omitempty"`
	RomBar   *proxmox.IntOrBool `json:"rombar,omitempty"`
	RomFile  string             `json:"romfile,omitempty"`
	XVGA     *proxmox.IntOrBool `json:"x-vga,omitempty"`
}

VMHostPCI represents a PCI device passthrough configuration for a VM.

func (*VMHostPCI) ToString 

func (r *VMHostPCI) ToString() (string, error)

ToString converts the VMHostPCI struct to its string representation.

func (*VMHostPCI) UnmarshalString 

func (r *VMHostPCI) UnmarshalString(s string) error

type VMNUMA added in v0.2.0 

type VMNUMA struct {
	CPUIDs        []string `json:"cpus,omitempty"`
	HostNodeNames []string `json:"hostnodes,omitempty"`
	Memory        *int     `json:"memory,omitempty"` // in MiB
	Policy        string   `json:"policy,omitempty"`
}

VMNUMA represents a NUMA node configuration for a VM.

func (*VMNUMA) ToString added in v0.2.0 

func (r *VMNUMA) ToString() (string, error)

ToString converts the VMHostPCI struct to its string representation.

func (*VMNUMA) UnmarshalString added in v0.2.0 

func (r *VMNUMA) UnmarshalString(s string) error

type VMNetworkDevice 

type VMNetworkDevice struct {
	Virtio     string             `json:"virtio,omitempty"`
	Bridge     string             `json:"bridge,omitempty"`
	Firewall   *proxmox.IntOrBool `json:"firewall,omitempty"`
	LinkDown   *proxmox.IntOrBool `json:"link_down,omitempty"`
	MACAddress string             `json:"macaddr,omitempty"`
	MTU        *int               `json:"mtu,omitempty"`
	Model      string             `json:"model"`
	Queues     *int               `json:"queues,omitempty"`
	Tag        *int               `json:"tag,omitempty"`
	Trunks     []int              `json:"trunks,omitempty"`
}

VMNetworkDevice represents a network device configuration for a VM.

func (*VMNetworkDevice) ToString 

func (r *VMNetworkDevice) ToString() (string, error)

ToString converts the VMNetworkDevice struct to its string representation.

func (*VMNetworkDevice) UnmarshalString 

func (r *VMNetworkDevice) UnmarshalString(s string) error

type VMQemuGuestAgent 

type VMQemuGuestAgent struct {
	Enabled           proxmox.IntOrBool  `json:"enabled"`
	FreezeFsOnBackup  *proxmox.IntOrBool `json:"freeze-fs-on-backup,omitempty"`
	FsTrimClonedDisks *proxmox.IntOrBool `json:"fstrim_cloned_disks,omitempty"`
	Type              string             `json:"type,omitempty"`
}

VMQemuGuestAgent represents the configuration of the QEMU Guest Agent for a VM.

func (*VMQemuGuestAgent) ToString 

func (r *VMQemuGuestAgent) ToString() (string, error)

ToString converts the VMQemuGuestAgent struct to its string representation.

func (*VMQemuGuestAgent) UnmarshalString 

func (r *VMQemuGuestAgent) UnmarshalString(s string) error

type VMSMBIOS 

type VMSMBIOS struct {
	Base64       *proxmox.IntOrBool `json:"base64,omitempty" `
	Family       string             `json:"family,omitempty"`
	Manufacturer string             `json:"manufacturer,omitempty"`
	Product      string             `json:"product,omitempty"`
	Serial       string             `json:"serial,omitempty"`
	SKU          string             `json:"sku,omitempty"`
	UUID         string             `json:"uuid,omitempty"`
	Version      string             `json:"version,omitempty"`
}

VMSMBIOS represents the SMBIOS configuration of a VM.

func (*VMSMBIOS) ToString 

func (r *VMSMBIOS) ToString() (string, error)

ToString converts the VMSMBIOS struct to its string representation.

func (*VMSMBIOS) UnmarshalString 

func (r *VMSMBIOS) UnmarshalString(s string) error

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.