cv4pve-api-powershell

    ______                _                      __
   / ____/___  __________(_)___ _   _____  _____/ /_
  / /   / __ \/ ___/ ___/ / __ \ | / / _ \/ ___/ __/
 / /___/ /_/ / /  (__  ) / / / / |/ /  __(__  ) /_
 \____/\____/_/  /____/_/_/ /_/|___/\___/____/\__/

         Corsinvest - Proxmox VE API PowerShell

A comprehensive PowerShell module that provides everything you need to build powerful automation scripts that manage Proxmox VE infrastructure programmatically.

Part of the cv4pve suite of tools.

Quick Links: PowerShell Gallery | Documentation | Proxmox VE API

Overview

The cv4pve-api-powershell module enables system administrators and developers to manage and automate Proxmox VE environments using PowerShell.

It provides a comprehensive set of cmdlets that wrap the Proxmox REST API, allowing operations such as VM and container management, node monitoring, backup handling, and storage inspection—all from PowerShell.

This module serves as the PowerCLI equivalent for Proxmox VE:

• While PowerCLI facilitates VMware vSphere automation via PowerShell
• cv4pve-api-powershell offers similar capabilities for Proxmox VE environments

Key Features

Core Capabilities

• Easy to Learn - Intuitive PowerShell cmdlet interface
• Complete API Coverage - Automatically generated from official Proxmox VE API documentation
• Multiple Response Types - Support for JSON, PNG, ExtJS, HTML, and text formats
• Rich Response Objects - PveResponse class with detailed request/response information
• Cross-Platform - Works on Windows, Linux, and macOS (PowerShell 6.0+)
• No Remote Installation Required - Execute from any machine outside Proxmox VE

Authentication & Security

• API Token Support - Proxmox VE 6.2+ API token authentication
• Two-Factor Authentication - One-time password (OTP) support
• Secure Connections - TLS/SSL support with certificate validation options
• High Availability - Multi-host cluster connection for HA environments

Virtual Machine & Container Management

• VM Operations - Start, stop, suspend, resume, reset, unlock
• Container Support - Full LXC container lifecycle management
• Snapshot Management - Create, list, rollback, and delete snapshots
• Clone Operations - Clone VMs and containers
• Resource Monitoring - RRD data collection from nodes, QEMU VMs, and LXC containers

Advanced Features

• Direct API Access - Use Invoke-PveRestApi for custom API calls
• Indexed Parameters - Support for indexed parameters (e.g., -NetN, -ScsiN, -IdeN)
• Task Management - Wait for task completion, check task status
• Utility Functions - Unix time conversion, VM lookup by ID or name, and more
• SPICE Integration - Connect to VM consoles via Invoke-PveSpice
• Documentation Generation - Built-in help documentation builder

Developer-Friendly

• PowerShell Gallery - Simple installation via Install-Module
• Comprehensive Documentation - HTML and Markdown documentation included
• Interactive Tutorials - VSCode notebook tutorials available
• Open Source - Full source code available on GitHub

Utility Functions

The module includes a rich set of utility cmdlets to simplify common operations:

Time Conversion

• ConvertFrom-PveUnixTime - Convert Unix timestamp to DateTime
• ConvertTo-PveUnixTime - Convert DateTime to Unix timestamp

Task Management

• Wait-PveTaskIsFinish - Wait for a task to complete
• Get-PveTaskIsRunning - Check if a task is still running

VM Operations (by ID or Name)

• Get-PveVm - Find VM by ID or name
• Start-PveVm - Start a VM
• Stop-PveVm - Stop a VM
• Suspend-PveVm - Suspend a VM
• Resume-PveVm - Resume a VM
• Reset-PveVm - Reset a VM
• Unlock-PveVm - Unlock a VM

Monitoring & Statistics

• Get-PveNodeMonitoring - Get RRD monitoring data from nodes
• Get-PveQemuMonitoring - Get RRD monitoring data from QEMU VMs
• Get-PveLxcMonitoring - Get RRD monitoring data from LXC containers

Snapshot Management

• Get-PveVmSnapshot - Get snapshots for a VM
• New-PveVmSnapshot - Create a new snapshot
• Undo-PveVmSnapshot - Rollback to a snapshot
• Remove-PveVmSnapshot - Delete a snapshot

And many more! Explore the full cmdlet list with Get-Command -Module Corsinvest.ProxmoxVE.Api

Documentation

Comprehensive documentation is available in multiple formats:

• HTML Documentation - Full API reference in HTML format
• Markdown Documentation - Documentation in Markdown format

Tutorial & Learning Resources

• Interactive VSCode Notebook Tutorial - Learn by doing with interactive examples
• Common Issues & Examples - Practical solutions to common problems and advanced examples
• Video Demo - Watch a quick demonstration of the module in action

Requirements

• PowerShell 6.0 or higher (PowerShell Core)
• Network access to your Proxmox VE cluster
• Valid credentials or API token for Proxmox VE

Installation

Prerequisites

First, ensure you have PowerShell installed on your system (version 6.0 or later).

From PowerShell Gallery (Recommended)

The easiest way to install is directly from the PowerShell Gallery:

Install-Module -Name Corsinvest.ProxmoxVE.Api

Manual Installation

1. Download the Corsinvest.ProxmoxVE.Api folder from the repository
2. Copy it to one of your PowerShell module paths

To view your module paths:

# Display module paths
$env:PSModulePath -split [IO.Path]::PathSeparator

Documentation

Need help getting started or troubleshooting issues?

• Common Issues & Examples - Practical examples and solutions to common problems:

  • Hashtable parameters (NetN, SataN, ScsiN)
  • Boolean vs Switch parameters
  • Working with result objects
  • Creating VMs with disks and network
  • Guest agent commands
  • And more!

• Full Documentation - Complete reference with all cmdlets

• Proxmox VE API Viewer - Official Proxmox VE API documentation

Quick Start

Connecting to Your Cluster

Use Connect-PveCluster to establish a connection. This cmdlet supports both username/password and API token authentication.

Using Username and Password

# Connect with username and password
Connect-PveCluster -HostsAndPorts 192.168.1.100:8006 -SkipCertificateCheck

# PowerShell will prompt for credentials
# Username format: user@pam, user@pve, or user@yourdomain

Using API Token (Proxmox VE 6.2+)

From Proxmox VE 6.2+, you can use API tokens for authentication without username/password.

# Connect using API token
Connect-PveCluster -HostsAndPorts 192.168.1.100:8006 `
                   -SkipCertificateCheck `
                   -ApiToken "root@pam!mytoken=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

Note: API token format is USER@REALM!TOKENID=UUID. If using Privilege Separation, ensure proper permissions are configured.

Connection Management

The Connect-PveCluster function creates a PveTicket object and stores it in $Global:PveTicketLast. All cmdlets use this ticket by default, or you can specify a different ticket with the -PveTicket parameter.

💡 Usage Examples

Basic Operations

# Connect to cluster
Connect-PveCluster -HostsAndPorts 192.168.1.100:8006 -SkipCertificateCheck

# Get Proxmox VE version
Get-PveVersion | Select-Object -ExpandProperty Response | Select-Object -ExpandProperty data
# Output: version : 8.2.0, release : 1, repoid : abc123...

# List all VMs in the cluster
Get-PveClusterResources -Type vm | Select-Object -ExpandProperty Response | Select-Object -ExpandProperty data
# Output: vmid, name, status, node, uptime, etc.

VM Management

# Start a VM (by ID or name)
Start-PveVm -VmIdOrName 100
# Output: UPID:pve1:00001234:...

# Stop a VM gracefully
Stop-PveVm -VmIdOrName "my-vm"

# Suspend/Resume a VM
Suspend-PveVm -VmIdOrName 100
Resume-PveVm -VmIdOrName 100

# Reset a VM
Reset-PveVm -VmIdOrName 100

# Unlock a VM
Unlock-PveVm -VmIdOrName 100

Snapshot Management

# List snapshots for a VM
Get-PveNodesQemuSnapshot -Node pve1 -Vmid 100 | Select -Expand Response | Select -Expand data
# Output: name, snaptime, description, vmstate...

# Using Get-PveVm helper
Get-PveVm -VmIdOrName 100 | Get-PveNodesQemuSnapshot

# Create a snapshot
New-PveNodesQemuSnapshot -Node pve1 -Vmid 100 -Snapname "backup-2024-01-15"
# Output: snapshot created successfully

# Rollback to a snapshot
New-PveNodesQemuSnapshotRollback -Node pve1 -Vmid 100 -Snapname "backup-2024-01-15"

# Delete a snapshot
Remove-PveNodesQemuSnapshot -Node pve1 -Vmid 100 -Snapname "backup-2024-01-15"

Working with Indexed Parameters

When working with indexed parameters (e.g., -ScsiN, -IdeN, -NetN), use hashtables:

# Define configurations using hashtables
$networkConfig = @{
    1 = [uri]::EscapeDataString("model=virtio,bridge=vmbr0")
}
$storageConfig = @{
    1 = 'ssdpool:32'
}
$bootableIso = @{
    1 = 'local:iso/ubuntu-22.04.iso'
}

# Create a new VM with indexed parameters
New-PveNodesQemu -Node pve1 `
                 -Vmid 105 `
                 -Memory 2048 `
                 -ScsiN $storageConfig `
                 -IdeN $bootableIso `
                 -NetN $networkConfig

Note: Use [uri]::EscapeDataString to properly escape parameter values containing special characters.

For more detailed examples and common issues, see the Common Issues & Examples documentation.

Monitoring Resources

# Get node monitoring data (RRD data)
Get-PveNodeMonitoring -Node pve1 -Timeframe hour
# Output: cpu, memory, network, disk usage statistics

# Get QEMU VM monitoring data
Get-PveQemuMonitoring -Node pve1 -Vmid 100 -Timeframe day
# Output: CPU usage, disk I/O, network traffic over time

# Get LXC container monitoring data
Get-PveLxcMonitoring -Node pve1 -Vmid 200 -Timeframe week

Task Management

# Execute a long-running task
$result = New-PveNodesQemu -Node pve1 -Vmid 110 -Memory 4096 -Name "new-vm"
$taskId = $result.Response.data
# Output: UPID:pve1:00001F40:...

# Wait for task completion
Wait-PveTaskIsFinish -Node pve1 -Upid $taskId

# Check if a task is still running
$isRunning = Get-PveTaskIsRunning -Node pve1 -Upid $taskId
# Output: True/False

Advanced Features

PveResponse Class

All cmdlets return a PveResponse object with rich information:

class PveResponse {
    [PSCustomObject] $Response           # The actual API response
    [int] $StatusCode                    # HTTP status code
    [string] $ReasonPhrase              # HTTP reason phrase
    [bool] $IsSuccessStatusCode         # Success indicator
    [string] $RequestResource           # API endpoint called
    [hashtable] $Parameters             # Request parameters
    [string] $Method                    # HTTP method used
    [string] $ResponseType              # Response format

    # Helper methods
    [bool] ResponseInError()            # Check for errors
    [PSCustomObject] ToTable()          # Format as table
    [PSCustomObject] ToData()           # Extract data only
    [void] ToCsv([string] $filename)    # Export to CSV
    [void] ToGridView()                 # Display in grid view
}

PveTicket Class

Connection information is stored in a PveTicket object:

class PveTicket {
    [string] $HostName
    [int] $Port
    [bool] $SkipCertificateCheck
    [string] $Ticket
    [string] $CSRFPreventionToken
    [string] $ApiToken
}

Direct API Access

For operations not covered by cmdlets, use Invoke-PveRestApi:

# Make a custom API call
$result = Invoke-PveRestApi -Method Get `
                            -Resource "/api2/json/nodes/pve1/status" `
                            -PveTicket $Global:PveTicketLast

# Display results
$result.Response.data

High Availability Connections

Connect to multiple hosts for HA failover:

# Connect to multiple nodes
Connect-PveCluster -HostsAndPorts "192.168.1.100:8006,192.168.1.101:8006,192.168.1.102:8006" `
                   -SkipCertificateCheck

---

Support

For professional consulting and enterprise support, visit www.corsinvest.it

---

Part of cv4pve suite | Made with ❤️ in Italy by Corsinvest

Copyright © Corsinvest Srl