Proxmox VE Automation Skill

This skill provides comprehensive automation for Proxmox VE (Virtual Environment) management through its REST API.

Overview

Proxmox VE is an open-source server virtualization management platform that supports:

• - QEMU/KVM Virtual Machines (VMs)
• LXC Containers (Linux Containers)
• Storage management
• Cluster management
• Backup and snapshots

API Basics

• - Base URL: INLINECODE0

- Default port: 8006 - Custom port can be configured in PVE settings

• - Authentication: Ticket-based (cookie) or API Token-based
• Data format: JSON
• API Explorer: INLINECODE2

Custom API Port

PVE API port can be customized from the default 8006:

CODEBLOCK0

Using custom port in code:
CODEBLOCK1

Authentication Methods

Method 1: API Token (Recommended for automation)

API tokens provide stateless access without CSRF tokens:

CODEBLOCK2

Creating an API Token:

1. 1. Web UI: Datacenter → Permissions → API Tokens → Add
2. Or via API: INLINECODE3

Method 2: Ticket-based Authentication

For interactive sessions or when API tokens aren't available:

CODEBLOCK3

Tickets expire after 2 hours. Renew by passing the old ticket as password.

Common Operations

Node Operations

CODEBLOCK4

VM (QEMU) Operations

CODEBLOCK5

LXC Container Operations

CODEBLOCK6

VM/Container Creation

Create a VM from template:
CODEBLOCK7

Create an LXC container:
CODEBLOCK8

Template Management

CODEBLOCK9

Cloud-Init Configuration

Cloud-init allows automatic VM initialization on first boot:

CODEBLOCK10

Important: Cloud-init requires a cloud-init capable image (Ubuntu Cloud Images, Debian Cloud, etc.) and a configured CD/DVD drive (usually ide2) for the config drive.

Snapshots and Backups

CODEBLOCK11

Storage Operations

CODEBLOCK12

Network Configuration

CODEBLOCK13

Cluster Operations

CODEBLOCK14

Working with Tasks

Most write operations return a task UPID (Unique Process ID). Poll the task status to track completion:

CODEBLOCK15

Best Practices

1. VM ID Management

• - VM IDs must be unique across the cluster
• Common convention: 100-999 for VMs, 100000+ for containers (though not required)
• Check available VM IDs: GET /cluster/resources and filter by type

2. Resource Allocation

• - Always specify memory and cores when creating VMs
• Leave overhead for the host (don't allocate 100% of resources)
• Use ballooning for dynamic memory: balloon: 1024 with INLINECODE6

3. Network Configuration

• - Use virtio network drivers for best performance
• Configure bridges properly before creating VMs
• For VLANs: INLINECODE7

4. Storage

• - Use appropriate storage types:

- local: Directory storage - local-lvm: LVM thin provisioning - zfs: ZFS storage - nfs, iscsi, ceph: Network storage

5. Security

• - Use API tokens with limited permissions instead of root
• Enable 2FA for user accounts
• Use firewall rules: INLINECODE14

Common Workflows

Create a VM from Cloud Image

1. 1. Download cloud image ISO to storage
2. Create VM with cloud-init drive
3. Configure cloud-init parameters
4. Start VM

Clone a Template VM

CODEBLOCK16

Bulk Operations

For multiple VMs, loop through and call API for each:

• - Always add delays between operations to avoid overwhelming the API
• Check task completion before proceeding
• Handle errors gracefully

API Parameters Reference

VM Creation Parameters (POST /nodes/{node}/qemu)

Required Parameters:

• - vmid (integer): Unique VM ID (100-999999999), must be unique across cluster
• INLINECODE16 (string): VM name (must be valid DNS name)

Resource Parameters:

• - memory (integer): RAM in MB. Examples: 512, 1024, 2048, 4096, 8192
• INLINECODE18 (integer): Minimum memory for ballooning in MB (optional, enables memory overcommit)
• INLINECODE19 (integer): Number of CPU cores per socket (1-128)
• INLINECODE20 (integer): Number of CPU sockets (1-4)
• INLINECODE21 (string): CPU type. Common values: host, kvm64, qemu64, INLINECODE25
• INLINECODE26 (integer): Number of hotplugged vCPUs (defaults to cores*sockets)

Storage Parameters:

• - scsi0, scsi1, virtio0, virtio1, ide0, ide1, sata0, etc.

- Format: <storage>:<size> or <storage>:<volume-name>
- Examples: local-lvm:32, zfs:vm-disk-001, local-lvm:64,format=raw

• - efidisk0 (string): EFI system partition. Example: INLINECODE40

Network Parameters:

• - net0, net1, etc. (string): Network interface config

- Format: <model>,<options>
- Models: virtio (recommended), e1000, rtl8139, vmxnet3
- Examples:
- virtio,bridge=vmbr0 (basic bridge)
- virtio,bridge=vmbr0,tag=100 (VLAN 100)
- virtio,bridge=vmbr0,ip=192.168.1.10/24,gw=192.168.1.1 (static IP via cloud-init)

Boot/Media Parameters:

• - ostype (string): OS type for optimizations

- Linux: l24 (2.4), l26 (2.6+), other
- Windows: wxp, w2k, w2k3, w2k8, wvista, win7, win8, win10, win11

• - ide2 (string): CD/DVD drive or cloud-init drive

- ISO: local:iso/ubuntu-22.04.iso,media=cdrom
- Cloud-init: local-lvm:cloudinit,media=cdrom

• - boot (string): Boot order. Example: INLINECODE68
• INLINECODE69 (string): seabios (default) or ovmf (UEFI)

Cloud-Init Parameters:

• - ciuser (string): Default username
• INLINECODE73 (string): Default password (will be hashed)
• INLINECODE74 (string): Path to custom cloud-init config
• INLINECODE75 (string): configdrive2 or INLINECODE77
• INLINECODE78 (string): URL-encoded SSH public keys
• INLINECODE79, ipconfig1 (string): Network config

- DHCP: ip=dhcp
- Static: ip=192.168.1.10/24,gw=192.168.1.1

• - nameserver (string): DNS servers (comma-separated)
• INLINECODE84 (string): DNS search domain

LXC Container Parameters (POST /nodes/{node}/lxc)

Required Parameters:

• - vmid (integer): Unique container ID
• INLINECODE86 (string): Template path. Example: INLINECODE87

Resource Parameters:

• - memory (integer): RAM in MB
• INLINECODE89 (integer): Swap in MB
• INLINECODE90 (integer): CPU cores
• INLINECODE91 (number): CPU limit (0-128, 0=unlimited)
• INLINECODE92 (integer): CPU weight (0-500000, default: 1024)

Storage Parameters:

• - rootfs (string): Root filesystem. Format: INLINECODE94

- Example: local-lvm:8, local-lvm:16,mountoptions=noatime

• - mp0, mp1, etc. (string): Mount points

- Example: local-lvm:32,mp=/data, INLINECODE100

Network Parameters:

• - net0, net1, etc. (string): Network config

- Format: name=<ifname>,bridge=<br>[,options]
- Examples:
- name=eth0,bridge=vmbr0,ip=dhcp
- name=eth0,bridge=vmbr0,ip=192.168.1.10/24,gw=192.168.1.1
- name=eth0,bridge=vmbr0,tag=100,ip=dhcp (VLAN)

System Parameters:

• - hostname (string): Container hostname
• INLINECODE108 (string): Root password
• INLINECODE109 (string): SSH public keys (newline-separated)
• INLINECODE110 (boolean): Create unprivileged container (0/1)
• INLINECODE111 (string): Enabled features. Example: INLINECODE112
• INLINECODE113 (boolean): Start on boot (0/1)
• INLINECODE114 (string): Startup order and delay. Example: INLINECODE115

Safety and Resource Protection

1. Check Available Resources Before Creation

Always verify node resources before creating VMs/containers:

CODEBLOCK17

2. Get Cluster-Wide Resource Usage

CODEBLOCK18

3. Safe VM/Container Creation Helper

CODEBLOCK19

4. Dry-Run Mode for Bulk Operations

CODEBLOCK20

5. Safe Defaults Checklist

When generating PVE automation code, ensure these safeguards are included:

1. 1. Pre-flight Checks:

- Verify VMID is unique (not already in use) - Check node has sufficient resources - Validate storage exists and has space

1. 2. Resource Limits:

- Set reasonable defaults (2GB RAM, 2 cores, 32GB disk) - Warn if allocating >50% of node resources to single VM - Use ballooning for memory overcommit

1. 3. Operation Safety:

- Always use dry-run for bulk operations - Confirm destructive operations (delete, rollback) - Check VM is stopped before deletion or disk modification

1. 4. Error Handling:

- Handle 409 Conflict (VMID exists) - Handle 507 Insufficient Storage - Handle 595 PVE errors with meaningful messages

1. 5. Network Safety:

- Validate bridge exists before creating VM - Warn about IP conflicts (manual check required) - Use VLAN tags appropriately

Error Handling

Common HTTP status codes:

• - 400: Bad request (missing/invalid parameters)
• INLINECODE117: Unauthorized (invalid credentials)
• INLINECODE118: Forbidden (insufficient permissions)
• INLINECODE119: Resource not found
• INLINECODE120: Conflict (VMID already exists)
• INLINECODE121: Internal server error
• INLINECODE122: Insufficient Storage
• INLINECODE123: PVE specific errors (check response body)

Error response format:
CODEBLOCK21

Common Error Patterns and Solutions

Error	Cause	Solution
INLINECODE124	VMID in use	Query /cluster/resources to find next available
INLINECODE126

Node overloaded | Check memory.free before creation | | unable to create disk: out of space | Storage full | Check storage usage before creation | | bridge 'vmbrX' does not exist | Invalid network config | List /nodes/{node}/network to get valid bridges | | OSTYPE not set | Missing OS type | Add ostype parameter (l26 for Linux, win10 for Windows) | | timeout | Task taking too long | Increase timeout for slow operations (template download) |

Python Example

CODEBLOCK22

Advanced Operations

1. High Availability (HA)

HA ensures VMs/containers restart on another node if the current node fails.

HA Resources:
CODEBLOCK23

HA Resources (VMs to protect):
CODEBLOCK24

HA Status and Control:
CODEBLOCK25

2. Live Migration

Migrate running VMs between nodes (requires shared storage or storage migration).

CODEBLOCK26

Migration Requirements:

• - Shared storage (VM disks accessible from both nodes) OR INLINECODE134
• Same network bridges on both nodes (vmbr0, etc.)
• CPUs compatible (or use cpu: kvm64 for portability)
• For live migration: Intel-Intel or AMD-AMD (same vendor)

3. PCI/GPU Passthrough

Pass physical PCI devices (GPUs, NICs) to VMs.

Prerequisites:

• - Enable IOMMU in BIOS and kernel
• Load VFIO modules
• Blacklist GPU drivers on host

Configuration:
CODEBLOCK27

USB Passthrough:
CODEBLOCK28

4. Backup and Restore

Backup (vzdump):
CODEBLOCK29

Restore:
CODEBLOCK30

Backup Management:
CODEBLOCK31

5. Scheduled Jobs

Automate backups and other tasks.

CODEBLOCK32

Cron Expression Examples:

• - "0 2 * * *": Daily at 2 AM
• INLINECODE137: Weekly on Sunday midnight
• INLINECODE138: Every 6 hours
• INLINECODE139: Monthly on 1st at 3 AM

6. Permission Management

Users:
CODEBLOCK33

Groups:
CODEBLOCK34

Roles:
CODEBLOCK35

ACLs (Access Control):
CODEBLOCK36

Pools:
CODEBLOCK37

7. Notifications (Webhooks)

Configure notifications for automation workflows.

CODEBLOCK38

Notification Events:

• - Backup jobs: vzdump, INLINECODE141
• Replication: INLINECODE142
• HA events: Resource migration, failover
• System: Updates, errors

8. Replication

Replicate VM disks to another node for disaster recovery.

CODEBLOCK39

9. Firewall

Host and VM-level firewall configuration.

Host Firewall:
CODEBLOCK40

VM Firewall:
CODEBLOCK41

Security Groups:
CODEBLOCK42

10. Storage Configuration

Storage Types:

Type	Description	Common Options
INLINECODE143	Directory on local filesystem	path, prune-backups
INLINECODE144

LVM logical volumes | vgname, base, safe-remove |
| lvmthin | LVM thin provisioning | vgname, thinpool |
| zfspool | ZFS pool | pool, sparse, blocksize |
| nfs | NFS share | server, export, options |
| cifs | SMB/CIFS share | server, share, username, password |
| iscsi | iSCSI target | portal, target |
| cephfs | CephFS | monhost, fs-name, userid |
| rbd | Ceph RBD | monhost, pool, userid |
| glusterfs | GlusterFS | server, volume, transport |

Storage Operations:
CODEBLOCK43

11. Certificate Management

CODEBLOCK44

12. Node Maintenance

CODEBLOCK45

References

• - Proxmox VE API Documentation
• API Explorer
• pvesh man page
• HA Manager
• PCI Passthrough
• Backup and Restore
• Firewall