Припущення, яке Ansible зазвичай може собі дозволити
Майже кожен модуль Ansible, яким ти користувався, працює так: Ansible під’єднується до хоста, названого в інвентарі, копіює на нього невелику програму на Python, запускає її і зчитує результат. Хост є і тим, що змінюють, і тим, що виконує роботу.
Створення віртуальної машини ламає це в найбазовіший спосіб. Хоста, який ти будуєш, не існує. У нього немає IP, немає демона SSH, немає Python і немає операційної системи. Під’єднуватися нема до чого.
Тож community.proxmox не є агентом конфігурації. Це API-клієнт, який просто постачається як колекція Ansible. Відтак усе в цьому дописі випливає з цього одного факту: де виконуються задачі, як передати облікові дані, чому повторний запуск робить не те, чого ти чекаєш, і чому --check каже тобі неправду.
Приклади тут скорочено з плейбука, який будує VM з Windows і Linux із записів NetBox: proxmox-create-vms.yml. Для читабельності я узагальнив назви вузла, сховища і мосту; справжня версія лежить у тому репозиторії.
Усе, що я стверджую нижче про поведінку модулів, перевірено на community.proxmox 1.6.0, тобто на версії, яку я встановив:
$ ansible-galaxy collection list community.proxmox
# /home/damien/.ansible/collections/ansible_collections
Collection Version
----------------- -------
community.proxmox 1.6.0
Спершу: колекція переїхала
Якщо ти читаєш старіший плейбук чи старішу відповідь, модулі там називалися community.general.proxmox_kvm. Тепер вони живуть в окремій колекції, і саме там іде розробка. Версія 1.6.0 містить 47 модулів, що охоплюють Ceph, SDN, файрвол, правила HA і приєднання до кластера, і жодного з них не було в часи community.general.
ansible-galaxy collection install community.proxmox
pip install 'proxmoxer>=2.0' requests
Залежність від Python не опціональна й не вбудована: колекція оголошує requirements: ["proxmoxer >= 2.0", "requests"], і їх треба встановити там, де модуль насправді виконується, а це, як пояснює наступний розділ, не вузол Proxmox.
requirements.yml, якщо хочеш зафіксувати версію:
---
collections:
- name: community.proxmox
version: ">=1.6.0"
Колекцію тестують на ansible-core від 2.17 до 2.20. Перейменування твоїх задач community.general.proxmox_* на community.proxmox.proxmox_* становить більшу частину міграції.
Кожна задача Proxmox виконується на localhost
Два рядки на початку play виконують основну роботу, і обидва виглядають так, ніби вимикають щось корисне:
- name: Create Proxmox virtual machines
hosts: "{{ target_hosts | default('cluster_pve:&status_planned') }}"
gather_facts: false
serial: 1
gather_facts: false не є оптимізацією. Збирання фактів під’єднується до хоста з інвентарю, а хост з інвентарю це VM, яку ще не збудовано. Залиш його ввімкненим, і play впаде ще до першої задачі.
Далі кожна задача Proxmox має delegate_to: localhost:
- name: Create Proxmox VM
delegate_to: localhost
register: created_vm
community.proxmox.proxmox_kvm:
api_user: "{{ proxmox_user }}"
api_password: "{{ proxmox_password }}"
api_host: "{{ proxmox_api_ip }}"
name: "{{ inventory_hostname }}"
node: "{{ proxmox_api_host }}"
...
Хост з інвентарю тепер просто ім’я і торба змінних. inventory_hostname стає назвою VM; її змінні описують машину, яку ти хочеш. До неї ніхто не під’єднується. Задача виконується на керівному вузлі, який відкриває HTTPS-сесію до api_host і надсилає опис VM.
Ти також побачиш, що це пишуть як local_action:, тобто старішим синтаксисом для того самого. Плейбук розбирання в тому репозиторії використовує його всюди. Вони рівнозначні. delegate_to це сучасне написання.
Запасний вихід вказує на вузол
Деякі речі справді мають відбуватися на хості Proxmox, і такі задачі делегуються зовсім в інше місце:
- name: Fail if no ISO file exists for the OS
delegate_to: "{{ proxmox_api_host }}"
ansible.builtin.stat:
path: "{{ iso | replace('isos:', '/mnt/pve/isos/template/') }}"
register: iso_file
failed_when: not iso_file.stat.exists
Це справжнє з’єднання SSH до справжнього вузла, яке перевіряє справжній шлях на спільному сховищі, бо API залюбки прийме посилання на ISO, яке не вказує на жоден файл, а дізнатися про це краще зараз, ніж під час завантаження. Зверни увагу на хірургію рядків, яка перетворює посилання на сховище PVE (isos:iso/debian.iso) на шлях у файловій системі. Абстракція сховищ для stat недоступна.
Тож в одному play задачі виконуються в трьох різних місцях, і плутанина між ними є найпоширенішою причиною, чому такі плейбуки падають:
qm єдина частина, якій потрібен SSH до гіпервізора.Облікові дані і значення за замовчуванням, яке ось-ось зміниться
Параметри автентифікації спільні для всіх модулів колекції через фрагмент документації, тож вони всюди однакові: api_host, api_user, а далі або api_password, або пара api_token_id / api_token_secret. Усі вони мають запасний варіант у змінних середовища: PROXMOX_HOST, PROXMOX_USER, PROXMOX_PASSWORD, PROXMOX_TOKEN_ID, PROXMOX_TOKEN_SECRET, PROXMOX_VALIDATE_CERTS. Це найчистіший спосіб повністю тримати секрети поза play.
API-токен кращий вибір за замовчуванням. Він має обмежену область дії, його можна відкликати без зміни пароля людини, і йому можна дати саме ті привілеї, які потрібні плейбуку, а не ті, що випадково має якась особа:
- name: Create Proxmox VM
delegate_to: localhost
community.proxmox.proxmox_kvm:
api_host: "{{ proxmox_api_ip }}"
api_user: ansible@pve
api_token_id: automation
api_token_secret: "{{ proxmox_token_secret }}"
validate_certs: true
ca_path: /etc/ssl/certs/pve-cluster-ca.pem
Задай validate_certs явно, сьогодні. Власна документація колекції каже це прямо:
Currently defaults to
falseand changes default totruewith community.proxmox 2.0.0.
А отже, плейбук, який про це ніде не згадує, зараз не перевіряє TLS, і почне перевіряти, а значить і падати на самопідписаному сертифікаті, з яким постачається кожна свіжа інсталяція Proxmox, щойно хтось запустить --upgrade. Краще ухвалити це рішення свідомо, ніж отримати його посеред збирання. Якщо лишаєш самопідписаний сертифікат, напиши validate_certs: false і прийми це зауваження; якщо маєш нормальний ланцюжок, вкажи на нього через ca_path. Так чи інакше, це записано.
Мінімальне робоче створення
Обріж робочу задачу до того, що справді визначає машину, і вона стає читабельною:
- name: Create Proxmox VM
delegate_to: localhost
register: created_vm
community.proxmox.proxmox_kvm:
api_host: "{{ proxmox_api_ip }}"
api_user: ansible@pve
api_token_id: automation
api_token_secret: "{{ proxmox_token_secret }}"
validate_certs: true
node: pve1
name: "{{ inventory_hostname }}"
cores: "{{ vcpus | int }}"
memory: "{{ memory }}"
machine: q35
bios: ovmf
ostype: l26
scsihw: virtio-scsi-single
scsi:
scsi0: "vmdata:32,format=qcow2,discard=on,ssd=1"
sata:
sata0: "isos:iso/debian-13-netinst.iso,media=cdrom"
net:
net0: "virtio,bridge=vmbr0"
efidisk0:
storage: vmdata
format: raw
efitype: 4m
pre_enrolled_keys: true
boot: "order=scsi0;sata0"
agent: "enabled=1,fstrim_cloned_disks=1"
onboot: true
tags:
- production
Кілька речей про цю форму варто знати, перш ніж писати власну.
Параметри пристроїв це синтаксис PVE всередині YAML. scsi, sata, net, virtio, ide мають тип dict з ключами scsi0, net0 і так далі, а значення це рядки параметрів через кому прямо з man qm: <storage>:<size>,option=value для диска, [model=]<enum>,option=value для NIC. Модуль їх не моделює; він їх пересилає. Коли щось відхилено, відповідь шукай у довіднику параметрів PVE, а не в документації Ansible.
Ти також побачиш, що їх пишуть як рядок JSON, а не як відображення YAML:
net: '{"net0":"virtio,bridge={{ vlan_bridge }}"}'
Працює і так, і так. Ansible приводить рядок для параметра типу dict. Форма JSON існує тому, що всю структуру легше згенерувати одним виразом Jinja. Форму відображення легше читати через пів року.
boot має синтаксис двох поколінь. Модуль приймає застарілі літери, де boot: "cdn" означає «спробуй диск, потім CD-ROM, потім мережу». Сучасний PVE хоче явний упорядкований список, boot: "order=scsi0;sata0;net0", який однозначно вказує, який саме диск. Застаріла форма досі працює. Явна форма це те, що тобі потрібно в новій роботі. Одна справжня пастка, захована в документації модуля: для мережевого завантаження з PVE 8.3.5 треба задати rng0.
numa і numa_enabled це різні параметри. numa_enabled це булеве значення, яке вмикає NUMA. numa це dict, що описує топологію (cpus, hostnodes, memory, policy). numa: true дає помилку типу, і на цьому легко втратити годину. Якщо тобі цікаво, чому все це важливо, вирівнювання NUMA в Proxmox розбирає саму проблему.
machine: q35 і bios: ovmf це правильні значення за замовчуванням, а не прикраса: повний аргумент тут.
Якщо пропустити vmid, модуль попросить в API наступний вільний ID. Зручно, і саме це безпосередньо спричиняє наступне.
Чому serial: 1
«Отримай наступний вільний ID, а потім створи з ним VM» це два виклики API з проміжком посередині. Два воркери, що роблять це одночасно, можуть прочитати той самий вільний ID, і той, хто програв, отримає помилку або, ще гірше, сюрприз.
serial: 1 робить фазу створення по одному хосту за раз. Це не швидко, і не мусить бути. Дорога частина побудови VM відбувається після того, як цей плейбук передає роботу далі. Парний play, який запускає готові VM, використовує serial: 5, бо під час запуску немає спільного лічильника, за який можна змагатися.
Якщо хочеш паралельності, виділяй VMID сам зі свого джерела істини і передавай його явно. Тоді немає ні циклу «прочитай, зміни, запиши», ні гонки.
Ідемпотентність не така, як ти чекаєш
Цей розділ варто прочитати двічі, бо proxmox_kvm поводиться не так, як ansible.builtin.package.
name не є ідентичністю. Назви VM не унікальні в межах кластера Proxmox, і модуль про це каже. З state: present і без vmid, якщо VM з такою назвою вже існує, модуль завершується з changed=false і msg: "VM with name <x> already exists" і нічого не робить. Він не порівнює твої параметри з реальністю. Він не сходиться. Він відмовляється.
update за замовчуванням false. Тож якщо змінити memory: у плейбуку і запустити ще раз, нічого не станеться. VM залишає пам’ять, з якою її збудували, задача повідомляє про успіх, і ніщо ніде не скаже тобі, що вони розійшлися.
update: true і далі відмовляється від цікавих параметрів. З документації модуля:
Because of the operations of the API and security reasons, I have disabled the update of the following parameters
net,virtio,ide,sata,scsi. Per example updatingnetupdate the MAC address andvirtiocreate always new disk…
update_unsafe: true знімає це обмеження, і попередження тут не для краси:
Use this option with caution because an improper configuration might result in a permanent loss of data (for example disk recreated).
Тож диск, який ти начебто збільшував, можуть замінити новим порожнім. Не берися за це: для відхилених параметрів є власні модулі, і про них наступний розділ.
І --check нічого з цього не покриває. Колекція оголошує підтримку режиму перевірки для кожного модуля окремо, і вона непослідовна саме в найгіршому напрямку:
| Модуль | check_mode | diff_mode |
|---|---|---|
proxmox_kvm | немає | немає |
proxmox_disk | немає | немає |
proxmox_template | немає | немає |
proxmox_snap | повна | немає |
proxmox_nic | повна | немає |
proxmox_pool | повна | немає |
Поділ не такий, що «модулі лише для читання можуть, модулі для запису ні»: proxmox_nic створює і видаляє інтерфейси і цілком справно дотримується режиму перевірки. Річ у тім, що три модулі, які мають справу зі сховищем і життєвим циклом VM, цього не роблять. Запуск плейбука збирання з --check мовчки пропускає створення VM, а потім звітує про світ, у якому VM так і не створили, тож кожна наступна задача міркує про неправильний стан. Для плейбука збирання --check не є страховкою, і вважати його такою гірше, ніж не запускати зовсім.
Тож зроби існування воротами
З огляду на все це, робочий шаблон такий: перестати вимагати від модуля ідемпотентності і самому вирішувати, чи будувати. Робочий плейбук робить це так:
- name: Check if VM is present or manually built
delegate_to: localhost
community.proxmox.proxmox_vm_info:
api_host: "{{ proxmox_api_ip }}"
api_user: "{{ proxmox_user }}"
api_password: "{{ proxmox_password }}"
name: "{{ inventory_hostname }}"
config: current
register: existing_vm
ignore_errors: true
failed_when: (existing_vm.proxmox_vms | length) == 0
- name: Configure Proxmox VM
when: existing_vm is failed
block:
- name: Create Proxmox VM
...
proxmox_vm_info з config: current повертає VM та її живу конфігурацію або порожній список. failed_when перетворює «порожній список» на збій, ignore_errors: true не дає цьому збою завершити play, а when: existing_vm is failed стає умовою «VM немає, будуй».
Використовувати навмисно провалену задачу як булеве значення читається погано, і я не вдаватиму, що це не так. Альтернатива: when: (existing_vm.proxmox_vms | default([]) | length) == 0, що чесно є перевіркою довжини і не потребує ignore_errors. Обидва варіанти працюють. Версія вище стоїть у продакшні, і її єдина справжня перевага в тому, що зареєстрований результат містить наявну конфігурацію, яку можуть прочитати пізніші задачі.
Важлива тут форма, а не написання: перевір, потім розгалузь, і стався до створення як до одноразової події. Поточна конфігурація VM це зовсім інша проблема, ніж існування VM, і цей модуль добрий лише в другій.
Для дисків і NIC є власні модулі
Ось те, що я вище пропустив, і воно змінює всю картину: параметри, які proxmox_kvm відмовляється оновлювати, не є прогалиною в колекції. Їх делеговано. community.proxmox.proxmox_disk і community.proxmox.proxmox_nic додають, змінюють і видаляють саме те, чого модуль створення не торкнеться, і ключами для них є ті самі назви scsi0 і net0, які ти використав, коли будував VM.
Обидва поводяться краще за proxmox_kvm, а один із них єдиний модуль у цьому процесі, який можна запустити насухо.
proxmox_nic: додати, перетегувати чи видалити інтерфейс
- name: Move the VM's primary NIC to a new bridge and VLAN
delegate_to: localhost
community.proxmox.proxmox_nic:
api_host: "{{ proxmox_api_ip }}"
api_user: ansible@pve
api_token_id: automation
api_token_secret: "{{ proxmox_token_secret }}"
vmid: "{{ created_vm.vmid }}"
interface: net0
bridge: vmbr1
tag: 120
model: virtio
mtu: 1
queues: 4
firewall: true
state: present
interface єдиний обов’язковий параметр, окрім автентифікації, net[n], де n від 0 до 31, а state: present або absent дає додавання і видалення. model за замовчуванням virtio, і це правильна відповідь, якщо гостьова система з ним справляється.
Цей модуль існує через MAC-адресу. Згадай, чому proxmox_kvm відмовляється оновлювати net: «updating net update the MAC address». proxmox_nic явно це виправляє:
When not specified this module will keep the MAC address the same when changing an existing interface.
Тож ти можеш перетегувати VLAN, перенести міст, змінити MTU чи ввімкнути файрвол так, щоб ідентичність NIC гостьової системи під нею не змінювалася. Це важливіше, ніж звучить: нова MAC скасовує резервації DHCP, ламає все, що ліцензовано на мережеву карту, і розсинхронізує запис інтерфейсу в NetBox, який плейбук створення так ретельно записав. Це модуль, завдяки якому мережева зміна на другий день стає нудною.
Кілька параметрів, які варто знати, ще до того як вони знадобляться:
rateвимірюється в MBps, мегабайтах за секунду, а не в бітах. Документація про це каже прямо, і помилку у вісім разів дуже легко зробити.link_down: trueвід’єднує інтерфейс, що в документації описано як «like pulling the plug». Чистий спосіб ізолювати підозрілу VM, не зупиняючи її і не торкаючись гостьової системи.trunksприймає список ID VLAN для пропускання, для гостьової системи, яка тегує сама.mtu: 1не друкарська помилка і не MTU в 1 байт: це означає «успадкувати MTU мосту», і застосовується лише доvirtio.queuesзадає multiqueue, від 0 до 16. Варто узгодити з кількістю vCPU на всьому, що пропускає справжній трафік.
І він повністю підтримує режим перевірки. --check на задачі proxmox_nic каже правду, тож це єдина частина цього процесу, яку можна безпечно відрепетирувати. Його повідомлення теж справді ідемпотентні. Незмінений інтерфейс повідомляє Nic net0 unchanged on VM with vmid 103, а не заявляє про зміну.
proxmox_disk: увесь життєвий цикл диска
proxmox_disk найбільший модуль із трьох, і його state виконує п’ять різних робіт:
state | Що відбувається | Зворотне? |
|---|---|---|
present | створити диск або оновити параметри наявного | н/д |
resized | збільшити його: PVE не вміє зменшувати, і документація каже робити це вручну | ні |
detached | стає unused[n]; том і його дані лишаються | так |
moved | змінити сховище або передати диск іншій VM | оригінал лишається, якщо немає delete_moved |
absent | видалено зі сховища | ні |
Різниця між detached і absent це та страховка, якої proxmox_kvm тобі ніколи не дає. Від’єднання змінює конфігурацію; видалення знищує дані. Два різні слова, два різні наслідки.
Додавання другого диска до VM, яка вже існує:
- name: Add a data disk
delegate_to: localhost
community.proxmox.proxmox_disk:
api_host: "{{ proxmox_api_ip }}"
api_user: ansible@pve
api_token_id: automation
api_token_secret: "{{ proxmox_token_secret }}"
vmid: "{{ created_vm.vmid }}"
disk: scsi1
storage: vmdata
size: 200
format: qcow2
iothread: true
aio: io_uring
discard: "on"
ssd: true
backup: true
state: present
create це перемикач, який мав би бути в proxmox_kvm. Він визначає, що дозволено робити state: present:
regular(за замовчуванням): створити диск, якщо його немає, інакше оновити його параметри.disabled: лише оновити параметри і ніколи не створювати. Саме цей варіант бери, коли змінюєшcacheчиiothreadна диску, який мусить уже існувати. Він не здивує тебе, створивши новий том через помилку в ключі.forced: завжди створювати. Наявний диск від’єднується і лишається невикористаним, а не видаляється.
Ця остання поведінка і є важливою деталлю. create: forced виглядає руйнівним параметром, але все одно нічого не знищує: старий том зберігається як unusedN, і його можна під’єднати назад. Порівняй із proxmox_kvm разом з update_unsafe, чий задокументований сценарій збою це перестворений диск. Приблизно та сама операція, набагато менший радіус ураження.
Збільшення диска:
- name: Grow the data disk by 100 GiB
delegate_to: localhost
community.proxmox.proxmox_disk:
api_host: "{{ proxmox_api_ip }}"
api_user: ansible@pve
api_token_id: automation
api_token_secret: "{{ proxmox_token_secret }}"
vmid: "{{ created_vm.vmid }}"
disk: scsi1
size: "+100G"
state: resized
Стеж за одиницями, бо значення size змінюється разом зі state. З state: present це GiB у вигляді голого числа (size: 200). З state: resized воно приймає суфікс: +100G, щоб додати до поточного розміру, або 500G як абсолютну ціль. Один параметр, дві домовленості, і якщо вгадаєш неправильно, збій буде тихим.
Перенесення диска на інше сховище, тобто випадок живої міграції одного тому:
- name: Move the disk to NVMe storage
delegate_to: localhost
community.proxmox.proxmox_disk:
api_host: "{{ proxmox_api_ip }}"
api_user: ansible@pve
api_token_id: automation
api_token_secret: "{{ proxmox_token_secret }}"
vmid: "{{ created_vm.vmid }}"
disk: scsi1
target_storage: nvme-pool
bwlimit: 200000
delete_moved: true
timeout: 3600
state: moved
target_storage переносить у межах однієї VM; target_vmid передає диск іншій VM і вимагає того самого сховища в обох. Вони взаємовиключні. delete_moved за замовчуванням false, тож за замовчуванням ти отримаєш дві копії, і оригінал лежатиме як невикористаний: безпечно, і добрий спосіб заповнити пул сховища, якщо ніколи до нього не повертатися.
timeout тут за замовчуванням 600, проти 30 у proxmox_kvm. Схожий на вигляд параметр, різниця у двадцять разів, бо ці операції копіюють дані. Збільшуй його для великих образів чи повільного сховища: документація каже це і для moved, і для import_from.
Що підводить нас до параметра, який робить цей модуль шляхом для V2V і хмарних образів:
import_from: "vmdata:9000/base-debian13.qcow2"
import_from будує диск з наявного тому, а не виділяє порожній: <STORAGE>:<VMID>/<NAME> або <STORAGE>:import/<NAME> з використанням каталогу імпорту сховища на PVE 9.x і новіших. Він взаємовиключний із size, і абсолютні шляхи файлової системи може використовувати лише root.
Решта списку параметрів і є причиною під’єднувати диски цим модулем, а не всередині виклику створення: cache, aio, iothread, discard, ssd, backup, detect_zeroes і вся родина обмеження швидкості: iops, iops_rd, iops_wr, їхні варіанти _max і _max_length, а також керування сплесками bps_*_max_length. Жоден із них не доступний через proxmox_kvm після створення.
Два застереження, обидва з власної документації модуля:
- Деякі зміни параметрів потребують перезавантаження. «Some updates on options (like
cache) are not being applied instantly and require VM restart.» Зелена задача означає, що конфігурацію записано, а не що запущена VM поводиться інакше. - Він не підтримує режим перевірки.
check_mode: none, як і вproxmox_kvm. Тож колекція ділиться навпіл: зміни NIC можна відрепетирувати з--check, зміни дисків ні.
Розподіл праці
| Щоб зробити це | Використовуй |
|---|---|
| Створити VM | proxmox_kvm, один раз, з воротами на існування |
| Змінити ядра, пам’ять, теги, агент, onboot | proxmox_kvm з update: true |
| Додати, перетегувати, від’єднати чи видалити NIC | proxmox_nic |
| Додати, збільшити, перенести, від’єднати чи видалити диск | proxmox_disk |
| Знімок | proxmox_snap (теж повний режим перевірки) |
| Будь-що, чого жоден із них не відкриває | qm set через SSH |
Змінити диск чи NIC через proxmox_kvm | нічого: саме для цього існує update_unsafe, і саме тому ним не варто користуватися |
Збудуй VM мінімальним викликом proxmox_kvm, а потім під’єднай диски й інтерфейси їхніми власними модулями. Задач більше, і це та версія, де зміни другого дня мають шлях, який не проходить через параметр із задокументованим ризиком втратити диск.
Де модуль зупиняється
proxmox_kvm має величезний список параметрів і все одно не покриває всього, що вміє qm. Замість чекати, робочий плейбук переходить до CLI на вузлі:
- name: Set RNG source and better SPICE quality
delegate_to: "{{ proxmox_api_host }}"
become: true
ansible.builtin.command:
cmd: >-
/usr/sbin/qm set {{ created_vm.vmid }}
--rng0 source=/dev/urandom
--spice_enhancements videostreaming=all
У цьому немає нічого поганого. Це не ідемпотентно в жодному значущому сенсі, бо qm set це запис, і він щоразу повідомлятиме changed, але це явно, читабельно і нічого не вдає. Якщо модуль згодом отримає цей параметр, задачу можна видалити.
Інші речі потребують другого проходу через модуль з update: true, бо їх не можна задати в тому самому виклику, що створює VM:
- name: Add SPICE-compatible USB device
delegate_to: localhost
community.proxmox.proxmox_kvm:
api_host: "{{ proxmox_api_ip }}"
api_user: "{{ proxmox_user }}"
api_password: "{{ proxmox_password }}"
node: "{{ proxmox_api_host }}"
vmid: "{{ created_vm.vmid }}"
usb:
usb0: "spice,usb3=1"
update: true
when: spice_usb | default(false)
Зверни увагу: передається vmid, а не name. Щойно маєш ID, використовуй його. Це єдиний ідентифікатор, який API вважає унікальним.
А для того, що вміє QEMU, але для чого в PVE немає параметра, є args, який передається в командний рядок QEMU дослівно:
args: >-
-global scsi-hd.physical_block_size=4k
-global scsi-hd.logical_block_size=4096
Цей показує віртуальний диск як 4Kn, а не 512e, і це важливіше, ніж здається: розміри блоків, 4Kn і 512e. Модуль позначає args як «for experts only», і причина в тому, що PVE його не перевіряє, а поганий прапорець не дає VM завантажитися з помилкою, яка йде від QEMU, а не від Proxmox.
Кластер не одразу узгоджений
- name: Let registration complete on cluster
ansible.builtin.pause:
seconds: 5
when: created_vm.changed
pause у плейбуку зазвичай поганий знак, але цей несе навантаження. Виклик створення повертається, коли API прийняв опис, а це не те саме, що всі вузли погодилися, що VM існує, а вже наступна задача хоче задати ACL на /vms/<vmid>. П’ять секунд терпіння дешевші за цикл повторів навколо помилки, яка з’являється лише під навантаженням.
Плейбук розбирання має ту саму форму з тієї самої причини: зупинити, зачекати, потім видалити.
Зчитати назад те, що збудував
proxmox_kvm документує три значення, що повертаються: vmid, status і msg. На практиці тобі знадобиться четверте, і його немає в документації.
- name: Get MAC address of VM
ansible.builtin.set_fact:
primary_mac_addr: "{{ created_vm.mac.net0 }}"
created_vm.mac справжнє: модуль будує його в get_vminfo() і вкидає в результат, але його немає в задокументованому блоці RETURN, а отже, ніщо не обіцяє, що воно й далі працюватиме. Варто точно знати, як воно поводиться, бо в ньому дві пастки:
- Воно з’являється лише тоді, коли модуль справді створив VM.
macзбирається лише на шляху створення й розгортання. Піди гілкою «вже існує», і в результаті будутьvmidіmsg, і більше нічого. - Воно містить лише ті інтерфейси, які ти передав. Код проходить параметри, які надав ти, вибирає ті, що відповідають
net[0-9], і для кожного зчитує збережену конфігурацію з API. Немає параметраnet, немає ключаmac.
Ось чому робочому плейбуку потрібні обидві половини, і друга негарна:
- name: Get MAC address of VM
ansible.builtin.set_fact:
primary_mac_addr: >-
{{ created_vm.mac.net0 if created_vm is defined and created_vm.changed
else ((existing_vm.proxmox_vms[0].config.net0 | split(','))[0] | split('='))[1] }}
Коли VM уже існувала, mac немає, тож MAC доводиться видлубувати з сирого рядка конфігурації. net0 приходить з API як virtio=AE:AE:5C:A8:89:85,bridge=vmbr0, тож: розбити за комами, взяти перше поле, розбити за =, взяти другу половину. Це хірургія рядків на відповіді API, і це чесна ціна модуля, чия форма результату залежить від того, якою гілкою він пішов.
Якщо MAC потрібна надійно в обох випадках, бери її з proxmox_vm_info безумовно і розбирай одну форму замість двох.
Керування з джерела істини
Ще раз поглянь на рядок, з якого починається play:
hosts: "{{ target_hosts | default('cluster_pve:&status_planned') }}"
Це і є справжня архітектура, і варто сказати це прямо: VM, які треба збудувати, не є списком у файлі змінних. Це хости в твоєму інвентарі, чий записаний статус каже, що вони мають існувати, а їх ще немає.
Інвентар тут NetBox. VM замовляють, створюючи запис у NetBox зі статусом planned, де вказано CPU, пам’ять, диск, VLAN, власника і платформу. Плейбук вибирає машини planned, будує їх, виділяє IP, записує DNS, а потім ставить запису статус staged, і в цю мить цей хост більше не відповідає шаблону хостів play, а обробник оновлює інвентар, щоб наступний play побачив новий стан:
handlers:
- name: Refresh inventory
ansible.builtin.meta: refresh_inventory
Поле статусу це скінченний автомат, плейбук один перехід у ньому, і все це можна запускати повторно, бо хост, який уже пішов далі, більше не вибирається. Це набагато краща властивість, ніж будь-яка ідемпотентність на рівні модуля, і саме тому задача створення може дозволити собі бути одноразовою.
community.proxmox також постачає власний плагін інвентарю, який будує інвентар з кластера, і це правильний вибір, коли джерелом істини є Proxmox. Тут навпаки: NetBox авторитетний, а Proxmox це місце, де втілюється його намір. Це тема для окремого допису, і я напишу його окремо.
Прибрати все назад
Створення без розбирання це пів життєвого циклу, і шлях видалення має власну пастку: не можна видалити запущену VM:
- name: Force stop the VM if it is running
delegate_to: localhost
community.proxmox.proxmox_kvm:
api_host: "{{ proxmox_api_ip }}"
api_user: "{{ proxmox_user }}"
api_password: "{{ proxmox_password }}"
name: "{{ inventory_hostname }}"
state: stopped
force: true
timeout: 10
- name: Allow the cluster to stop the VM before removing it
ansible.builtin.pause:
seconds: 10
- name: Remove the VM from the cluster
delegate_to: localhost
community.proxmox.proxmox_kvm:
api_host: "{{ proxmox_api_ip }}"
api_user: "{{ proxmox_user }}"
api_password: "{{ proxmox_password }}"
name: "{{ inventory_hostname }}"
state: absent
force: true
timeout: 10
state: stopped означає м’яке вимкнення, і взаємодія з timeout задокументована, її варто запам’ятати: якщо тайм-аут досягнуто з force: true, VM вимикається жорстко; з force: false задача натомість падає. Десятисекундне вікно для м’якого вимкнення, а потім висмикнути вилку, розумна політика для машини, яку розбирають, і жахлива для всього іншого.
Повне розбирання (proxmox-remove-vms.yml) потім розмотує решту запису: DNS, виділений IP, інтерфейси в NetBox, VM у NetBox і застарілі записи в known_hosts. Він обгортає блок в ignore_errors: true, що в розбиранні виправдано. Ти видаляєш речі, яких уже може не бути, а напіввидалена машина гірша за галасливий журнал.
Що я змінив би в новому збиранні
Прочитавши вихідний код модуля, а не лише його документацію, п’ять речей:
- Використовуй API-токен, а не
api_userразом зapi_password. Обмежена область дії, можна відкликати, і він ніколи не належить людині. - Задай
validate_certsявно, перш ніж 2.0.0 змінить його під тобою. - Виділяй VMID сам із джерела істини. Це прибирає гонку «прочитай, зміни, запиши», дає змогу відмовитися від
serial: 1і дає кожній пізнішій задачі стабільний ідентифікатор замість назви, яка не унікальна. - Створюй VM голою, а потім під’єднуй її диски й NIC через
proxmox_diskіproxmox_nic. Задач більше, але тоді кожен диск і інтерфейс має модуль, який може змінити його пізніше, включно зcreate: disabledдля правок лише параметрів іstate: detachedзамість видалення, а не конфігурацію, яку можна змінити лише черезupdate_unsafe. - Бери MAC з
proxmox_vm_infoв одному місці, щоб розбирати одну форму замість умови між задокументованим і незадокументованим значенням.
І не берися за --check на плейбуку збирання. Модуль, який має значення, не може його дотриматися.
Пробний запуск, який завжди каже «так», гірший за відсутність пробного запуску, бо ти йому повіриш.
Джерела
- community.proxmox collection docs — уся поверхня з 47 модулів
- community.proxmox on GitHub — де лежить згаданий вище код;
plugins/modules/proxmox_kvm.pyце файл, який варто читати, коли документація неоднозначна proxmox_kvmmodule documentation — список параметрів і попередженняupdate/update_unsafe, процитовані вищеproxmox_vm_infomodule documentation —config: currentіconfig: pending- PVE
qmoptions reference — справжня специфікація кожного рядкаscsi[n],net[n]іboot, який ти передаєш - proxmoxer — клієнт Python, на якому побудовано колекцію
- damo2929/ansible-example — плейбуки, з яких узято ці уривки, включно з інвентарем на основі NetBox, генерацією DHCP і збиранням гіпервізора