Proxmox VE 自動化：別再手動建 VM 了
手動從 ISO 裝一台 VM 要多久？下載映像、設定磁碟、裝系統、改網路、裝套件——順利的話半小時，不順利的話一個下午。現在想像你要建 10 台一模一樣的。對，該讓自動化上場了。
Cloud-init：VM 的開箱即用設定
Cloud-init 是雲端映像的標準初始化工具。VM 第一次開機時，它會自動幫你設好主機名、網路、使用者帳號和 SSH Key。流程是：做一個範本，之後每台新 VM 都從範本 clone，開機就能用。如果你對 VM 範本還不熟，可以先回顧VM 管理裡的範本與快照章節。
製作雲端映像範本
# 下載 Ubuntu 雲端映像
wget https://cloud-images.ubuntu.com/noble/current/noble-server-cloudimg-amd64.img
# 建立一台 VM 當範本（ID 9000，不啟動）
qm create 9000 --name ubuntu-cloud --memory 2048 --cores 2 \
--net0 virtio,bridge=vmbr0 --scsihw virtio-scsi-pci
# 匯入雲端映像當系統碟
qm set 9000 --scsi0 local-lvm:0,import-from=/root/noble-server-cloudimg-amd64.img
# 掛載 Cloud-init 光碟
qm set 9000 --ide2 local-lvm:cloudinit
# 設定開機順序和 Console
qm set 9000 --boot order=scsi0
qm set 9000 --serial0 socket --vga serial0
# 預設 Cloud-init 參數
qm set 9000 --ciuser admin --sshkeys ~/.ssh/id_rsa.pub --ipconfig0 ip=dhcp
# 轉成範本（不能再修改，只能 clone）
qm template 9000從範本秒建 VM
# Clone 出一台新 VM
qm clone 9000 100 --name web-server-01
# 覆寫 Cloud-init 參數
qm set 100 --ipconfig0 ip=192.168.1.100/24,gw=192.168.1.1
qm set 100 --nameserver 1.1.1.1
# 開機，30 秒後 SSH 直接連
qm start 100範本做好之後，建一台新 VM 從「半小時」變成「30 秒」。這不是誇張，是真的。
Terraform：基礎設施寫成程式碼
Terraform 讓你用設定檔描述「我要什麼 VM」，然後一個指令全部建好。改了設定檔，再跑一次就自動更新。
# provider.tf
terraform {
required_providers {
proxmox = {
source = "bpg/proxmox"
version = ">=0.50.0"
}
}
}
provider "proxmox" {
endpoint = "https://pve:8006"
api_token = "terraform@pve!automation=uuid-secret"
insecure = true
}
# vm.tf
resource "proxmox_virtual_environment_vm" "web_server" {
name = "web-server-01"
node_name = "pve1"
clone { vm_id = 9000 }
cpu { cores = 2; type = "host" }
memory { dedicated = 4096 }
disk {
datastore_id = "local-lvm"
size = 32
interface = "scsi0"
}
network_device { bridge = "vmbr0" }
initialization {
ip_config {
ipv4 { address = "192.168.1.100/24"; gateway = "192.168.1.1" }
}
user_account {
username = "admin"
keys = [file("~/.ssh/id_rsa.pub")]
}
}
}terraform init # 初始化
terraform plan # 預覽變更（看看要建什麼）
terraform apply # 執行（真的建下去）Ansible：軟體安裝與設定管理
Terraform 管「建 VM」，Ansible 管「VM 裡面裝什麼」。兩個搭配起來就是完整的自動化流水線：
Terraform → 建 VM（硬體、網路、Cloud-init）
↓
Cloud-init → 初始設定（SSH Key、基本網路）
↓
Ansible → 軟體安裝、設定檔、服務啟動
# playbook.yml
- name: Manage Proxmox VMs
hosts: localhost
tasks:
- name: Create VM from template
community.general.proxmox_kvm:
api_host: pve.example.com
api_user: ansible@pve
api_token_id: automation
api_token_secret: "uuid-secret"
clone: ubuntu-cloud-template
name: web-server-01
node: pve1
full: true
timeout: 300REST API：什麼都能呼叫
PVE 的 Web GUI 背後就是 REST API，所有操作都能用 API 做。
認證方式
| 方式 | 適合 | 安全性 |
|---|---|---|
| Ticket（帳密換 Cookie） | 臨時測試 | 一般 |
| API Token | 長期自動化 | 較高（建議，設定方式見權限管理） |
# API Token 直接用（推薦）
curl -k -H "Authorization: PVEAPIToken=user@pve!mytoken=uuid-secret" \
https://pve:8006/api2/json/nodes
# pvesh：PVE 內建的 CLI API 工具
pvesh get /nodes
pvesh get /nodes/pve1/qemu/100/status/current
pvesh create /nodes/pve1/qemu/100/status/start常用端點速查
| 動作 | 方法 | 端點 |
|---|---|---|
| 列出所有 VM | GET | /nodes/{node}/qemu |
| 啟動 VM | POST | /nodes/{node}/qemu/{vmid}/status/start |
| 關機 VM | POST | /nodes/{node}/qemu/{vmid}/status/shutdown |
| 建立快照 | POST | /nodes/{node}/qemu/{vmid}/snapshot |
| 遷移 VM | POST | /nodes/{node}/qemu/{vmid}/migrate |
| 叢集狀態 | GET | /cluster/status |
SDK 列表
| 語言 | 套件 |
|---|---|
| Python | proxmoxer |
| Go | proxmox-api-go |
| JavaScript | proxmox-api |
| Rust | proxmox-client |
| CLI | pvesh（內建） |
IaC 最佳實踐
- 所有設定檔進 Git：Terraform、Ansible、Cloud-init 設定都要版本控制
- Secrets 不要硬寫：API Token 放環境變數或 Vault，不要 commit 進 repo（備份策略可參考備份與還原）
- Terraform 狀態檔用遠端後端：S3 或 Consul，別放在本機
- 範本定期更新：雲端映像每個月重做一次，帶最新的安全更新
- 先 plan 再 apply：永遠先看 Terraform 要做什麼，確認了再執行
自動化的終極目標：所有基礎設施都能從 Git repo 重建。機器爆了不可怕，重跑一次
terraform apply就好。
自動化的前期投入比較大，但回本速度很快。當你第三次手動建 VM 還在複製貼上 IP 的時候，就會後悔沒早點寫 Terraform。
延伸閱讀：Proxmox API 官方文件、Terraform Proxmox Provider（bpg/proxmox）、Cloud-init 官方文件。
常見問題
Q: Proxmox Cloud-init 範本做好後，clone 一台 VM 要多久？
Full Clone 約 1-3 分鐘（取決於磁碟大小和儲存速度），Linked Clone 只需幾秒。加上 Cloud-init 自動設定網路和 SSH Key，整個流程從 clone 到能 SSH 登入通常不超過 2 分鐘。
Q: Proxmox Terraform Provider 該選哪個？
目前社群最活躍的是 bpg/proxmox（原名 Telmate 已停止維護）。它支援 VM、LXC、Cloud-init、儲存等完整資源管理，建議用 0.50 以上版本。
Q: PVE API Token 跟帳號密碼登入有什麼差別？
API Token 不需要每次換 Ticket，可以直接在 Header 帶入驗證，適合長期自動化。還能設定 Token 的獨立權限（privsep）和到期日，比共用帳號密碼安全得多。
Q: Ansible 和 Terraform 在 PVE 自動化中怎麼分工？
Terraform 負責「建基礎設施」（建 VM、設網路、分配儲存），Ansible 負責「設定軟體」（裝套件、改設定檔、啟動服務）。兩者搭配 Cloud-init 形成完整的自動化流水線。
下一步
系列最後一篇，整理 Homelab 的實用服務清單和長期維運心法： Homelab 最佳實踐