← Все статьи

Proxmox: автоматизация через API и Terraform

Proxmox REST API

Proxmox VE предоставляет REST API для управления кластером: создание, удаление, миграция VM и контейнеров, управление сетями и хранилищами. API использует аутентификацию через тикеты или API-токены.

Аутентификация через API-токен

# Создание API-токена в веб-интерфейсе:
# Datacenter -> Permissions -> API Tokens -> Add

# Использование токена
TOKEN="user@pam!mytoken=uuid-ключ-токена"
PVE_HOST="proxmox.example.com"

# Получение списка VM
curl -s -H "Authorization: PVEAPIToken=$TOKEN" \
    "https://$PVE_HOST:8006/api2/json/nodes/pve/qemu" | jq .

# Получение статуса кластера
curl -s -H "Authorization: PVEAPIToken=$TOKEN" \
    "https://$PVE_HOST:8006/api2/json/cluster/status" | jq .

Создание VM через API

# Клонирование шаблона VM
curl -X POST -H "Authorization: PVEAPIToken=$TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
        "newid": 200,
        "name": "web-server-01",
        "target": "pve1",
        "full": 1,
        "pool": "production"
    }' "https://$PVE_HOST:8006/api2/json/nodes/pve/qemu/100/clone"

# Настройка сети после клонирования
curl -X PUT -H "Authorization: PVEAPIToken=$TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
        "net0": "virtio,bridge=vmbr0,tag=100"
    }' "https://$PVE_HOST:8006/api2/json/nodes/pve/qemu/200/config"

Terraform провайдер

# versions.tf
terraform {
    required_providers {
        proxmox = {
            source = "Telmate/proxmox"
            version = "~> 3.0"
        }
    }
}

provider "proxmox" {
    pm_api_url = "https://proxmox.example.com:8006/api2/json"
    pm_api_token_id = "user@pam!mytoken"
    pm_api_token_secret = "uuid-токен-секрет"
    pm_tls_insecure = false
}

Определение ресурсов

# main.tf
resource "proxmox_vm_qemu" "web_server" {
    count = 3
    name = "web-${count.index + 1}"
    target_node = "pve1"
    vmid = 200 + count.index
    clone = "ubuntu-22.04-template"

    cores = 2
    memory = 4096
    disk {
        size = "50G"
        type = "scsi"
        storage = "local-lvm"
    }

    network {
        model = "virtio"
        bridge = "vmbr0"
        tag = 100
    }

    ipconfig0 = "ip=10.0.100.${21 + count.index}/24,gw=10.0.100.1"

    # Cloud-init
    ciuser = "ubuntu"
    sshkeys = file("~/.ssh/id_rsa.pub")

    lifecycle {
        ignore_changes = [
            network,
        ]
    }
}

Создание LXC контейнеров

resource "proxmox_lxc" "app_server" {
    count = 2
    hostname = "app-${count.index + 1}"
    target_node = "pve1"
    ostemplate = "local:vztmpl/ubuntu-22.04-standard_22.04-1_amd64.tar.zst"

    cores = 2
    memory = 2048
    swap = 1024
    disk {
        size = "20G"
        storage = "local-lvm"
    }

    network {
        name = "eth0"
        bridge = "vmbr0"
        ip = "dhcp"
        tag = 200
    }

    rootfs {
        size = "20G"
        storage = "local-lvm"
    }

    features {
        nesting = true
    }
}

Ansible + Proxmox

# inventory/proxmox.yml
plugin: community.general.proxmox
url: https://proxmox.example.com:8006
user: terraform@pam
token_id: mytoken
token_secret: uuid-токен
want_proxmox_nodes_enabled: true

# playbooks/deploy.yml
- hosts: all
  become: yes
  tasks:
    - name: Install packages
      apt:
        name: [nginx, docker.io, certbot]
        state: present
        update_cache: yes

    - name: Configure nginx
      template:
        src: nginx.conf.j2
        dest: /etc/nginx/nginx.conf
      notify: restart nginx

Комбинируйте Terraform для создания инфраструктуры и Ansible для настройки ПО. Terraform управляет lifecycle ресурсов, а Ansible — конфигурацией внутри VM.

Бэкап через API

# Запуск бэкапа
curl -X POST -H "Authorization: PVEAPIToken=$TOKEN" \
    -d '{
        "storage": "backup-server",
        "mode": "snapshot",
        "compress": "zstd"
    }' "https://$PVE_HOST:8006/api2/json/nodes/pve/qemu/200/backup"

# Список бэкапов
curl -s -H "Authorization: PVEAPIToken=$TOKEN" \
    "https://$PVE_HOST:8006/api2/json/nodes/pve/storage/backup-server/content" | jq .

Миграция VM

# Online миграция
curl -X POST -H "Authorization: PVEAPIToken=$TOKEN" \
    -d '{"target": "pve2"}' \
    "https://$PVE_HOST:8006/api2/json/nodes/pve/qemu/200/migrate"

Вывод

Proxmox API + Terraform + Ansible — это полноценный стек автоматизации для гипервизора. Terraform обеспечивает declarative management инфраструктуры, API позволяет интегрировать с CI/CD, а Ansible настраивает содержимое VM. Начните с API-токенов и простого скрипта, затем переходите к Terraform.