Automatyzacja Proxmox VE:
Ansible i Terraform

API i tokeny (oficjalne)

Każda akcja panelu ma odpowiednik API. Token: użytkownik + token ID, ACL jak u człowieka, z 2FA na koncie człowieka i bez 2FA na automacie (TFA and Automated Access w PBS/PVE). Nie wkłada się hasła root w pipeline. Ścieżki ACL wąskie: jedna pula, jeden storage, bez Sys.Modify na całym datacenter.

Dokumentacja API jest w GUI (Datacenter → Permissions → API Tokens) i w pveum. To warstwa, na której stoją Terraform i Ansible — nie odwrotnie.

Terraform: bpg/proxmox

W registry: bpg/proxmox (społeczność). Starszy Telmate/proxmox nadal się zdarza w forkach — przy nowym projekcie bierzemy bpg. Nie jest to oficjalny provider Proxmox GmbH. Stan (state) trzymajcie poza klastrem. Zasoby: VM, CT, network, storage mapping — zakres zależy od wersji providera, nie od „wszystkiego, co umie GUI”.

vSphere ma oficjalny vmware/vsphere. Na PVE nie ma odpowiednika z pieczątką Proxmoxa. To trzeba wpisać w ryzyka projektu IaC, nie zamiatać.

W praktyce pinujemy wersję providera (numer w required_providers), recenzujemy changelog przed upgrade’em i nie mieszamy Telmate z bpg w jednym state. API PVE jest wersjonowane; provider społecznościowy dogania je z opóźnieniem. Dlatego dzień zero klastra i Ceph zostają w runbooku, a Terraform bierze gości, tagi, mostki i VNet, które provider faktycznie umie.

Ansible: community.general

Moduły community.general.proxmox, proxmox_kvm, proxmox_pct, proxmox_template wołają to samo API. Kolekcja jest społecznościowa (Ansible / contributors), nie „Ansible certified Proxmox”. Nadaje się do idempotentnego tworzenia CT/VM, snapshotów, start/stop. Nie zastępuje terraform state przy dwudziestu warstwach sieci SDN. W praktyce Ansible idempotentnie woła API do CT/VM, a Terraform trzyma sieć i tagi, które mają być w git. Dwa narzędzia na tym samym obiekcie bez podziału odpowiedzialności dają dryf: GUI, Ansible i Terraform nadpisują się nawzajem.

Cloud-init i obrazy

PVE obsługuje cloud-init przy VM (vendor/meta/network). Terraform i Ansible podają user-data. Szablony CT z pveam, obrazy cloud z vendorów Linux. Windows: cloudbase-init albo sysprep we własnym złotym obrazie — nie obiecujemy „cloud-init jak na Debianie”.

Czego nie automatyzować na ślepo

• Tworzenie klastra Corosync i QDevice „z Terraforma przy pierwszym bootcie” bez runbooka sieci — kworum to nie zasób cloud.
• Kasowanie datastore PBS tokenem, który też robi backup (patrz PBS i ransomware).
• VM/CT, cloud-init, tagi, affinity, SDN VNet — tak, z review PR i state w S3/Git.

Tokeny: wąskie ACL

Dokumentacja API i pveum: token = użytkownik + token ID, te same ścieżki ACL co człowiek. 2FA na koncie operatora, bez 2FA na automacie (TFA and Automated Access). Hasła root nie ma w CI. Osobny token na Terraform (VM/CT/sieć), osobny na Ansible (jeśli w ogóle woła PVE), żaden nie ma Datastore.Modify na PBS ani Sys.Modify na całym datacenter „na wszelki wypadek”.

Moduły Ansible community.general.proxmox, proxmox_kvm, proxmox_pct, proxmox_template wołają to samo API. Nie są „Ansible certified Proxmox”. Nadają się do CT/VM, snapshotów, start/stop — nie do dwudziestu warstw SDN jako źródła prawdy.

State, SDN i dzień zero

Stan Terraform trzymamy poza klastrem (S3/Git z lockiem). Provider bpg nie pokrywa „wszystkiego, co umie GUI” — zakres zależy od wersji. Klaster Corosync, QDevice i OSD Ceph zostawiamy na runbook dnia zero, nie na apply przy pierwszym bootcie bez sieci kworum. PBS: token backupu nie kasuje datastore — patrz PBS i ransomware.

Cloud-init na VM (vendor/meta/network) jest w PVE; Windows to cloudbase-init albo sysprep we własnym obrazie, nie „cloud-init jak na Debianie”. Szablony CT z pveam.

pvesh i eksplorator API

Każda akcja GUI ma ścieżkę REST. pvesh to klient CLI tego API na węźle (get/set/create/delete/ls). Eksplorator w GUI (Documentation → API Viewer) pokazuje te same ścieżki, które woła Terraform. To warstwa producenta. Provider bpg i kolekcja Ansible są nad nią i mogą zalegać względem nowej wersji PVE — stąd pin wersji i changelog przed upgrade’em.

Token API z 2FA na koncie człowieka i bez 2FA na automacie (TFA and Automated Access) jest w dokumentacji PVE/PBS. Privilege Separation: token dziedziczy ACL użytkownika, ale da się go zawęzić. Osobny token na Terraform, osobny na backup PBS — żaden nie ma obu światów.