proxmox

package module
v0.0.6 Latest Latest
Warning

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

 Go to latest Published: Aug 17, 2025 License: MIT Imports: 9 Imported by: 0

README

go-proxmox

Go Report Card codecov Go Reference

This is an API client library for Proxmox VE servers. It aims to be simple to use and consume in your own Go programs, make very little assumptions about how the user would consume it, and use as few non-stdlib dependencies to do so as possible.

This is currently tested against Proxmox VE 8.x systems.

This library is in its early development phase. Minor changes may be made in its usage, and only a portion of API methods are currently supported. See the CONTRIBUTING.md for details on contributing new methods to this library. Or make an Issue to discuss it.

Usage

This API client library currently supports API tokens for authentication.

import proxmox "github.com/starttoaster/go-proxmox"

// Create a new API client using a Proxmox API token
c, _ := proxmox.NewClient(tokenID, token, proxmox.WithBaseURL("https://10.0.0.10:8006/"))

// Retrieve cluster nodes
nodes, _, _ := c.Nodes.GetNodes()

// Retrieve the status of a node named server1
node, _, _ := c.Nodes.GetNodeStatus("server1")

// Retrieve the version of a node named server1
version, _, _ := c.Nodes.GetNodeVersion("server1")
Insecure API servers

If your PVE server's TLS can't be verified, you can pass an insecure HTTP client to the library.

httpClient := http.Client{
	Transport: &http.Transport{
		TLSClientConfig: &tls.Config{
			InsecureSkipVerify: true,
		},
	},
}

c, _ := proxmox.NewClient(tokenID, token, 
    proxmox.WithBaseURL("https://10.0.0.10:8006/"), 
    proxmox.WithHTTPClient(&httpClient),
)

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type BootInfo 

type BootInfo struct {
	Mode       string `json:"mode"`
	SecureBoot int    `json:"secureboot"`
}

BootInfo info about host boot

type CPUInfo 

type CPUInfo struct {
	Cores   int    `json:"cores"`
	CPUs    int    `json:"cpus"`
	Flags   string `json:"flags"`
	HVM     string `json:"hvm"`
	MHz     string `json:"mhz"`
	Model   string `json:"model"`
	Sockets int    `json:"sockets"`
	UserHz  int    `json:"user_hz"`
}

CPUInfo info about host CPU

type CephHealthStatus added in v0.0.5 

type CephHealthStatus struct {
	Status string `json:"status"`
}

CephHealthStatus status of ceph health

type Client 

type Client struct {

	// Services for each resource in the Proxmox API
	Nodes   *NodeService
	Cluster *ClusterService
	// contains filtered or unexported fields
}

Client for the Proxmox API

func NewClient 

func NewClient(tokenID string, token string, options ...ClientOptionFunc) (*Client, error)

NewClient returns a new Proxmox API client

func (*Client) Do 

func (c *Client) Do(req *http.Request, v interface{}) (*http.Response, error)

Do sends an API request. The response is stored in the value 'v' or returned as an error. If v implements the io.Writer interface, the raw response body will be written to v, without json decoding it.

func (*Client) NewRequest 

func (c *Client) NewRequest(method, path string, opt interface{}) (*http.Request, error)

NewRequest creates a new request. Method should be a valid http request method. Path should be an API path relative to the client's base URL. Path should not have a preceding '/' If specified, the value pointed to by opt is encoded into the query string of the URL.

type ClientOptionFunc 

type ClientOptionFunc func(*Client) error

ClientOptionFunc can be used to customize a new Proxmox API client

func WithBaseURL 

func WithBaseURL(urlStr string) ClientOptionFunc

WithBaseURL sets the URL for API requests to something other than localhost. API path is applied automatically if unspecified. Default: "https://localhost:8006/"

func WithHTTPClient 

func WithHTTPClient(client *http.Client) ClientOptionFunc

WithHTTPClient sets the HTTP client for API requests to something other than the default Go http Client

type ClusterService 

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

ClusterService is the service that encapsulates node API methods

func (*ClusterService) GetClusterCephStatus added in v0.0.5 

func (s *ClusterService) GetClusterCephStatus() (*GetClusterCephStatusResponse, *http.Response, error)

GetClusterCephStatus makes a GET request to the /cluster/resources endpoint https://pve.proxmox.com/pve-docs/api-viewer/index.html#/cluster/resources

func (*ClusterService) GetClusterResources added in v0.0.2 

func (s *ClusterService) GetClusterResources() (*GetClusterResourcesResponse, *http.Response, error)

GetClusterResources makes a GET request to the /cluster/resources endpoint https://pve.proxmox.com/pve-docs/api-viewer/index.html#/cluster/resources

func (*ClusterService) GetClusterStatus 

func (s *ClusterService) GetClusterStatus() (*GetClusterStatusResponse, *http.Response, error)

GetClusterStatus makes a GET request to the /cluster/status endpoint https://pve.proxmox.com/pve-docs/api-viewer/index.html#/cluster/status

type CurrentKernel 

type CurrentKernel struct {
	Machine string `json:"machine"`
	Release string `json:"release"`
	SysName string `json:"sysname"`
	Version string `json:"version"`
}

CurrentKernel info about host kernel

type GetClusterCephStatusData added in v0.0.5 

type GetClusterCephStatusData struct {
	Health CephHealthStatus `json:"health"`
}

GetClusterCephStatusData contains data of a ceph cluster's status from GetClusterCephStatus

type GetClusterCephStatusResponse added in v0.0.5 

type GetClusterCephStatusResponse struct {
	Data GetClusterCephStatusData `json:"data"`
}

GetClusterCephStatusResponse contains the response for the /cluster/ceph/status endpoint

type GetClusterResourcesData added in v0.0.2 

type GetClusterResourcesData struct {
	ID         string       `json:"id"`
	Node       string       `json:"node"`
	Status     string       `json:"status"`
	Type       string       `json:"type"`
	CPU        *float64     `json:"cpu"`
	Disk       *int         `json:"disk"`
	DiskRead   *int         `json:"diskread"`
	DiskWrite  *int         `json:"diskwrite"`
	MaxCPU     *int         `json:"maxcpu"`
	MaxDisk    *int         `json:"maxdisk"`
	MaxMem     *int         `json:"maxmem"`
	Mem        *int         `json:"mem"`
	Name       *string      `json:"name"`
	NetIn      *int         `json:"netin"`
	NetOut     *int         `json:"netout"`
	Template   *int         `json:"template"`
	Uptime     *int         `json:"uptime"`
	VMID       *IntOrString `json:"vmid"`
	HAState    *string      `json:"hastate"`
	CgroupMode *int         `json:"cgroup-mode"`
	Level      *string      `json:"level"`
	Content    *string      `json:"content"`
	PluginType *string      `json:"plugintype"`
	Shared     *int         `json:"shared"`
	Storage    *string      `json:"storage"`
	SDN        *string      `json:"sdn"`
}

GetClusterResourcesData contains data of a cluster's resources from GetClusterResources

type GetClusterResourcesResponse added in v0.0.2 

type GetClusterResourcesResponse struct {
	Data []GetClusterResourcesData `json:"data"`
}

GetClusterResourcesResponse contains the response for the /cluster/resources endpoint

type GetClusterStatusData 

type GetClusterStatusData struct {
	ID      string  `json:"id"`
	Name    string  `json:"name"`
	Type    string  `json:"type"`
	IP      *string `json:"ip"`
	Level   *string `json:"level"`
	Local   *int    `json:"local"`
	NodeID  *int    `json:"nodeid"`
	Online  *int    `json:"online"`
	Quorate *int    `json:"quorate"`
	Version *int    `json:"version"`
}

GetClusterStatusData contains data of a cluster's status from GetClusterStatus

type GetClusterStatusResponse 

type GetClusterStatusResponse struct {
	Data []GetClusterStatusData `json:"data"`
}

GetClusterStatusResponse contains the response for the /cluster/status endpoint

type GetNodeCertificatesInfoData 

type GetNodeCertificatesInfoData struct {
	Filename      string   `json:"filename"`
	Fingerprint   string   `json:"fingerprint"`
	Issuer        string   `json:"issuer"`
	NotAfter      int      `json:"notafter"`
	NotBefore     int      `json:"notbefore"`
	PEM           string   `json:"pem"`
	PublicKeyBits int      `json:"public-key-bits"`
	PublicKeyType string   `json:"public-key-type"`
	San           []string `json:"san"`
	Subject       string   `json:"subject"`
}

GetNodeCertificatesInfoData contains data of certificates from a GetNodeCertificatesInfo response

type GetNodeCertificatesInfoResponse 

type GetNodeCertificatesInfoResponse struct {
	Data []GetNodeCertificatesInfoData `json:"data"`
}

GetNodeCertificatesInfoResponse contains the response for the /nodes/{node}/disks/list endpoint

type GetNodeDisksListData 

type GetNodeDisksListData struct {
	ByIDLink     string      `json:"by_id_link"`
	DevPath      string      `json:"devpath"`
	GPT          int         `json:"gpt"`
	Health       string      `json:"health"`
	Model        string      `json:"model"`
	RPM          IntOrString `json:"rpm"`
	Serial       string      `json:"serial"`
	Size         int         `json:"size"`
	Type         string      `json:"type"`
	Used         string      `json:"used"`
	Vendor       string      `json:"vendor"`
	WWN          string      `json:"wwn"`
	Wearout      IntOrString `json:"wearout"`
	Bluestore    int         `json:"bluestore,omitempty"`
	OSDEncrypted int         `json:"osdencrypted,omitempty"`
}

GetNodeDisksListData contains data of disks from a GetNodeDisksList response

type GetNodeDisksListResponse 

type GetNodeDisksListResponse struct {
	Data []GetNodeDisksListData `json:"data"`
}

GetNodeDisksListResponse contains the response for the /nodes/{node}/disks/list endpoint

type GetNodeLxcData 

type GetNodeLxcData struct {
	CPU       float64     `json:"cpu"`
	CPUs      int         `json:"cpus"`
	Disk      int         `json:"disk"`
	DiskRead  int         `json:"diskread"`
	DiskWrite int         `json:"diskwrite"`
	MaxDisk   int         `json:"maxdisk"`
	MaxMem    int         `json:"maxmem"`
	MaxSwap   int         `json:"maxswap"`
	Mem       int         `json:"mem"`
	Name      string      `json:"name"`
	NetIn     int         `json:"netin"`
	NetOut    int         `json:"netout"`
	Status    string      `json:"status"`
	Type      string      `json:"type"`
	Uptime    int         `json:"uptime"`
	VMID      IntOrString `json:"vmid"`
	Tags      string      `json:"tags"`
}

GetNodeLxcData contains data of one VM from a GetNodeLxc response

type GetNodeLxcResponse 

type GetNodeLxcResponse struct {
	Data []GetNodeLxcData `json:"data"`
}

GetNodeLxcResponse contains the response for the /nodes/{node}/lxc endpoint

type GetNodeQemuData 

type GetNodeQemuData struct {
	CPU       float64     `json:"cpu"`
	CPUs      int         `json:"cpus"`
	Disk      int         `json:"disk"`
	DiskRead  int         `json:"diskread"`
	DiskWrite int         `json:"diskwrite"`
	MaxDisk   int         `json:"maxdisk"`
	MaxMem    int         `json:"maxmem"`
	Mem       int         `json:"mem"`
	Name      string      `json:"name"`
	NetIn     int         `json:"netin"`
	NetOut    int         `json:"netout"`
	PID       int         `json:"pid"`
	Status    string      `json:"status"`
	Uptime    int         `json:"uptime"`
	VMID      IntOrString `json:"vmid"`
	Tags      string      `json:"tags"`
}

GetNodeQemuData contains data of one VM from a GetNodeQemu response

type GetNodeQemuResponse 

type GetNodeQemuResponse struct {
	Data []GetNodeQemuData `json:"data"`
}

GetNodeQemuResponse contains the response for the /nodes/{node}/qemu endpoint

type GetNodeStatusData 

type GetNodeStatusData struct {
	BootInfo      BootInfo      `json:"boot-info"`
	CPU           float64       `json:"cpu"`
	CPUInfo       CPUInfo       `json:"cpuinfo"`
	CurrentKernel CurrentKernel `json:"current-kernel"`
	Idle          int           `json:"idle"`
	KSM           KSM           `json:"ksm"`
	Kversion      string        `json:"kversion"`
	LoadAvg       []string      `json:"loadavg"`
	Memory        Memory        `json:"memory"`
	PveVersion    string        `json:"pveversion"`
	RootFs        RootFS        `json:"rootfs"`
	Swap          Swap          `json:"swap"`
	Uptime        int           `json:"uptime"`
	Wait          float64       `json:"wait"`
}

GetNodeStatusData contains data of one node from a GetNode response

type GetNodeStatusResponse 

type GetNodeStatusResponse struct {
	Data GetNodeStatusData `json:"data"`
}

GetNodeStatusResponse contains the response for the /nodes/{node}/status endpoint

type GetNodeStorageData 

type GetNodeStorageData struct {
	Active       int     `json:"active"`
	Avail        int     `json:"avail"`
	Content      string  `json:"content"`
	Enabled      int     `json:"enabled"`
	Shared       int     `json:"shared"`
	Storage      string  `json:"storage"`
	Total        int     `json:"total"`
	Type         string  `json:"type"`
	Used         int     `json:"used"`
	UsedFraction float64 `json:"used_fraction"`
}

GetNodeStorageData contains data of certificates from a GetNodeStorage response

type GetNodeStorageResponse 

type GetNodeStorageResponse struct {
	Data []GetNodeStorageData `json:"data"`
}

GetNodeStorageResponse contains the response for the /nodes/{node}/storage endpoint

type GetNodeVersionData 

type GetNodeVersionData struct {
	Release string `json:"release"`
	RepoID  string `json:"repoid"`
	Version string `json:"version"`
}

GetNodeVersionData contains the version data for one node from a GetNodeVersion request

type GetNodeVersionResponse 

type GetNodeVersionResponse struct {
	Data GetNodeVersionData `json:"data"`
}

GetNodeVersionResponse contains the response for the /nodes/{node}/version endpoint

type GetNodesData 

type GetNodesData struct {
	CPU            float64 `json:"cpu"`
	Disk           int     `json:"disk"`
	ID             string  `json:"id"`
	Level          string  `json:"level"`
	MaxCPU         int     `json:"maxcpu"`
	MaxDisk        int     `json:"maxdisk"`
	MaxMem         int     `json:"maxmem"`
	Mem            int     `json:"mem"`
	Node           string  `json:"node"`
	SSLFingerprint string  `json:"ssl_fingerprint"`
	Status         string  `json:"status"`
	Type           string  `json:"type"`
	Uptime         int     `json:"uptime"`
}

GetNodesData contains data of one node from a GetNodes response

type GetNodesResponse 

type GetNodesResponse struct {
	Data []GetNodesData `json:"data"`
}

GetNodesResponse contains the response for the /nodes endpoint

type IntOrString added in v0.0.3 

type IntOrString string

IntOrString is an alias for some returns from the Proxmox API where we've identified that some versions return a string, and others return an integer For example, LXC VMIDs were a string return in PVE 8.1.x, and are an integer in 8.2.x Since it can be either depending on the version of Proxmox queried, we're going to return the looser type. String in this case.

func (*IntOrString) UnmarshalJSON added in v0.0.3 

func (is *IntOrString) UnmarshalJSON(data []byte) error

UnmarshalJSON implements the json.Unmarshaler interface for IntOrString types

type KSM added in v0.0.3 

type KSM struct {
	Shared int `json:"shared"`
}

KSM info about Kernel same-page merging

type Memory 

type Memory struct {
	Free  int `json:"free"`
	Total int `json:"total"`
	Used  int `json:"used"`
}

Memory info about host memory

type NodeService 

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

NodeService is the service that encapsulates node API methods

func (*NodeService) GetNodeCertificatesInfo 

func (s *NodeService) GetNodeCertificatesInfo(name string) (*GetNodeCertificatesInfoResponse, *http.Response, error)

GetNodeCertificatesInfo makes a GET request to the /nodes/{node}/certificates/info endpoint https://pve.proxmox.com/pve-docs/api-viewer/index.html#/nodes/{node}/certificates/info

func (*NodeService) GetNodeDisksList 

func (s *NodeService) GetNodeDisksList(name string) (*GetNodeDisksListResponse, *http.Response, error)

GetNodeDisksList makes a GET request to the /nodes/{node}/disks/list endpoint https://pve.proxmox.com/pve-docs/api-viewer/index.html#/nodes/{node}/disks/list

func (*NodeService) GetNodeLxc 

func (s *NodeService) GetNodeLxc(name string) (*GetNodeLxcResponse, *http.Response, error)

GetNodeLxc makes a GET request to the /nodes/{node}/lxc endpoint https://pve.proxmox.com/pve-docs/api-viewer/index.html#/nodes/{node}/lxc

func (*NodeService) GetNodeQemu 

func (s *NodeService) GetNodeQemu(name string) (*GetNodeQemuResponse, *http.Response, error)

GetNodeQemu makes a GET request to the /nodes/{node}/qemu endpoint https://pve.proxmox.com/pve-docs/api-viewer/index.html#/nodes/{node}/qemu

func (*NodeService) GetNodeStatus 

func (s *NodeService) GetNodeStatus(name string) (*GetNodeStatusResponse, *http.Response, error)

GetNodeStatus makes a GET request to the /nodes/{node}/status endpoint This returns more information about a node than the /nodes endpoint https://pve.proxmox.com/pve-docs/api-viewer/index.html#/nodes/{node}/status

func (*NodeService) GetNodeStorage 

func (s *NodeService) GetNodeStorage(name string) (*GetNodeStorageResponse, *http.Response, error)

GetNodeStorage makes a GET request to the /nodes/{node}/storage endpoint https://pve.proxmox.com/pve-docs/api-viewer/index.html#/nodes/{node}/storage

func (*NodeService) GetNodeVersion 

func (s *NodeService) GetNodeVersion(name string) (*GetNodeVersionResponse, *http.Response, error)

GetNodeVersion makes a GET request to the /nodes/{node}/version endpoint https://pve.proxmox.com/pve-docs/api-viewer/index.html#/nodes/{node}/version

func (*NodeService) GetNodes 

func (s *NodeService) GetNodes() (*GetNodesResponse, *http.Response, error)

GetNodes makes a GET request to the /nodes endpoint https://pve.proxmox.com/pve-docs/api-viewer/index.html#/nodes

type RootFS added in v0.0.3 

type RootFS struct {
	Avail int `json:"avail"`
	Free  int `json:"free"`
	Total int `json:"total"`
	Used  int `json:"used"`
}

RootFS info about the host root filesystem

type Swap 

type Swap struct {
	Free  int `json:"free"`
	Total int `json:"total"`
	Used  int `json:"used"`
}

Swap info about swap

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.