Założenie, które Ansible zwykle może przyjąć
Prawie każdy moduł Ansible, którego używałeś, działa tak: Ansible łączy się z hostem wymienionym w inwentarzu, kopiuje na niego mały program w Pythonie, uruchamia go i odczytuje wynik. Host jest tym, co się zmienia, i tym, co wykonuje pracę.
Tworzenie maszyny wirtualnej łamie to w najbardziej podstawowy możliwy sposób. Host, który budujesz, nie istnieje. Nie ma IP, nie ma demona SSH, nie ma Pythona i nie ma systemu operacyjnego. Nie ma się z czym połączyć.
community.proxmox nie jest więc agentem konfiguracji. To klient API, który akurat jest dostarczany jako kolekcja Ansible. W związku z tym wszystko w tym wpisie wynika z tego jednego faktu: gdzie wykonują się zadania, jak dostarczasz poświadczenia, dlaczego ponowne uruchomienie nie robi tego, czego się spodziewasz, i dlaczego --check nie mówi ci prawdy.
Przykłady są tu przycięte z playbooka, który buduje maszyny wirtualne z Windows i Linuksem z rekordów NetBox: proxmox-create-vms.yml. Dla czytelności uogólniłem nazwy węzła, storage i bridge’a; prawdziwa wersja jest w tym repozytorium.
Wszystko, co niżej twierdzę o zachowaniu modułów, sprawdziłem na community.proxmox 1.6.0, czyli wersji, którą mam zainstalowaną:
$ ansible-galaxy collection list community.proxmox
# /home/damien/.ansible/collections/ansible_collections
Collection Version
----------------- -------
community.proxmox 1.6.0
Najpierw: kolekcja się przeniosła
Jeśli czytasz starszy playbook albo starszą odpowiedź, moduły nazywały się community.general.proxmox_kvm. Teraz żyją we własnej kolekcji i to tam toczy się rozwój. Wersja 1.6.0 zawiera 47 modułów, obejmujących Ceph, SDN, firewall, reguły HA i dołączanie do klastra, z których żaden nie istniał w czasach community.general.
ansible-galaxy collection install community.proxmox
pip install 'proxmoxer>=2.0' requests
Zależność od Pythona nie jest opcjonalna ani dołączona: kolekcja deklaruje requirements: ["proxmoxer >= 2.0", "requests"], a trzeba je zainstalować tam, gdzie moduł faktycznie się wykonuje, czyli, jak wyjaśnia następna sekcja, nie na węźle Proxmox.
requirements.yml, jeśli wolisz to przypiąć:
---
collections:
- name: community.proxmox
version: ">=1.6.0"
Kolekcja jest testowana na ansible-core od 2.17 do 2.20. Zmiana nazw zadań community.general.proxmox_* na community.proxmox.proxmox_* to większość migracji.
Każde zadanie Proxmox wykonuje się na localhost
Dwie linijki na górze playa robią najcięższą robotę i obie wyglądają, jakby wyłączały coś przydatnego:
- name: Create Proxmox virtual machines
hosts: "{{ target_hosts | default('cluster_pve:&status_planned') }}"
gather_facts: false
serial: 1
gather_facts: false to nie optymalizacja. Zbieranie faktów łączy się z hostem z inwentarza, a host z inwentarza to maszyna wirtualna, której jeszcze nie zbudowano. Zostaw to włączone, a play padnie przed pierwszym zadaniem.
Potem każde zadanie Proxmox ma 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 }}"
...
Host z inwentarza to teraz tylko nazwa i worek zmiennych. inventory_hostname staje się nazwą maszyny wirtualnej; jej zmienne opisują maszynę, którą chcesz. Nic się z nim nie łączy. Zadanie wykonuje się na węźle sterującym, który otwiera sesję HTTPS do api_host i wysyła definicję maszyny.
Zobaczysz to też zapisane jako local_action:, czyli starszą składnię tego samego. Playbook do rozbiórki w tamtym repozytorium używa jej wszędzie. Są równoważne. delegate_to to obecna pisownia.
Furtka awaryjna wskazuje na węzeł
Niektóre rzeczy naprawdę muszą się dziać na hoście Proxmox, a te zadania delegują gdzie indziej:
- 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
To prawdziwe połączenie SSH do prawdziwego węzła, sprawdzające prawdziwą ścieżkę na współdzielonym storage, bo API chętnie przyjmie odwołanie do ISO, które nie wskazuje na żaden plik, a wolisz się o tym dowiedzieć teraz niż przy rozruchu. Zwróć uwagę na chirurgię napisów, która tłumaczy odwołanie do storage PVE (isos:iso/debian.iso) na ścieżkę w systemie plików. Abstrakcja storage nie jest dostępna dla stat.
Jeden play ma więc zadania wykonywane w trzech różnych miejscach, a pomylenie ich to najczęstszy sposób, w jaki te playbooki padają:
qm to jedyna część, która potrzebuje SSH do hiperwizora.Poświadczenia i wartość domyślna, która zaraz się zmieni
Opcje uwierzytelniania są wspólne dla każdego modułu kolekcji przez fragment dokumentacji, więc wszędzie są takie same: api_host, api_user, a potem albo api_password, albo para api_token_id / api_token_secret. Wszystkie mają zapasowe zmienne środowiskowe, PROXMOX_HOST, PROXMOX_USER, PROXMOX_PASSWORD, PROXMOX_TOKEN_ID, PROXMOX_TOKEN_SECRET, PROXMOX_VALIDATE_CERTS, co jest najczystszym sposobem, żeby całkowicie trzymać sekrety poza playem.
Token API to lepsza wartość domyślna. Ma zakres, da się go odwołać bez zmiany hasła człowieka i można mu dać dokładnie te uprawnienia, których potrzebuje playbook, a nie te, które akurat ma jakaś osoba:
- 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
Ustaw validate_certs jawnie, już dziś. Dokumentacja samej kolekcji mówi to wprost:
Currently defaults to
falseand changes default totruewith community.proxmox 2.0.0.
Co znaczy, że playbook, który o tym nie wspomina, teraz nie weryfikuje TLS, a zacznie weryfikować, i przez to zacznie padać na samopodpisanym certyfikacie, z którym przychodzi każda świeża instalacja Proxmox, w chwili gdy ktoś uruchomi --upgrade. Lepiej podjąć tę decyzję celowo, niż żeby spadła w środku budowy. Jeśli zostajesz przy samopodpisanym certyfikacie, napisz validate_certs: false i przyjmij to ustalenie; jeśli masz porządny łańcuch, wskaż go w ca_path. Tak czy inaczej jest to zapisane.
Minimalne sensowne tworzenie
Okrój produkcyjne zadanie do tego, co faktycznie definiuje maszynę, i robi się czytelne:
- 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
Kilka rzeczy w tym kształcie warto wiedzieć, zanim napiszesz własny.
Opcje urządzeń to składnia PVE wewnątrz YAML. scsi, sata, net, virtio, ide mają wszystkie typ dict, z kluczami scsi0, net0 i tak dalej, a wartości to rozdzielane przecinkami napisy opcji prosto z man qm: <storage>:<size>,option=value dla dysku, [model=]<enum>,option=value dla karty sieciowej. Moduł ich nie modeluje; przekazuje je dalej. Kiedy coś zostaje odrzucone, odpowiedź jest w dokumentacji opcji PVE, a nie w dokumentacji Ansible.
Zobaczysz je też zapisane jako napis JSON zamiast mapowania YAML:
net: '{"net0":"virtio,bridge={{ vlan_bridge }}"}'
Oba działają. Ansible konwertuje napis dla parametru typu dict. Forma JSON istnieje, bo łatwiej zrobić szablon całej struktury w jednym wyrażeniu Jinja. Forma mapowania jest łatwiejsza do przeczytania pół roku później.
boot ma dwie generacje składni. Moduł przyjmuje stare litery, gdzie boot: "cdn" znaczy „spróbuj dysku, potem CD-ROM, potem sieci”. Obecne PVE chce jawnej uporządkowanej listy, boot: "order=scsi0;sata0;net0", która nie pozostawia wątpliwości, który dysk. Stara forma wciąż działa. Jawna forma to ta, której chcesz w nowej pracy. Jedna prawdziwa pułapka zakopana w dokumentacji modułu: rozruch sieciowy wymaga ustawienia rng0 od PVE 8.3.5.
numa i numa_enabled to różne parametry. numa_enabled to wartość logiczna, która włącza NUMA. numa to dict opisujący topologię (cpus, hostnodes, memory, policy). Ustawienie numa: true to błąd typu, a łatwo na nim stracić godzinę. Jeśli interesuje cię, dlaczego to wszystko ma znaczenie, wyrównanie NUMA w Proxmox omawia problem leżący u podstaw.
machine: q35 i bios: ovmf to właściwe wartości domyślne, a nie dekoracja; pełny wywód.
Pominięcie vmid znaczy, że moduł pyta API o następne wolne ID. Wygodne i bezpośrednia przyczyna następnej rzeczy.
Dlaczego serial: 1
„Pobierz następne dostępne ID, a potem utwórz z nim maszynę” to dwa wywołania API z przerwą w środku. Dwa procesy robiące to równocześnie mogą odczytać to samo wolne ID, a przegrany dostaje błąd albo, co gorsza, niespodziankę.
serial: 1 sprawia, że faza tworzenia idzie po jednym hoście naraz. Nie jest szybka i nie musi być. Kosztowna część budowania maszyny dzieje się po tym, jak ten playbook przekaże pałeczkę. Bliźniaczy play, który uruchamia gotowe maszyny, używa serial: 5, bo uruchamianie nie ma wspólnego licznika, o który można by się ścigać.
Jeśli wolisz równoległość, przydziel VMID sam ze swojego źródła prawdy i przekaż je jawnie. Wtedy nie ma odczytu-modyfikacji-zapisu i nie ma wyścigu.
Idempotencja to nie to, czego się spodziewasz
To sekcja do przeczytania dwa razy, bo proxmox_kvm nie zachowuje się jak ansible.builtin.package.
name nie jest tożsamością. Nazwy maszyn wirtualnych nie są unikalne w klastrze Proxmox i moduł to mówi. Przy state: present i bez vmid, jeśli maszyna o tej nazwie już istnieje, moduł kończy z changed=false i msg: "VM with name <x> already exists" i nic nie robi. Nie porównuje twoich parametrów z rzeczywistością. Nie dąży do zbieżności. Odmawia.
update ma domyślnie false. Edycja memory: w playbooku i ponowne uruchomienie to więc no-op. Maszyna zatrzymuje pamięć, z którą ją zbudowano, zadanie zgłasza sukces i nic nigdzie nie mówi ci, że te dwie rzeczy się rozjechały.
update: true wciąż odmawia ciekawych parametrów. Z dokumentacji modułu:
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 znosi to ograniczenie, a ostrzeżenie nie jest na pokaz:
Use this option with caution because an improper configuration might result in a permanent loss of data (for example disk recreated).
Dysk, który myślałeś, że powiększasz, może więc zostać zastąpiony nowym, pustym. Nie sięgaj po to: odrzucone parametry mają własne moduły, a to jest następna sekcja.
A --check nie obejmuje niczego z tego. Kolekcja deklaruje obsługę trybu sprawdzania dla każdego modułu z osobna i jest niespójna dokładnie w złym kierunku:
| Moduł | check_mode | diff_mode |
|---|---|---|
proxmox_kvm | brak | brak |
proxmox_disk | brak | brak |
proxmox_template | brak | brak |
proxmox_snap | pełny | brak |
proxmox_nic | pełny | brak |
proxmox_pool | pełny | brak |
Podział nie przebiega tak, że „moduły tylko do odczytu mogą, moduły zapisujące nie”: proxmox_nic tworzy i usuwa interfejsy, a tryb sprawdzania honoruje bez zarzutu. Chodzi o to, że trzy moduły zajmujące się storage i cyklem życia maszyny go nie mają. Przebieg --check playbooka budującego po cichu pomija tworzenie maszyny, a potem raportuje o świecie, w którym maszyny nigdy nie zrobiono, więc każde następne zadanie rozumuje o złym stanie. Na playbooku budującym --check to nie siatka bezpieczeństwa, a traktowanie go jak siatki jest gorsze niż nieuruchamianie go wcale.
Niech więc istnienie będzie bramką
Biorąc to wszystko pod uwagę, wykonalny wzorzec to przestać prosić moduł o idempotencję i samemu zdecydować, czy budować. Playbook produkcyjny robi to tak:
- 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 z config: current zwraca maszynę i jej bieżącą konfigurację albo pustą listę. failed_when zamienia „pustą listę” w porażkę, ignore_errors: true nie pozwala tej porażce zakończyć playa, a when: existing_vm is failed staje się „maszyny nie ma, zbuduj ją”.
Używanie celowo nieudanego zadania jako wartości logicznej czyta się źle i nie będę udawał, że jest inaczej. Alternatywa to when: (existing_vm.proxmox_vms | default([]) | length) == 0, która uczciwie jest sprawdzeniem długości i nie potrzebuje ignore_errors. Oba działają. Wersja wyżej jest tą, która jest na produkcji, a jej jedyna prawdziwa przewaga to to, że zarejestrowany wynik niesie istniejącą konfigurację do odczytu przez późniejsze zadania.
Ważny jest kształt, nie pisownia: sprawdź, potem rozgałęź i traktuj tworzenie jako jednorazowe zdarzenie. Bieżąca konfiguracja maszyny to inny problem niż jej istnienie, a ten moduł jest dobry tylko w tym drugim.
Dyski i karty sieciowe mają własne moduły
Oto rzecz, którą wyżej prześlizgnąłem, a która zmienia cały obraz: parametry, których proxmox_kvm odmawia aktualizować, to nie luka w kolekcji. Są delegowane. community.proxmox.proxmox_disk i community.proxmox.proxmox_nic dodają, zmieniają i usuwają dokładnie to, czego moduł tworzący nie ruszy, z kluczami według tych samych nazw scsi0 i net0, których użyłeś przy budowie maszyny.
Oba zachowują się lepiej niż proxmox_kvm, a jeden z nich to jedyny moduł w tym procesie, który można uruchomić na sucho.
proxmox_nic: dodaj, przetaguj albo usuń interfejs
- 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 to jedyna wymagana opcja poza uwierzytelnianiem, net[n], gdzie n to od 0 do 31, a state: present albo absent daje ci dodawanie i usuwanie. model ma domyślnie virtio, co jest właściwą odpowiedzią, chyba że gość sobie nie radzi.
Powodem istnienia tego modułu jest adres MAC. Przypomnij sobie, dlaczego proxmox_kvm odmawia aktualizacji net: „updating net update the MAC address”. proxmox_nic naprawia to jawnie:
When not specified this module will keep the MAC address the same when changing an existing interface.
Możesz więc przetagować VLAN, przenieść bridge, zmienić MTU albo włączyć firewall bez zmiany tożsamości karty sieciowej gościa pod jego stopami. To ma większe znaczenie, niż brzmi: nowy MAC unieważnia rezerwacje DHCP, psuje wszystko, co jest licencjonowane na kartę sieciową, i rozsynchronizowuje rekord interfejsu w NetBox, który playbook tworzący tak starannie zapisał. To moduł, dzięki któremu zmiana sieci w dniu drugim może być nudna.
Kilka opcji, które warto znać, zanim będą potrzebne:
ratejest w MBps, czyli megabajtach na sekundę, nie w bitach. Dokumentacja mówi to jasno, a błąd o czynnik osiem bardzo łatwo popełnić.link_down: trueodłącza interfejs, co dokumentacja opisuje jako „like pulling the plug”. Czysty sposób na izolację podejrzanej maszyny bez zatrzymywania jej i bez dotykania gościa.trunksprzyjmuje listę identyfikatorów VLAN do przepuszczenia, dla gościa, który sam taguje.mtu: 1to nie literówka i nie MTU o długości 1 bajta: znaczy „dziedzicz MTU bridge’a” i dotyczy tylkovirtio.queuesustawia multiqueue, od 0 do 16. Warto dopasować do liczby vCPU na czymkolwiek, co przepycha prawdziwy ruch.
I w pełni obsługuje tryb sprawdzania. --check na zadaniu proxmox_nic mówi ci prawdę, co czyni je jedyną częścią tego procesu, którą możesz bezpiecznie przećwiczyć. Jego komunikaty też są porządnie idempotentne. Niezmieniony interfejs zgłasza Nic net0 unchanged on VM with vmid 103, zamiast twierdzić, że coś zmienił.
proxmox_disk: cały cykl życia dysku
proxmox_disk to największy moduł z trzech, a jego state wykonuje pięć różnych zadań:
state | Co się dzieje | Odwracalne? |
|---|---|---|
present | tworzy dysk albo aktualizuje opcje istniejącego | n/d |
resized | powiększa go: PVE nie umie zmniejszać, a dokumentacja każe robić to ręcznie | nie |
detached | staje się unused[n]; wolumin i jego dane zostają | tak |
moved | zmienia storage pod spodem albo przekazuje dysk innej maszynie | oryginał zostaje, chyba że delete_moved |
absent | usunięty ze storage pod spodem | nie |
Różnica między detached a absent to siatka bezpieczeństwa, której proxmox_kvm nigdy ci nie daje. Odłączenie to zmiana konfiguracji; usunięcie niszczy dane. Dwa różne słowa, dwie różne konsekwencje.
Dodanie drugiego dysku do maszyny, która już istnieje:
- 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 to pokrętło, które powinien był mieć proxmox_kvm. Kontroluje, co wolno zrobić state: present:
regular(domyślne): utwórz dysk, jeśli go brakuje, w przeciwnym razie zaktualizuj jego opcje.disabled: tylko aktualizuj opcje i nigdy nie twórz. Po to sięgaj, kiedy zmieniaszcachealboiothreadna dysku, który musi już istnieć. Nie zaskoczy cię wyczarowaniem nowego woluminu, bo w kluczu była literówka.forced: zawsze twórz. Istniejący dysk zostaje odłączony i pozostawiony jako nieużywany, a nie usunięty.
To ostatnie zachowanie to ważny szczegół. create: forced to opcja wyglądająca na niszczącą, a i tak niczego nie niszczy: stary wolumin przeżywa jako unusedN i możesz go podłączyć z powrotem. Porównaj to z proxmox_kvm plus update_unsafe, którego udokumentowany tryb awarii to dysk utworzony od nowa. Z grubsza ta sama operacja, dużo lepszy promień rażenia.
Powiększanie dysku:
- 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
Uważaj na jednostki, bo size zmienia znaczenie razem ze state. Przy state: present to GiB jako goła liczba (size: 200). Przy state: resized przyjmuje przyrostek: +100G, żeby dodać do bieżącego rozmiaru, albo 500G jako cel bezwzględny. Jeden parametr, dwie konwencje, a jeśli źle zgadniesz, porażka jest cicha.
Przenoszenie dysku na inny storage, czyli przypadek migracji na żywo jednego woluminu:
- 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 przenosi w obrębie jednej maszyny; target_vmid przekazuje dysk innej maszynie i wymaga tego samego storage po obu stronach. Wzajemnie się wykluczają. delete_moved ma domyślnie false, więc domyślnie kończysz z dwiema kopiami, a oryginał leży jako nieużywany: bezpiecznie, i dobry sposób na zapchanie puli storage, jeśli nigdy do tego nie wrócisz.
timeout ma tu domyślnie 600, wobec 30 w proxmox_kvm. Parametr wyglądający tak samo, dwudziestokrotna różnica, bo te operacje kopiują dane. Podnieś go dla dużych obrazów albo wolnego storage; dokumentacja mówi to i dla moved, i dla import_from.
Co prowadzi do opcji, która czyni ten moduł ścieżką dla V2V i obrazów chmurowych:
import_from: "vmdata:9000/base-debian13.qcow2"
import_from buduje dysk z istniejącego woluminu, zamiast przydzielać pusty: <STORAGE>:<VMID>/<NAME> albo <STORAGE>:import/<NAME>, z użyciem katalogu importu storage w PVE 9.x i nowszych. Wyklucza się z size, a ścieżek bezwzględnych w systemie plików może używać tylko root.
Reszta listy parametrów to powód, żeby podłączać dyski tym modułem, a nie w wywołaniu tworzącym: cache, aio, iothread, discard, ssd, backup, detect_zeroes i cała rodzina dławienia, iops, iops_rd, iops_wr, ich warianty _max i _max_length oraz kontrolki burst bps_*_max_length. Nic z tego nie jest osiągalne przez proxmox_kvm po utworzeniu.
Dwa zastrzeżenia, oba z dokumentacji samego modułu:
- Niektóre zmiany opcji wymagają restartu. „Some updates on options (like
cache) are not being applied instantly and require VM restart.” Zielone zadanie znaczy, że konfiguracja została zapisana, a nie że działająca maszyna zachowuje się inaczej. - Nie obsługuje trybu sprawdzania.
check_mode: none, tak samo jakproxmox_kvm. Kolekcja dzieli się więc na pół: zmiany kart sieciowych da się przećwiczyć z--check, zmian dysków nie.
Podział pracy
| Żeby zrobić to | Użyj |
|---|---|
| Utworzyć maszynę | proxmox_kvm, raz, z bramką na istnienie |
| Zmienić rdzenie, pamięć, tagi, agenta, onboot | proxmox_kvm z update: true |
| Dodać, przetagować, odłączyć albo usunąć kartę sieciową | proxmox_nic |
| Dodać, powiększyć, przenieść, odłączyć albo usunąć dysk | proxmox_disk |
| Snapshot | proxmox_snap (też pełny tryb sprawdzania) |
| Cokolwiek, czego żaden z nich nie udostępnia | qm set przez SSH |
Zmienić dysk albo kartę sieciową przez proxmox_kvm | nic: do tego jest update_unsafe i właśnie dlatego nie powinieneś go używać |
Zbuduj maszynę minimalnym wywołaniem proxmox_kvm, a potem podłącz dyski i interfejsy ich własnymi modułami. To więcej zadań, i to jest wersja, w której zmiany w dniu drugim mają drogę, która nie wymaga opcji, której udokumentowanym ryzykiem jest utrata dysku.
Gdzie moduł się kończy
proxmox_kvm ma ogromną listę parametrów, a i tak nie obejmuje wszystkiego, co potrafi qm. Zamiast czekać, playbook produkcyjny schodzi do CLI na węźle:
- 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
Nie ma w tym nic złego. Nie jest idempotentne w żadnym sensownym znaczeniu, bo qm set to zapis i będzie zgłaszać changed przy każdym przebiegu, ale jest jawne, jest czytelne i niczego nie udaje. Jeśli moduł później zyska ten parametr, usuwasz zadanie.
Inne rzeczy wymagają drugiego przejścia przez moduł z update: true, bo nie da się ich ustawić w tym samym wywołaniu, które tworzy maszynę:
- 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)
Zwróć uwagę, że przekazuje vmid, a nie name. Kiedy masz ID, używaj go. To jedyny identyfikator, który API traktuje jako unikalny.
A dla rzeczy, które QEMU potrafi, a dla których PVE nie ma opcji, jest args, przekazywane do wiersza poleceń QEMU dosłownie:
args: >-
-global scsi-hd.physical_block_size=4k
-global scsi-hd.logical_block_size=4096
To przedstawia dysk wirtualny jako 4Kn zamiast 512e, co ma większe znaczenie, niż się wydaje: rozmiary bloków, 4Kn i 512e. Moduł opisuje args jako „for experts only”, a powód jest taki, że PVE tego nie waliduje, a zła flaga uniemożliwia rozruch maszyny z błędem pochodzącym od QEMU, a nie od Proxmox.
Klaster nie jest natychmiast spójny
- name: Let registration complete on cluster
ansible.builtin.pause:
seconds: 5
when: created_vm.changed
pause w playbooku to zwykle zły zapach, a ta jest nośna. Wywołanie tworzące wraca, kiedy API przyjęło definicję, a to nie to samo, co zgoda każdego węzła, że maszyna istnieje, a już następne zadanie chce ustawić ACL na /vms/<vmid>. Pięć sekund cierpliwości jest tańsze niż pętla ponowień wokół błędu, który pojawia się tylko pod obciążeniem.
Playbook do rozbiórki ma ten sam kształt z tego samego powodu: zatrzymaj, poczekaj, potem usuń.
Odczytanie tego, co zbudowałeś
proxmox_kvm dokumentuje trzy wartości zwrotne: vmid, status i msg. W praktyce będziesz chciał czwartej, a jej w dokumentacji nie ma.
- name: Get MAC address of VM
ansible.builtin.set_fact:
primary_mac_addr: "{{ created_vm.mac.net0 }}"
created_vm.mac jest prawdziwe, bo moduł buduje je w get_vminfo() i wrzuca do wyniku, ale nie ma go w udokumentowanym bloku RETURN, co znaczy, że nic nie obiecuje, że będzie dalej działać. Warto dokładnie wiedzieć, jak się zachowuje, bo są w nim dwie pułapki:
- Pojawia się tylko wtedy, gdy moduł faktycznie utworzył maszynę.
macjest składane tylko na ścieżce tworzenia i wdrażania. Pójdź gałęzią „already exists”, a wynik mavmidimsgi nic więcej. - Zawiera tylko interfejsy, które przekazałeś. Kod przechodzi po parametrach, które podałeś, wybiera te pasujące do
net[0-9], a potem odczytuje z API zapisaną konfigurację każdego z nich. Brak parametrunet, brak kluczamac.
Dlatego playbook produkcyjny potrzebuje obu połówek, a druga jest brzydka:
- 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] }}
Kiedy maszyna już istniała, nie ma mac, więc MAC trzeba wykopać z surowego napisu konfiguracji. net0 wraca z API jako virtio=AE:AE:5C:A8:89:85,bridge=vmbr0, więc: podziel po przecinkach, weź pierwsze pole, podziel po =, weź drugą połowę. To chirurgia napisów na odpowiedzi API i uczciwy koszt modułu, którego kształt odpowiedzi zależy od tego, którą gałęzią poszedł.
Jeśli potrzebujesz MAC niezawodnie w obu przypadkach, pobieraj go z proxmox_vm_info bezwarunkowo i parsuj jeden kształt zamiast dwóch.
Sterowanie ze źródła prawdy
Spójrz jeszcze raz na linijkę, która otwiera play:
hosts: "{{ target_hosts | default('cluster_pve:&status_planned') }}"
To jest faktyczna architektura i warto to powiedzieć wprost: maszyny do zbudowania to nie lista w pliku vars. To hosty w twoim inwentarzu, których zapisany status mówi, że powinny istnieć, a jeszcze nie istnieją.
Inwentarzem jest tu NetBox. Maszynę zamawia się przez utworzenie rekordu NetBox ze statusem planned, z jej CPU, pamięcią, dyskiem, VLAN, właścicielem i platformą. Playbook wybiera maszyny planned, buduje je, przydziela IP, zapisuje DNS, a potem ustawia rekord na staged, i w tym momencie ten host przestaje pasować do wzorca hostów playa, a handler odświeża inwentarz, żeby następny play widział nowy stan:
handlers:
- name: Refresh inventory
ansible.builtin.meta: refresh_inventory
Pole statusu to maszyna stanów, playbook to jedno przejście w niej, a całość da się uruchamiać ponownie, bo host, który już poszedł dalej, nie jest wybierany. To dużo lepsza własność niż jakakolwiek ilość idempotencji na poziomie modułu i to dzięki niej zadanie tworzące może sobie pozwolić na bycie jednorazowym.
community.proxmox ma też własną wtyczkę inwentarza, która buduje inwentarz z klastra: właściwy wybór, kiedy to Proxmox jest źródłem prawdy. Tutaj jest odwrotnie: NetBox jest autorytatywny, a Proxmox to miejsce, gdzie jego intencja się realizuje. To temat na osobny wpis i napiszę go oddzielnie.
Zabranie tego z powrotem
Tworzenie bez rozbiórki to pół cyklu życia, a ścieżka usuwania ma własną pułapkę: nie możesz usunąć działającej maszyny:
- 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 to łagodne wyłączenie, a jego interakcja z timeout jest udokumentowana i warta zapamiętania: jeśli timeout zostanie osiągnięty przy force: true, maszyna jest wyłączana twardo; przy force: false zadanie zamiast tego pada. Dziesięciosekundowe okno na łagodne wyłączenie, a potem wyciągnięcie wtyczki, to rozsądna polityka dla maszyny, którą się rozbiera, i fatalna dla czegokolwiek innego.
Pełna rozbiórka (proxmox-remove-vms.yml) odwija potem resztę rekordu: DNS, przydzielony IP, interfejsy w NetBox, maszynę w NetBox i nieaktualne wpisy w known_hosts. Opakowuje blok w ignore_errors: true, co w rozbiórce da się obronić. Usuwasz rzeczy, których może już nie być, a na wpół usunięta maszyna jest gorsza niż hałaśliwy log.
Co zmieniłbym w świeżej budowie
Po przeczytaniu źródła modułu, a nie tylko jego dokumentacji, pięć rzeczy:
- Używaj tokena API, a nie
api_userplusapi_password. Ma zakres, da się go odwołać i nigdy nie należy do osoby. - Ustaw
validate_certsjawnie, zanim 2.0.0 zmieni to pod tobą. - Przydzielaj VMID sam ze źródła prawdy. Usuwa to wyścig odczytu-modyfikacji-zapisu, pozwala zrezygnować z
serial: 1i daje każdemu późniejszemu zadaniu stabilny identyfikator zamiast nazwy, która nie jest unikalna. - Utwórz maszynę gołą, a potem podłącz jej dyski i karty sieciowe przez
proxmox_diskiproxmox_nic. Więcej zadań, ale każdy dysk i interfejs ma wtedy moduł, który może go później zmienić, w tymcreate: disableddla edycji samych opcji istate: detachedzamiast usuwania, a nie konfigurację, którą da się zmienić tylko przezupdate_unsafe. - Pobieraj MAC z
proxmox_vm_infow jednym miejscu, żeby był jeden kształt do parsowania zamiast warunku rozpiętego między udokumentowaną a nieudokumentowaną wartością zwrotną.
I nie sięgaj po --check na playbooku budującym. Moduł, który się liczy, nie może go honorować.
Próba na sucho, która zawsze mówi tak, jest gorsza niż żadna, bo jej uwierzysz.
Źródła
- community.proxmox collection docs — pełna powierzchnia 47 modułów
- community.proxmox on GitHub — tam żyje źródło omawiane wyżej;
plugins/modules/proxmox_kvm.pyto plik do przeczytania, kiedy dokumentacja jest niejednoznaczna proxmox_kvmmodule documentation — lista parametrów i cytowane wyżej ostrzeżeniaupdate/update_unsafeproxmox_vm_infomodule documentation —config: currenticonfig: pending- PVE
qmoptions reference — prawdziwa specyfikacja każdego napisuscsi[n],net[n]iboot, który przekazujesz dalej - proxmoxer — klient Pythona, na którym zbudowana jest kolekcja
- damo2929/ansible-example — playbooki, z których pochodzą te fragmenty, w tym inwentarz sterowany z NetBox, generowanie DHCP i budowa hiperwizora