Почему Terraform + Proxmox

Proxmox VE 9.1 — мощная штука, но руками создавать VM не кайф. Terraform позволяет полностью описывать инфраструктуру кодом: VM, параметры, диски, cloud-init, сеть, storage. Изменения вносятся декларативно: ты просто правишь .tf, а Terraform приводит Proxmox к новому состоянию.

Начальная конфигурация VM

Пример минимальной VM в Proxmox через Terraform:

provider "proxmox" {
  pm_api_url      = "https://pve01:8006/api2/json"
  pm_api_token_id = "terraform@pve!tf"
  pm_api_token_secret = "YOURSECRET"
  pm_tls_insecure = true
}

resource "proxmox_vm_qemu" "vm01" {
  name        = "dev-vm01"
  target_node = "pve01"

  clone = "ubuntu-base-cloudinit"   # базовый cloud-init шаблон

  cores = 2
  memory = 2048

  disk {
    size = "10G"
    type = "scsi"
    storage = "local-lvm"
  }

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

  agent = 1
}

Теперь — меняем параметры и смотрим, как Terraform с этим работает.

1) Изменение CPU и RAM

Хочешь апгрейднуть виртуалку? Просто меняешь значения:

resource "proxmox_vm_qemu" "vm01" {
  name        = "dev-vm01"
  target_node = "pve01"

  cores  = 4       # было 2
  memory = 4096    # было 2048

  # остальное без изменений
}

Поведение: Proxmox позволяет менять CPU/RAM без пересоздания VM. Terraform спокойно выполнит API-update, VM перезапустится при необходимости.

2) Изменение дисков (size, storage)

Увеличение размера диска

disk {
  size = "20G"   # было 10G
  type = "scsi"
  storage = "local-lvm"
}

Важно: в Proxmox увеличение дисков — ок, уменьшение — невозможно. Terraform правильно выполнит resize через API.

Перенос на другое хранилище

Перемещение storage почти всегда вызывает пересоздание VM!

disk {
  size = "20G"
  type = "scsi"
  storage = "ceph-storage"  # сменили storage
}

Terraform покажет destroy + create. Это норма — Proxmox API иначе не умеет.

3) Cloud-Init: изменение параметров

Proxmox VE 9.1 круто работает с cloud-init, а Terraform позволяет менять его значения:

os_type = "cloud-init"

ciuser      = "devops"
cipassword  = "StrongPass123!"
ipconfig0   = "ip=192.168.10.50/24,gw=192.168.10.1"
sshkeys     = file("~/.ssh/id_rsa.pub")

Поведение: изменения применяются без пересоздания VM, Terraform дергает API cloud-init options.

4) Заметки и теги в Proxmox 9.1

Proxmox 9.1 добавил нормальную поддержку тегов через API. Terraform — тоже.

tags = [
  "env-dev",
  "team-platform",
  "terraform-managed"
]

desc = "Dev virtual machine managed by Terraform"

Теги меняются без пересоздания, всё через API-update.

Работа с terraform plan и apply

Классический цикл:

terraform fmt
terraform validate
terraform plan
terraform apply

На что смотреть в плане:

• Зелёный “+” — будет создано
• Жёлтый “~” — изменится на месте
• Красный “-” — будет удалено
• -/+ — пересоздание (важно!)

Главный чек: если Terraform показывает пересоздание VM — убедись, что там нет важных данных.

Полезные советы и подводные камни

• Используй QEMU Agent — agent = 1. Без него Terraform иногда не может корректно получить статус.
• Не меняй storage у дисков, если не готов пересоздать VM.
• Cloud-init шаблон делай заранее → clone в Terraform работает идеально.
• Держи state вне локалки (minio, S3-compatible, GitLab storage).
• Не уменьшай диски — Proxmox не умеет.
• Если VM критичная — через lifecycle { prevent_destroy = true } защищай от случайного удаления.

Почему Terraform для Proxmox VE 9.1

Terraform позволяет управлять инфраструктурой как кодом. Для Proxmox 9.1 это особенно удобно:

• быстрое создание стендов (Kubernetes, Docker, тестовые ВМ);
• единый cloud-init шаблон для всех виртуалок;
• воспроизводимость — одна команда apply создаёт полностью готовую VM;
• хорошая работа с PVE API Token в версии 9.x.

Что изменилось в Proxmox VE 9.1

• Базовая система — Debian 12 (Bookworm), обновлённые qemu/kvm.
• cloud-init теперь использует nocloud backend по умолчанию.
• Новые конфиги сетей Debian 12 требуют ip=dhcp или netplan config.
• UUID-имена дисков изменились (и Terraform Provider стал работать стабильнее).
• local-lvm в 9.1 создаётся с более строгими параметрами хранения.
• Telmate/proxmox стал корректнее обрабатывать serial-консоль + cloud-init.

Подготовка окружения

Требования:

• Proxmox VE 9.1
• Terraform 1.2+
• Terraform Provider: Telmate/proxmox >= 2.9
• Ubuntu Cloud Image / Debian Cloud Image
• API Token для Terraform

Создание API Token в PVE 9.1

1. Datacenter → Permissions → API Tokens.
2. Create.
3. User: root@pam
4. Permissions: Administrator
5. Запомнить Token ID + Secret.

Создание cloud-init шаблона в Proxmox VE 9.1

1. Скачиваем Cloud Image

wget https://cloud-images.ubuntu.com/jammy/current/jammy-server-cloudimg-amd64.img

2. Создаём VM-шаблон (ID 9000)

qm create 9000 --memory 2048 --cores 2 --name "ubuntu-ci-template" --net0 virtio,bridge=vmbr0

3. Импортируем диск

qm importdisk 9000 jammy-server-cloudimg-amd64.img local-lvm

4. Подключаем диск + cloud-init

qm set 9000 --scsihw virtio-scsi-pci --scsi0 local-lvm:vm-9000-disk-0
qm set 9000 --boot c --bootdisk scsi0
qm set 9000 --ide2 local-lvm:cloudinit
qm set 9000 --serial0 socket --vga serial0

5. Создаём шаблон

qm template 9000

Шаблон готов. Он полностью совместим с Terraform и Proxmox VE 9.1.

Настройка Terraform Provider

terraform.tf

terraform {
  required_providers {
    proxmox = {
      source  = "Telmate/proxmox"
      version = ">= 2.9.0"
    }
  }
}

provider.tf

provider "proxmox" {
  pm_api_url = "https://YOUR-PVE-IP:8006/api2/json"
  pm_api_token_id     = var.pve_token_id
  pm_api_token_secret = var.pve_token_secret
  pm_tls_insecure = true
}

variables.tf

variable "pve_token_id" { type = string }
variable "pve_token_secret" { type = string }

variable "vm_name"   { type = string default = "devopz-91" }
variable "vm_memory" { type = number default = 2048 }
variable "vm_cores"  { type = number default = 2 }

Создание VM в Proxmox VE 9.1 через Terraform

Пример работает с cloud-init шаблоном ID 9000.

main.tf

resource "proxmox_vm_qemu" "vm" {
  name        = var.vm_name
  target_node = "pve"
  clone       = "9000"

  agent = 1
  onboot = true

  cores  = var.vm_cores
  memory = var.vm_memory

  ssh_user = "ubuntu"

  # v9.1: cloud-init поддерживает ipconfig0 грамотно
  ipconfig0 = "ip=dhcp"

  ciuser     = "ubuntu"
  cipassword = "P@ssw0rd123!"
  sshkeys    = file("~/.ssh/id_rsa.pub")

  disk {
    size = "10G"
  }

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

outputs.tf

output "vm_name" {
  value = proxmox_vm_qemu.vm.name
}

output "vm_ip" {
  value = proxmox_vm_qemu.vm.ssh_host
}

Рабочий цикл

1. terraform init
2. terraform plan
3. terraform apply
4. VM появляется в Proxmox → запускается → получает DHCP-IP → доступна по SSH.
5. terraform destroy удаляет её полностью.

Best Practices для Proxmox VE 9.1

• Не храни Token в git — используй переменные окружения.
• В 9.1 cloud-init лучше работает с ide2 → cloudinit.
• Для стабильной работы Telmate/proxmox включай agent = 1.
• Шаблон должен быть только read-only — это важно для клонирования.
• Проверяй формат SSH ключей: некоторые старые RSA-ключи Debian 12 режет.

FAQ

Можно использовать Debian cloud image?

Да, Debian 12 Cloud работает идеально с PVE 9.1.

Работает ли с ZFS?

Да, но ZFS-диски импортируются через qm importdisk ... storage=zfs.

Нужен ли SSH-agent?

Нет, достаточно обычного ~/.ssh/id_rsa.pub.

Поддерживает ли PVE 9.1 cloud-init userdata?

Да, можно подсовывать cicustom, но Terraform Telmate его не поддерживает напрямую.