Proxmox REST API та автоматизація: керування через скрипти

Proxmox VE надає повноцінний REST API, через який доступні всі операції — від створення VM до керування кластером. Це основа для інтеграції з Terraform, Ansible, CI/CD і власними скриптами.

Автентифікація: API-токен vs. Cookie

Створення API-токена

# Створити користувача для автоматизації
pveum user add automation@pve --password AutoPass123

# Призначити права
pveum aclmod / --users automation@pve --roles PVEVMAdmin

# Створити API-токен (без привілеїв суперкористувача)
pveum user token add automation@pve mytoken --privsep 0

# Вивід: automation@pve!mytoken = xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Приклади запитів через curl

>TOKEN="automation@pve!mytoken=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
HOST="https://192.168.1.100:8006/api2/json"

# Список вузлів кластера
curl -s -k -H "Authorization: PVEAPIToken=$TOKEN" "$HOST/nodes" | python3 -m json.tool

# Список VM на вузлі pve
curl -s -k -H "Authorization: PVEAPIToken=$TOKEN" "$HOST/nodes/pve/qemu"

# Запустити VM 100
curl -s -k -X POST -H "Authorization: PVEAPIToken=$TOKEN" "$HOST/nodes/pve/qemu/100/status/start"

# Зупинити VM
curl -s -k -X POST -H "Authorization: PVEAPIToken=$TOKEN" "$HOST/nodes/pve/qemu/100/status/stop"

# Створити знімок
curl -s -k -X POST   -H "Authorization: PVEAPIToken=$TOKEN"   -d "snapname=api-test&description=Created+via+API"   "$HOST/nodes/pve/qemu/100/snapshot"

Python SDK для Proxmox

>from proxmoxer import ProxmoxAPI

proxmox = ProxmoxAPI(
    '192.168.1.100',
    user='automation@pve',
    token_name='mytoken',
    token_value='xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
    verify_ssl=False
)

# Список усіх VM
for vm in proxmox.nodes('pve').qemu.get():
    print(f"VM {vm['vmid']}: {vm['name']} - {vm['status']}")

# Створити знімок
proxmox.nodes('pve').qemu(100).snapshot.post(
    snapname='python-snap',
    description='Created via Python SDK'
)

# Запустити VM
proxmox.nodes('pve').qemu(100).status.start.post()

Terraform-провайдер Proxmox

>terraform {
  required_providers {
    proxmox = {
      source  = "bpg/proxmox"
      version = "~> 0.50"
    }
  }
}

provider "proxmox" {
  endpoint  = "https://192.168.1.100:8006/"
  api_token = "automation@pve!mytoken=xxxxxxxx..."
  insecure  = true
}

resource "proxmox_virtual_environment_vm" "ubuntu" {
  name      = "tf-ubuntu"
  node_name = "pve"
  vm_id     = 300

  clone {
    vm_id = 100  # ID шаблону
    full  = false
  }

  cpu { cores = 2 }
  memory { dedicated = 2048 }

  network_device {
    bridge = "vmbr0"
    model  = "virtio"
  }
}

Часті помилки під час роботи з Proxmox API

401 Unauthorized: permission denied - invalid PVE ticket

596 Connection reset by peer / SSL_ERROR

Parameter verification failed: vmid: value does not look like a valid VM ID

403 Forbidden: Permission check failed (/vms/100, VM.PowerMgmt)

API-токен проти Terraform-провайдера: що обрати

Коли автоматизація через API не підходить

• Разова ручна задача, яку простіше виконати через вебінтерфейс за одну хвилину — обгортати її в скрипт з автентифікацією не окупається
• У команді ніхто не підтримує отримані скрипти після відходу автора — необслуговувана автоматизація небезпечніша, ніж її відсутність, особливо поряд із status/start і status/stop
• Потрібна візуальна перевірка стану кластера перед кожною дією (сусідні ноди, вільне місце) — API не показує це так само наочно, як вебінтерфейс
• Інфраструктура змінюється настільки рідко, що Terraform state розходитиметься з реальністю між запусками — у цьому разі ручні операції надійніші за автоматизацію, за якою не стежать

Перевірка, що автоматизація працює правильно

# Токен дійсний і бачить кластер
curl -s -k -H "Authorization: PVEAPIToken=$TOKEN" "$HOST/version"

# Права токена обмежені очікуваним набором
pveum user permissions automation@pve

# Список задач, запущених через API, для звірки з логом скрипта
pvesh get /nodes/pve/tasks --limit 10

1. Виконайте запит до /version без прив'язки до конкретної VM — якщо він повертає 200, токен робочий на базовому рівні
2. Звірте фактичні права токена командою pveum user permissions з тим, що очікувалося під час створення — зайві права найпростіше прибрати одразу
3. Після виконання скрипта перевірте список задач у /nodes/NODE/tasks — кожна дія API має там відображатися з підсумковим статусом OK
4. Для Terraform виконайте terraform plan без застосування і переконайтеся, що він не показує неочікуваних змін на вже наявних ресурсах

Обмеження прав токена за ролями і ACL розглядає стаття користувачі, ролі і ACL у Proxmox, а базовий захист самого вебінтерфейсу панелі — матеріал двофакторний захист панелі Proxmox.

Часті питання

Чи обходить API-токен двофакторну автентифікацію, увімкнену для входу у вебінтерфейс Proxmox?

API-токен і вхід у вебінтерфейс — це різні механізми автентифікації: токен має власний секрет і перевіряється окремо від сесії браузера, тому формально він не «обходить» двофакторний захист, а просто працює іншим шляхом входу, для якого цей захист не передбачено. Саме тому права і термін дії такого токена варто обмежувати особливо уважно.

Що безпечніше: видати токену автоматизації права суперкористувача чи обмежену роль?

Обмежена роль безпечніша практично завжди: токен створюється під конкретну задачу, і йому варто видавати лише ті права, які реально потрібні скрипту, через призначення ролі на конкретний шлях, а не на корінь дерева ресурсів. Права суперкористувача перетворюють витік одного токена на компрометацію всього кластера цілком, тоді як вузька роль обмежує збиток заздалегідь зрозумілими рамками.

Чи потрібно передавати пароль користувача за кожного запиту, якщо використовується API-токен?

Ні, у цьому і сенс токена: одного разу створене значення підставляється в заголовок запиту і діє без введення пароля, поки його явно не відкликали. Пароль потрібен лише для сесійного входу через cookie, що має обмежений термін дії, тоді як токен створено спеціально для скриптів і автоматизації, де повторне ручне введення пароля було б незручним і небезпечним.

Чи варто переходити на Terraform, якщо прямі виклики API через curl чи Python уже працюють?

Якщо наявні скрипти вирішують разові задачі і ними хтось постійно опікується, змінювати їх на Terraform не обов'язково. Перехід виправданий, коли інфраструктура має відтворюватися за описом із коду, потрібен відкат до попередньої конфігурації і відстеження стану, — тоді state-файл Terraform бере на себе те, що інакше довелося б реалізовувати вручну поверх прямих викликів API.