🧱 Proxmox VE 虛擬機自動化管理：CLI、API 與 Ansible 整合應用

🧱 Proxmox VE 虛擬機自動化管理：CLI、API 與 Ansible 整合應用

Proxmox VE 擁有完整的 CLI 指令集、REST API 與 Ansible 支援，能以程式化方式建立 VM/LXC、批次調整資源、雲端初始化（Cloud-Init）與生命周期管理。本文提供可直接複製的腳本與 Playbook，協助你把日常操作自動化。

一、CLI（qm / pct / pvesh）：最快上手的自動化入口

CLI 適合在單點或 Pipeline 裡快速批次作業；搭配 shell 迴圈即可量產 VM/LXC。

1) 建立 KVM 虛擬機（qm + Cloud-Init）

# 參數
VMID=101
ISO=local:iso/debian-12.6.0-amd64-netinst.iso
STOR=local-lvm

# 建立 VM 與基本硬體
qm create $VMID --name "vm-$VMID" --memory 4096 --cores 2 --cpu host \
  --net0 virtio,bridge=vmbr0 --scsihw virtio-scsi-pci

# 匯入（或直接掛）磁碟
qm set   $VMID --ide2 $ISO,media=cdrom
qm set   $VMID --scsi0 $STOR:32    # 32G 虛擬碟

# 啟用 Cloud-Init（自動化帳號/網路/SSH Key）
qm set   $VMID --ide0 $STOR:cloudinit
qm set   $VMID --ciuser admin --cipassword 'P@ssw0rd!'
qm set   $VMID --sshkey ~/.ssh/id_rsa.pub
qm set   $VMID --ipconfig0 ip=dhcp

# 開機
qm start $VMID

2) 建立 LXC 容器（pct）

# 下載範例模板（可用 Web UI 或 pveam）
pveam available | grep debian-12
pveam download local debian-12-standard_12.2-1_amd64.tar.zst

# 建立容器
CTID=201
pct create $CTID local:vztmpl/debian-12-standard_12.2-1_amd64.tar.zst \
  --hostname lxc-$CTID --cores 2 --memory 2048 --swap 512 \
  --rootfs local-lvm:8 --net0 name=eth0,bridge=vmbr0,ip=dhcp --unprivileged 1
pct start $CTID

3) pvesh：以本機指令呼叫 REST API

# 列出叢集資源（等同 GET /api2/json/cluster/resources）
pvesh get /cluster/resources

# 建立排程備份（等同 POST /api2/json/nodes/{node}/vzdump）
pvesh create /nodes/node1/vzdump --all 1 --mode snapshot --compress zstd --storage local

二、REST API：與 CI/CD、內部系統對接

Proxmox API 入口為 https://<host>:8006/api2/json。建議使用 API Token（避免明文密碼）。

1) 取得 Token（Web 介面）

• Datacenter → Permissions → API Tokens → 為 user@pam 建立 tokenid，勾選 Privilege Separation，指派相對應角色（例如 PVEVMAdmin）。

2) 使用 Token 呼叫 API（cURL 範例）

# 列出節點
curl -k -H "Authorization: PVEAPIToken=user@pam!tokenid=SECRET" \
  https://pve-1:8006/api2/json/nodes

# 建立 VM（僅示意，常用參數取決於儲存/網路）
curl -k -X POST -H "Authorization: PVEAPIToken=user@pam!tokenid=SECRET" \
  -d "vmid=150&name=auto-150&memory=4096&cores=2&net0=virtio,bridge=vmbr0" \
  https://pve-1:8006/api2/json/nodes/pve-1/qemu

3) 以 Cookie + CSRF（傳統方式）

# 登入取得 Ticket 與 CSRF
curl -k -d "username=root@pam&password=YOURPASS" https://pve-1:8006/api2/json/access/ticket

# 之後 POST 需帶上：
#  -H "CSRFPreventionToken: <from-login>"
#  --cookie "PVEAuthCookie=<from-login>"

三、Ansible：宣告式大量佈建與收斂

適合把「建立 VM → 設定規格 → 啟動 → 安裝後設定」流程化，方便重複執行與追蹤。

1) 建議目錄

inventories/
  production/
    hosts.ini
    group_vars/proxmox.yml
playbooks/
  create_vms.yml
roles/
  postconfig/...

2) inventory（hosts.ini）

[proxmox]
pve-1 ansible_host=10.10.10.11
pve-2 ansible_host=10.10.10.12

[proxmox:vars]
ansible_user=root
ansible_ssh_common_args='-o StrictHostKeyChecking=no'

3) API 連線參數（group_vars/proxmox.yml）

pve_api_host: "https://10.10.10.11:8006/api2/json"
pve_api_user: "user@pam"
pve_api_token_id: "tokenid"
pve_api_token_secret: "SECRET"
pve_validate_certs: false

4) Playbook（使用 community.general.proxmox_kvm）

---
- name: Create KVMs on Proxmox
  hosts: proxmox
  gather_facts: false
  collections:
    - community.general

  vars:
    vm_plan:
      - { vmid: 310, name: "web-01", memory: 4096, cores: 2 }
      - { vmid: 311, name: "web-02", memory: 4096, cores: 2 }

  tasks:
    - name: Create/ensure VMs
      community.general.proxmox_kvm:
        api_user: "{{ pve_api_user }}"
        api_token_id: "{{ pve_api_token_id }}"
        api_token_secret: "{{ pve_api_token_secret }}"
        api_host: "{{ pve_api_host }}"
        validate_certs: "{{ pve_validate_certs }}"
        node: "pve-1"
        vmid: "{{ item.vmid }}"
        name: "{{ item.name }}"
        memory: "{{ item.memory }}"
        cores: "{{ item.cores }}"
        net:
          - model=virtio,bridge=vmbr0
        scsihw: virtio-scsi-pci
        scsi:
          - storage=local-lvm,size=32
        state: present
      loop: "{{ vm_plan }}"

    - name: Start VMs
      community.general.proxmox_kvm:
        api_user: "{{ pve_api_user }}"
        api_token_id: "{{ pve_api_token_id }}"
        api_token_secret: "{{ pve_api_token_secret }}"
        api_host: "{{ pve_api_host }}"
        validate_certs: "{{ pve_validate_certs }}"
        node: "pve-1"
        vmid: "{{ item.vmid }}"
        state: started
      loop: "{{ vm_plan }}"

💡 若沒有 proxmox_kvm 模組怎麼辦？（用 uri 直打 REST API）

- name: Create VM via REST
  uri:
    url: "{{ pve_api_host }}/nodes/pve-1/qemu"
    method: POST
    headers:
      Authorization: "PVEAPIToken={{ pve_api_user }}!{{ pve_api_token_id }}={{ pve_api_token_secret }}"
    body_format: form-urlencoded
    body:
      vmid: "320"
      name: "api-320"
      memory: "4096"
      cores: "2"
      net0: "virtio,bridge=vmbr0"
    validate_certs: false
    status_code: 200, 202

四、批次化：一鍵大量佈署小範例

#!/usr/bin/env bash
# create_many.sh
for i in {401..405}; do
  qm create $i --name "batch-$i" --memory 2048 --cores 2 \
    --net0 virtio,bridge=vmbr0 --scsihw virtio-scsi-pci
  qm set $i --scsi0 local-lvm:16 --ide2 local:iso/debian-12.iso,media=cdrom
  qm start $i
done

五、常見自動化情境

• 🚀 從模板快速複製：先把 Golden Image 設為模板 qm template <VMID>，再 qm clone 搭配 Cloud-Init 批次生成。
• 🔁 滾動更新：用 Ansible 將 VM 分組，逐台遷移（或停止）、更新、驗證，再切回 HA。
• 🧰 資源彈性調整：以 API/Ansible 依尖峰自動調整 vCPU/Memory，低谷再縮回。
• 🛡️ 備份與健康檢查：以 pvesh 觸發 vzdump，日誌串接 Rsyslog/GoAccess，異常時發 Slack/Webhook。

六、排錯與最佳實務

• API 403：確認 Token 角色（Role）是否涵蓋 VM.Allocate / Sys.Modify 等權限。
• 模組缺少：Ansible 加裝 ansible-galaxy collection install community.general。
• Cloud-Init 無效：檢查 --ide0 <storage>:cloudinit 是否已設定、VM BIOS/Boot 順序。
• REST 202：代表已受理非同步工作，後續可輪詢 /nodes/<node>/tasks/<upid>/status。

📘 結語

把 CLI、REST API 與 Ansible 串起來，你就擁有「可重現、可追蹤、可回滾」的 VM/LXC 生命周期管理。建議配合前文的網路/VLAN、儲存、備份、HA 叢集文章，形成完整的 Proxmox 自動化作業鏈。

---

🔗 延伸閱讀

• 🧱 Proxmox VE 高可用叢集（HA Cluster）架構實作指南
• 🧱 Proxmox VE 快照與備份還原：pve-zsync 與 vzdump 自動化策略
• 🧱 Proxmox VE 儲存整合教學：ZFS、NFS、iSCSI 與 LVM 的差異與實作
• 🧱 Proxmox VE 網路設定與 VLAN 管理：bridge、bonding、VLAN Tag 全解析

— WWFandy・系統與網路筆記