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ą:

Gdzie naprawdę wykonuje się każde zadanie playbooka budującego ProxmoxWęzeł sterujący Ansibledelegate_to: localhostproxmox_kvmproxmox_vm_infoproxmox_diskproxmox_access_aclkażdy z nich toklient HTTPS, a nie agentproxmoxer ≥ 2.0 + requestsinstalowane tu, nie na węźlegather_facts: falseWęzeł Proxmox: pve1pvedaemon, REST APIna porcie 8006qm, /etc/pve, storagetu ląduje definicja maszynymaszyna, którą tworzyszbez IP · bez SSH · bez Pythonabez systemu operacyjnegow inwentarzu to tylkonazwa i worek zmiennychAPISSHqm setstatnie ma się z czym łączyćdopiero w późniejszym playu
Trzy konteksty wykonania w jednym playu. Moduły Proxmox nigdy nie dotykają węzła ani gościa: to klienci HTTPS działający obok playbooka. Furtka 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 false and changes default to true with 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 updating net update the MAC address and virtio create 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_modediff_mode
proxmox_kvmbrakbrak
proxmox_diskbrakbrak
proxmox_templatebrakbrak
proxmox_snappełnybrak
proxmox_nicpełnybrak
proxmox_poolpełnybrak

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.

Co naprawdę robi drugi przebieg proxmox_kvmdrugi przebieg: state: present, a maszyna o tej nazwie istniejemoduł nigdy nie porównuje twoich parametrów z działającą maszynąupdate: falsedomyślniechanged = false„VM with name <x>already exists”zmień memory w playu,uruchom ponownie, a nicnigdzie ci nie powieupdate: truezbieżna większośćcores, memory, tags,agent, onboot zastosowanenet, virtio, ide, sata,scsi, efidisk0, tpmstate0odrzucone celowodo nich użyj proxmox_diski proxmox_nicupdate_unsafe: truezbieżne wszystkoodrzucone parametryteż są stosowaneparametr dysku możeutworzyć dysk od nowatrwała utrata danychto udokumentowane ryzyko--checknic ci nie mówicheck_mode: nonezadanie jest pomijanekażde późniejsze zadanierozumuje o świecie,w którym maszynynigdy nie utworzonoTylko dwie z czterech cokolwiek zbiegają, a ta, któraobejmuje dyski, to ta, która może je zniszczyć.Więc sam rób bramkę na istnienie i traktuj tworzeniejako jednorazowe zdarzenie.
Co naprawdę robi drugi przebieg. Tylko dwie z czterech ścieżek w ogóle cokolwiek doprowadzają do zbieżności, a jedyna, która obejmuje dyski, to ta, która może je zniszczyć.

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:

  • rate jest 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: true odłą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.
  • trunks przyjmuje listę identyfikatorów VLAN do przepuszczenia, dla gościa, który sam taguje.
  • mtu: 1 to nie literówka i nie MTU o długości 1 bajta: znaczy „dziedzicz MTU bridge’a” i dotyczy tylko virtio.
  • queues ustawia 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ń:

stateCo się dziejeOdwracalne?
presenttworzy dysk albo aktualizuje opcje istniejącegon/d
resizedpowiększa go: PVE nie umie zmniejszać, a dokumentacja każe robić to ręcznienie
detachedstaje się unused[n]; wolumin i jego dane zostajątak
movedzmienia storage pod spodem albo przekazuje dysk innej maszynieoryginał zostaje, chyba że delete_moved
absentusunięty ze storage pod spodemnie

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 zmieniasz cache albo iothread na 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 jak proxmox_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ć toUżyj
Utworzyć maszynęproxmox_kvm, raz, z bramką na istnienie
Zmienić rdzenie, pamięć, tagi, agenta, onbootproxmox_kvm z update: true
Dodać, przetagować, odłączyć albo usunąć kartę sieciowąproxmox_nic
Dodać, powiększyć, przenieść, odłączyć albo usunąć dyskproxmox_disk
Snapshotproxmox_snap (też pełny tryb sprawdzania)
Cokolwiek, czego żaden z nich nie udostępniaqm set przez SSH
Zmienić dysk albo kartę sieciową przez proxmox_kvmnic: 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:

  1. Pojawia się tylko wtedy, gdy moduł faktycznie utworzył maszynę. mac jest składane tylko na ścieżce tworzenia i wdrażania. Pójdź gałęzią „already exists”, a wynik ma vmid i msg i nic więcej.
  2. 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 parametru net, brak klucza mac.

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_user plus api_password. Ma zakres, da się go odwołać i nigdy nie należy do osoby.
  • Ustaw validate_certs jawnie, 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: 1 i 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_disk i proxmox_nic. Więcej zadań, ale każdy dysk i interfejs ma wtedy moduł, który może go później zmienić, w tym create: disabled dla edycji samych opcji i state: detached zamiast usuwania, a nie konfigurację, którą da się zmienić tylko przez update_unsafe.
  • Pobieraj MAC z proxmox_vm_info w 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