Proxmox VE Deployment

This guide covers automating PiVirt cluster deployments onto Proxmox VE environments using deployer and Proxmox REST APIs.

Prerequisites

Proxmox Requirements

• Proxmox VE 8.0+
• VM templates for PiVirt nodes
• Shared storage (Ceph, NFS, or ZFS)
• Network with VLAN support

Credentials

/etc/deployer/config.yaml

providers:
  proxmox:
    enabled: true
    default_endpoint: "https://proxmox.pilab.hu:8006"
    default_user: "root@pam"
    token_ref: "vault:secret/data/proxmox#token"
    insecure: true

Deployment Configuration

Cluster Definition

deploy/proxmox-cluster.yaml

apiVersion: deployer.pilab.hu/v1
kind: Deployment
metadata:
  name: "pivirt-proxmox-staging"
spec:
  provider: "proxmox"
  topology:
    control_plane:
      count: 3
      template: "pivirt-cp-template"
      node: "proxmox-01"
      customization:
        cpu: 4
        cores: 2
        memory: 16Gi
        disk: 100Gi
    workers:
      count: 3
      template: "pivirt-worker-template"
      node: "proxmox-02"
      customization:
        cpu: 8
        cores: 4
        memory: 32Gi
        disk: 200Gi

  # VM customization
  customization:
    hostname_template: "pivirt-{{.Role}}-{{.Index}}"
    domain: "pilab.hu"
    dns_servers:
      - "10.0.1.5"
      - "10.0.1.6"
    ntp_servers:
      - "time.pilab.hu"
    timezone: "Europe/Budapest"

  # Network configuration
  network:
    bridge: "vmbr0"
    vlan: 100
    model: "virtio"

  # Storage configuration
  storage:
    pool: "local-lvm"
    format: "raw"

  cloud_init:
    template: "proxmox-node.yaml.tmpl"
    vars:
      pivirt_version: "v0.0.89"
      cluster_name: "pivirt-proxmox-staging"

Create VM Templates

Control Plane Template

# Create base VM via Proxmox UI or CLI
qm create 9000 \
  --name pivirt-cp-base \
  --memory 16384 \
  --cores 4 \
  --net0 virtio,bridge=vmbr0 \
  --scsihw virtio-scsi-pci \
  --scsi0 local-lvm:32 \
  --ostype l26 \
  --agent enabled=1

# Install Ubuntu 24.04
qm start 9000

# Install PiVirt components
# ... (install pivirtd, agent, pvcli)

# Shutdown and convert to template
qm shutdown 9000
qm template 9000

Worker Template

# Similar process for worker template
qm create 9001 \
  --name pivirt-worker-base \
  --memory 32768 \
  --cores 8 \
  --net0 virtio,bridge=vmbr0 \
  --scsihw virtio-scsi-pci \
  --scsi0 local-lvm:64 \
  --ostype l26 \
  --agent enabled=1

# Install and configure
# ...

qm template 9001

Deployment Process

1. Plan Deployment

deployer plan -f deploy/proxmox-cluster.yaml

2. Apply Deployment

deployer apply -f deploy/proxmox-cluster.yaml

3. Monitor Progress

deployer status -n pivirt-proxmox-staging
deployer logs -n pivirt-proxmox-staging --follow

4. Verify Deployment

pvcli cluster get staging
pvcli cluster node list

cloud-init Template

templates/proxmox-node.yaml.tmpl

#cloud-config
hostname: {{ .node_name }}
fqdn: {{ .node_name }}.pilab.hu

users:
  - name: pivirt
    groups: [sudo, docker, kvm]
    sudo: ALL=(ALL) NOPASSWD:ALL
    ssh_authorized_keys:
      - {{ .ssh_public_key }}

packages:
  - qemu-kvm
  - qemu-guest-agent
  - pivirt-agent
  - pvcli

runcmd:
  - systemctl enable --now qemu-guest-agent
  - systemctl enable --now pivirt-agent
  - systemctl enable --now pivirtd

final_message: "PiVirt node {{ .node_name }} provisioned on Proxmox"

Proxmox-Specific Features

QEMU Guest Agent

# Enable QEMU guest agent
spec:
  agent:
    enabled: true
    type: "qemu"

Backup Integration

# Use Proxmox backup
vzdump <vmid> --mode snapshot --compress zstd

Live Migration

# Migrate VM between Proxmox nodes
qm migrate <vmid> <target-node> --online

Troubleshooting

VM Won’t Start

# Check Proxmox logs
qm status <vmid>
qm config <vmid>

# Check QEMU logs
qm monitor <vmid>

Template Issues

# List templates
qm list | grep template

# Convert back to VM
qm template <vmid> --rollback

Network Issues

# Check bridge
brctl show vmbr0

# Check VLAN
cat /proc/net/vlan/config

Related

• Deployment Guide
• deployer Guide