वह धारणा जो Ansible आम तौर पर बना सकता है

आपने जो भी Ansible मॉड्यूल इस्तेमाल किया है, लगभग हर एक ऐसे काम करता है: Ansible इन्वेंटरी में लिखे होस्ट से कनेक्ट होता है, उस पर एक छोटा Python प्रोग्राम कॉपी करता है, उसे चलाता है, और नतीजा वापस पढ़ता है। होस्ट ही वह चीज़ है जो बदली जा रही है, और वही काम भी कर रहा है।

वर्चुअल मशीन बनाना इस बात को सबसे बुनियादी तरीक़े से तोड़ देता है। जो होस्ट आप बना रहे हैं, वह मौजूद ही नहीं है। न उसका IP है, न SSH daemon, न Python, न ऑपरेटिंग सिस्टम। कनेक्ट करने को कुछ है ही नहीं।

इसलिए community.proxmox कॉन्फ़िगरेशन एजेंट नहीं है। यह एक API क्लाइंट है जो संयोग से Ansible collection के रूप में आता है। इस पोस्ट में सब कुछ इसी एक बात से निकलता है: टास्क कहाँ चलते हैं, क्रेडेंशियल अंदर कैसे पहुँचाते हैं, दोबारा चलाने पर वह क्यों नहीं होता जो आप सोचते हैं, और --check आपको सच क्यों नहीं बता रहा।

यहाँ के उदाहरण एक प्लेबुक से काटकर छोटे किए गए हैं जो NetBox रिकॉर्ड से Windows और Linux VM बनाती है: 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

पहली बात: collection की जगह बदल गई है

अगर आप कोई पुरानी प्लेबुक या पुराना जवाब पढ़ रहे हैं, तो मॉड्यूल का नाम community.general.proxmox_kvm था। अब वे एक अलग collection में रहते हैं, और डेवलपमेंट वहीं हो रहा है। वर्ज़न 1.6.0 में 47 मॉड्यूल हैं, जो Ceph, SDN, फ़ायरवॉल, HA नियम और क्लस्टर join तक को कवर करते हैं। community.general के दौर में इनमें से कुछ भी नहीं था।

ansible-galaxy collection install community.proxmox
pip install 'proxmoxer>=2.0' requests

Python dependency वैकल्पिक नहीं है और साथ में बंडल भी नहीं है: collection requirements: ["proxmoxer >= 2.0", "requests"] घोषित करता है, और इन्हें वहाँ इंस्टॉल होना चाहिए जहाँ मॉड्यूल असल में चलता है। और जैसा अगला सेक्शन बताता है, वह जगह Proxmox नोड नहीं है।

अगर आप वर्ज़न पिन करना चाहें तो requirements.yml:

---
collections:
  - name: community.proxmox
    version: ">=1.6.0"

collection को 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 कोई optimisation नहीं है। फ़ैक्ट इकट्ठा करने के लिए इन्वेंटरी होस्ट से कनेक्ट होना पड़ता है, और इन्वेंटरी होस्ट एक ऐसी 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 का नाम बन जाता है, और उसके वेरिएबल्स उस मशीन का वर्णन करते हैं जो आप चाहते हैं। उससे कुछ भी कनेक्ट नहीं होता। टास्क कंट्रोल नोड पर चलता है, जो api_host से HTTPS सेशन खोलता है और VM की परिभाषा भेज देता है।

आपको यही चीज़ local_action: के रूप में भी लिखी दिखेगी, जो उसी काम का पुराना सिंटैक्स है। उस रिपॉज़िटरी की teardown प्लेबुक हर जगह यही इस्तेमाल करती है। दोनों बराबर हैं। delegate_to आज की वर्तनी है।

बच निकलने का रास्ता नोड की ओर जाता है

कुछ काम सच में Proxmox होस्ट पर ही होने चाहिए, और वे टास्क बिल्कुल अलग जगह delegate होते हैं:

- 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 कनेक्शन है, जो shared स्टोरेज पर एक असली path जाँच रहा है। वजह यह है कि API ख़ुशी-ख़ुशी ऐसा ISO reference स्वीकार कर लेगा जो किसी फ़ाइल तक नहीं पहुँचता, और यह बात बूट के समय के बजाय अभी पता चल जाए तो बेहतर है। ध्यान दें कि स्ट्रिंग की चीर-फाड़ करके PVE स्टोरेज reference (isos:iso/debian.iso) को फ़ाइलसिस्टम path में बदला जा रहा है। stat के पास स्टोरेज abstraction नहीं होता।

तो एक ही play में टास्क तीन अलग-अलग जगहों पर चल रहे होते हैं, और इन्हें आपस में मिला देना ही इन प्लेबुक के फ़ेल होने का सबसे आम कारण है:

Proxmox build playbook का हर टास्क असल में कहाँ चलता हैAnsible control nodedelegate_to: localhostproxmox_kvmproxmox_vm_infoproxmox_diskproxmox_access_aclइनमें से हर एकHTTPS client है, agent नहींproxmoxer ≥ 2.0 + requestsयहाँ इंस्टॉल, नोड पर नहींgather_facts: falseProxmox नोड: pve1pvedaemon, REST APIपोर्ट 8006 परqm, /etc/pve, storageVM की परिभाषा यहाँ पहुँचती हैजो VM आप बना रहे हैंन IP · न SSH · न Pythonकोई OS नहींinventory में यह सिर्फ़एक नाम और vars का थैला हैAPISSHqm setstatजोड़ने को कुछ नहींबाद की play तक नहीं
एक play में तीन execution context। Proxmox मॉड्यूल कभी नोड या guest को नहीं छूते, वे प्लेबुक के बगल में चल रहे HTTPS क्लाइंट हैं। qm वाला रास्ता ही अकेला हिस्सा है जिसे hypervisor तक SSH चाहिए।

क्रेडेंशियल, और एक डिफ़ॉल्ट जो बदलने वाला है

auth के विकल्प collection के हर मॉड्यूल में एक documentation fragment के ज़रिए साझा होते हैं, इसलिए हर जगह एक जैसे हैं: api_host, api_user, और फिर या तो api_password या फिर जोड़ी api_token_id / api_token_secret। ये सब environment variables पर fallback करते हैं: PROXMOX_HOST, PROXMOX_USER, PROXMOX_PASSWORD, PROXMOX_TOKEN_ID, PROXMOX_TOKEN_SECRET, PROXMOX_VALIDATE_CERTS। secrets को 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 आज ही साफ़-साफ़ सेट कीजिए। collection का अपना documentation इसे सीधे कहता है:

Currently defaults to false and changes default to true with community.proxmox 2.0.0.

मतलब जो प्लेबुक इसका ज़िक्र ही नहीं करती, वह अभी TLS validate नहीं कर रही, और जिस पल कोई --upgrade चलाएगा, वह validate करना शुरू कर देगी। यानी हर नए Proxmox इंस्टॉल के साथ आने वाले self-signed सर्टिफ़िकेट पर फ़ेल होना भी शुरू कर देगी। यह फ़ैसला सोच-समझकर लेना बेहतर है, बजाय इसके कि यह किसी बिल्ड के बीच में आ गिरे। अगर आप self-signed सर्टिफ़िकेट रख रहे हैं, तो validate_certs: false लिखिए और यह कमी स्वीकार कीजिए। अगर आपके पास ठीक-ठाक chain है, तो ca_path उस पर पॉइंट कीजिए। दोनों में से कुछ भी हो, बात लिखित में रहती है।

कम से कम जितना चाहिए, उतना create

प्रोडक्शन वाले टास्क को छीलकर सिर्फ़ उतना रखिए जो सच में मशीन को परिभाषित करता है, तो वह पढ़ने लायक़ हो जाता है:

- 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

अपना ख़ुद का लिखने से पहले इस ढांचे की कुछ बातें जान लेना अच्छा है।

डिवाइस वाले विकल्प YAML के अंदर PVE सिंटैक्स हैं। scsi, sata, net, virtio, ide सब dict टाइप के हैं, जिनकी keys scsi0, net0 वग़ैरह हैं, और values सीधे man qm से निकली comma से अलग की गई option strings हैं: डिस्क के लिए <storage>:<size>,option=value, NIC के लिए [model=]<enum>,option=value। मॉड्यूल इन्हें model नहीं करता, बस आगे भेज देता है। जब कुछ reject होता है, तो जवाब PVE options reference में मिलेगा, Ansible docs में नहीं।

आपको ये YAML mapping के बजाय JSON string के रूप में भी लिखे दिखेंगे:

    net: '{"net0":"virtio,bridge={{ vlan_bridge }}"}'

दोनों चलते हैं। dict टाइप वाले पैरामीटर के लिए Ansible string को अपने आप बदल लेता है। JSON वाला रूप इसलिए है कि पूरे ढांचे को एक Jinja expression में template करना आसान होता है। mapping वाला रूप छह महीने बाद पढ़ने में आसान होता है।

boot के सिंटैक्स की दो पीढ़ियाँ हैं। मॉड्यूल पुराने अक्षर स्वीकार करता है, जहाँ boot: "cdn" का मतलब है “पहले डिस्क, फिर CD-ROM, फिर नेटवर्क”। आज का PVE साफ़ क्रम वाली सूची चाहता है, boot: "order=scsi0;sata0;net0", जिसमें कौन सी डिस्क, इस पर कोई शक नहीं रहता। पुराना रूप अब भी चलता है। नए काम में आपको साफ़ वाला रूप चाहिए। मॉड्यूल docs में दबी एक असली पकड़: PVE 8.3.5 से नेटवर्क बूट के लिए rng0 सेट करना ज़रूरी है।

numa और numa_enabled अलग-अलग पैरामीटर हैं। numa_enabled वह boolean है जो NUMA चालू करता है। numa एक dict है जो topology बताता है (cpus, hostnodes, memory, policy)। numa: true सेट करना type error है, और इसमें आसानी से एक घंटा चला जाता है। अगर आपको जानना है कि यह सब क्यों मायने रखता है, तो Proxmox पर NUMA alignment असली समस्या को कवर करता है।

machine: q35 और bios: ovmf सही डिफ़ॉल्ट हैं, सजावट नहीं। पूरा तर्क यहाँ है।

vmid छोड़ देने का मतलब है कि मॉड्यूल API से अगली ख़ाली ID माँगता है। सुविधाजनक है, और अगली समस्या की सीधी वजह भी।

serial: 1 क्यों

“अगली उपलब्ध ID लो, फिर उससे VM बनाओ” दो API कॉल हैं जिनके बीच एक फ़ासला है। दो workers एक साथ यह करें तो दोनों एक ही ख़ाली ID पढ़ सकते हैं, और हारने वाले को error मिलता है, या उससे बुरा, कोई अचंभा।

serial: 1 create वाले चरण को एक बार में एक होस्ट तक सीमित कर देता है। यह तेज़ नहीं है, और इसे होने की ज़रूरत भी नहीं। VM बनाने का महँगा हिस्सा इस प्लेबुक के काम सौंप देने के बाद होता है। तैयार VMs को स्टार्ट करने वाला साथी play serial: 5 इस्तेमाल करता है, क्योंकि स्टार्ट करने में कोई साझा काउंटर नहीं जिस पर होड़ लगे।

अगर आपको parallelism चाहिए, तो VMID ख़ुद अपने source of truth से अलॉट कीजिए और उसे साफ़ तौर पर पास कीजिए। फिर न कोई read-modify-write होता है, न कोई race।

Idempotency वैसी नहीं है जैसी आप उम्मीद करते हैं

यह सेक्शन दो बार पढ़ने वाला है, क्योंकि proxmox_kvm का बर्ताव ansible.builtin.package जैसा नहीं है।

name कोई पहचान नहीं है। Proxmox क्लस्टर में VM के नाम unique नहीं होते, और मॉड्यूल ख़ुद यह कहता है। state: present के साथ और बिना vmid के, अगर उस नाम की VM पहले से है, तो मॉड्यूल changed=false और msg: "VM with name <x> already exists" के साथ बाहर निकल जाता है और कुछ नहीं करता। वह आपके पैरामीटर की असलियत से तुलना नहीं करता। converge नहीं करता। वह मना कर देता है।

update का डिफ़ॉल्ट false है। तो प्लेबुक में memory: बदलकर दोबारा चलाना कुछ नहीं करता। VM उसी मेमोरी के साथ रहती है जिससे वह बनी थी, टास्क सफलता बताता है, और कहीं भी कुछ नहीं बताता कि दोनों अलग हो चुके हैं।

update: true भी दिलचस्प पैरामीटर बदलने से मना करता है। मॉड्यूल documentation से:

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 यह रोक हटा देता है, और चेतावनी दिखावे के लिए नहीं है:

Use this option with caution because an improper configuration might result in a permanent loss of data (for example disk recreated).

यानी जिस डिस्क का आप साइज़ बढ़ा रहे थे, उसकी जगह एक नई ख़ाली डिस्क आ सकती है। इसकी तरफ़ हाथ मत बढ़ाइए। मना किए गए पैरामीटर के अपने मॉड्यूल हैं, और वही अगला सेक्शन है।

और --check इसमें से कुछ भी कवर नहीं करता। collection हर मॉड्यूल के लिए check mode सपोर्ट अलग से घोषित करता है, और यह ठीक ग़लत दिशा में असंगत है:

मॉड्यूलcheck_modediff_mode
proxmox_kvmnonenone
proxmox_disknonenone
proxmox_templatenonenone
proxmox_snapfullnone
proxmox_nicfullnone
proxmox_poolfullnone

बँटवारा “सिर्फ़ पढ़ने वाले मॉड्यूल कर सकते हैं, लिखने वाले नहीं” वाला नहीं है। proxmox_nic इंटरफ़ेस बनाता और हटाता है और check mode का पूरा पालन करता है। असल बात यह है कि जो तीन मॉड्यूल स्टोरेज और VM lifecycle से जुड़े हैं, वे नहीं करते। बिल्ड प्लेबुक का --check रन VM बनाने वाला टास्क चुपचाप छोड़ देता है और फिर एक ऐसी दुनिया की रिपोर्ट देता है जिसमें VM कभी बनी ही नहीं, तो उसके बाद का हर टास्क ग़लत स्थिति के बारे में सोच रहा होता है। बिल्ड प्लेबुक पर --check कोई सेफ़्टी नेट नहीं है, और उसे सेफ़्टी नेट मानना उसे न चलाने से भी बुरा है।

proxmox_kvm का दूसरा रन असल में क्या करता हैदूसरा रन: state: present, और उस नाम का VM मौजूद हैमॉड्यूल आपके पैरामीटर की तुलना चलते VM से कभी नहीं करताupdate: falseडिफ़ॉल्टchanged = false“VM with name <x>already exists”play में memory बदलिए,दोबारा चलाइए, और कहींकुछ नहीं बताताupdate: trueज़्यादातर converge करता हैcores, memory, tags,agent, onboot लागूnet, virtio, ide, sata,scsi, efidisk0, tpmstate0डिज़ाइन से मनाउनके लिए proxmox_diskऔर proxmox_nic लीजिएupdate_unsafe: trueसब converge करता हैमना किए गए पैरामीटरभी लागू होते हैंडिस्क पैरामीटर डिस्कदोबारा बना सकता हैस्थायी डेटा हानिdocumented जोखिम है--checkकुछ नहीं बताताcheck_mode: noneटास्क छोड़ दिया जाता हैफिर हर बाद का टास्कऐसी दुनिया मानकर चलता हैजहाँ VM कभीबना ही नहींचार में से दो ही कुछ converge करते हैं, और जो डिस्कढकता है वही उन्हें नष्ट कर सकता है।इसलिए मौजूदगी पर गेट खुद लगाइए, और creation कोएक बार की घटना मानिए।
दूसरा रन असल में क्या करता है। चार में से दो रास्ते ही कुछ भी converge करते हैं, और डिस्क को कवर करने वाला अकेला रास्ता वही है जो उन्हें नष्ट कर सकता है।

तो मौजूदगी को ही गेट बनाइए

इन सबको देखते हुए, जो तरीक़ा चलता है वह यह है कि मॉड्यूल से idempotent होने की उम्मीद छोड़ दीजिए और ख़ुद तय कीजिए कि बनाना है या नहीं। प्रोडक्शन प्लेबुक यह ऐसे करती है:

- 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
      ...

config: current के साथ proxmox_vm_info VM और उसका live कॉन्फ़िगरेशन लौटाता है, या एक ख़ाली सूची। failed_when “ख़ाली सूची” को failure बना देता है, ignore_errors: true उस failure को play ख़त्म करने से रोकता है, और when: existing_vm is failed का मतलब बन जाता है “VM नहीं है, बनाओ”।

जानबूझकर फ़ेल किए गए टास्क को boolean की तरह इस्तेमाल करना पढ़ने में बुरा लगता है, और मैं इसका दिखावा नहीं करूँगा कि ऐसा नहीं है। विकल्प है when: (existing_vm.proxmox_vms | default([]) | length) == 0, जो ईमानदारी से length check है और जिसे ignore_errors की ज़रूरत नहीं। दोनों चलते हैं। ऊपर वाला रूप प्रोडक्शन में है, और उसका एक असली फ़ायदा यह है कि registered नतीजे में मौजूदा कॉन्फ़िगरेशन रहता है जिसे बाद के टास्क पढ़ सकते हैं।

ज़रूरी चीज़ ढांचा है, वर्तनी नहीं: पहले जाँचो, फिर शाखा बनाओ, और creation को एक बार की घटना मानो। VM का चलता हुआ कॉन्फ़िगरेशन उसकी मौजूदगी से अलग समस्या है, और यह मॉड्यूल सिर्फ़ दूसरी वाली में अच्छा है।

डिस्क और NIC के अपने मॉड्यूल हैं

यह वह बात है जिसे मैंने ऊपर हल्के में छोड़ दिया था, और यह पूरी तस्वीर बदल देती है: proxmox_kvm जिन पैरामीटर को अपडेट करने से मना करता है, वे collection में कोई कमी नहीं हैं। उन्हें सौंपा गया है। community.proxmox.proxmox_disk और community.proxmox.proxmox_nic ठीक वही चीज़ें जोड़ते, बदलते और हटाते हैं जिन्हें create मॉड्यूल नहीं छूता, उन्हीं scsi0 और net0 नामों के आधार पर जो आपने VM बनाते समय इस्तेमाल किए थे।

दोनों proxmox_kvm से बेहतर बर्ताव करते हैं, और इनमें से एक इस workflow का अकेला मॉड्यूल है जिसे dry-run किया जा सकता है।

proxmox_nic: इंटरफ़ेस जोड़ना, दोबारा tag करना या हटाना

- 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

auth के अलावा interface अकेला ज़रूरी विकल्प है, net[n] जहाँ n 0 से 31 तक है, और state: present या absent आपको जोड़ना और हटाना देते हैं। model का डिफ़ॉल्ट virtio है, जो सही जवाब है जब तक कोई गेस्ट इसे सँभाल न पाए।

यह मॉड्यूल MAC address की वजह से है। याद कीजिए कि 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 दोबारा tag कर सकते हैं, bridge बदल सकते हैं, MTU बदल सकते हैं या firewall चालू कर सकते हैं, गेस्ट के NIC की पहचान उसके नीचे बदले बिना। यह जितना लगता है उससे ज़्यादा मायने रखता है: नया MAC DHCP reservation को बेकार कर देता है, NIC से बँधी किसी भी लाइसेंस वाली चीज़ को तोड़ देता है, और NetBox के उस interface record को बेमेल कर देता है जिसे create playbook ने इतनी सावधानी से लिखा था। यही वह मॉड्यूल है जो day-2 नेटवर्क बदलाव को उबाऊ बना देता है।

कुछ विकल्प जिन्हें ज़रूरत पड़ने से पहले जान लेना अच्छा है:

  • rate MBps में है, यानी MegaBytes per second, bits नहीं। डॉक्यूमेंटेशन इस बारे में साफ़ है और आठ गुना वाली गलती करना बहुत आसान है।
  • link_down: true इंटरफ़ेस को डिस्कनेक्ट कर देता है, जिसे डॉक्यूमेंट “like pulling the plug” बताते हैं। किसी संदिग्ध VM को रोके बिना या गेस्ट को छुए बिना अलग करने का साफ़ तरीका।
  • trunks उन VLAN ID की सूची लेता है जिन्हें पास करना है, उस गेस्ट के लिए जो अपनी tagging खुद करता है।
  • mtu: 1 टाइपो नहीं है और 1-byte MTU भी नहीं; इसका मतलब है “bridge का MTU अपनाओ”, और यह सिर्फ़ virtio पर लागू होता है।
  • queues multiqueue सेट करता है, 0 से 16। असली ट्रैफ़िक धकेलने वाली किसी भी चीज़ पर इसे vCPU संख्या से मिलाना फ़ायदेमंद है।

और यह check mode को पूरी तरह समर्थन देता है। proxmox_nic टास्क पर --check आपको सच बताता है, जो इसे इस workflow का अकेला हिस्सा बनाता है जिसका आप सुरक्षित रूप से रिहर्सल कर सकते हैं। इसके मैसेज भी ठीक से idempotent हैं। बिना बदले इंटरफ़ेस पर यह बदलाव का दावा करने की बजाय Nic net0 unchanged on VM with vmid 103 बताता है।

proxmox_disk: डिस्क का पूरा जीवनचक्र

proxmox_disk तीनों में सबसे बड़ा मॉड्यूल है, और इसका state पाँच अलग काम कर रहा है:

stateक्या होता हैपलटा जा सकता है?
presentडिस्क बनाओ, या मौजूदा डिस्क के विकल्प अपडेट करोलागू नहीं
resizedबढ़ाओ; PVE छोटा नहीं कर सकता, और डॉक्यूमेंट कहते हैं कि वह हाथ से करेंनहीं
detachedunused[n] बन जाती है; volume और उसका डेटा बने रहते हैंहाँ
movedbacking storage बदलो, या डिस्क दूसरे VM को सौंप दोमूल रहती है जब तक delete_moved न हो
absentbacking storage से हटा दी जाती हैनहीं

detached और absent के बीच का फ़र्क वह सुरक्षा जाल है जो proxmox_kvm आपको कभी नहीं देता। Detach करना एक config बदलाव है; मिटाना डेटा नष्ट करता है। दो अलग शब्द, दो अलग नतीजे।

पहले से मौजूद 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 वह knob है जो proxmox_kvm में होना चाहिए था। यह तय करता है कि state: present को क्या करने की इजाज़त है:

  • regular (डिफ़ॉल्ट): डिस्क न हो तो बनाओ, वरना उसके विकल्प अपडेट करो।
  • disabled: सिर्फ़ विकल्प अपडेट करो, और कभी मत बनाओ। जब आप किसी ऐसी डिस्क पर cache या iothread बदल रहे हों जिसका पहले से होना ज़रूरी है, तब यही चुनिए। यह किसी key की गलत वर्तनी की वजह से नया volume खड़ा करके आपको चौंका नहीं सकता।
  • forced: हमेशा बनाओ। मौजूदा डिस्क detach होकर unused छोड़ दी जाती है, मिटाई नहीं जाती।

यह आखिरी बर्ताव ही ज़रूरी बारीकी है। create: forced विनाशकारी दिखने वाला विकल्प है, और फिर भी यह कुछ नष्ट नहीं करता: पुराना volume unusedN के रूप में बचा रहता है और आप उसे दोबारा जोड़ सकते हैं। इसकी तुलना proxmox_kvm और update_unsafe से कीजिए, जिसकी documented विफलता है डिस्क का दोबारा बन जाना। लगभग वही काम, नुकसान का दायरा बहुत बेहतर।

डिस्क बढ़ाना:

- 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 के साथ यह suffix लेता है: मौजूदा आकार में जोड़ने के लिए +100G, या absolute लक्ष्य के रूप में 500G। एक पैरामीटर, दो परिपाटियाँ, और गलत अंदाज़ा लगाने पर विफलता चुपचाप होती है।

डिस्क को दूसरे स्टोरेज पर ले जाना, जो एक volume के live-migration वाला मामला है:

- 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 है, इसलिए डिफ़ॉल्ट रूप से आप दो कॉपी के साथ खत्म करते हैं और मूल वहाँ unused पड़ी रहती है: सुरक्षित, और अगर आप कभी वापस न आएँ तो स्टोरेज पूल भरने का अच्छा तरीका।

यहाँ timeout का डिफ़ॉल्ट 600 है, जबकि proxmox_kvm में 30। एक जैसा दिखने वाला पैरामीटर, बीस गुना फ़र्क, क्योंकि ये ऑपरेशन डेटा कॉपी करते हैं। बड़ी इमेज या धीमे स्टोरेज के लिए इसे बढ़ाइए; डॉक्यूमेंट moved और import_from दोनों के लिए यही कहते हैं।

जो हमें उस विकल्प पर लाता है जो इस मॉड्यूल को V2V और cloud-image का रास्ता बनाता है:

    import_from: "vmdata:9000/base-debian13.qcow2"

import_from खाली डिस्क allocate करने की बजाय किसी मौजूदा volume से डिस्क बनाता है: <STORAGE>:<VMID>/<NAME>, या PVE 9.x और बाद में storage के import directory के साथ <STORAGE>:import/<NAME>। यह size के साथ नहीं चल सकता, और absolute filesystem path सिर्फ़ root इस्तेमाल कर सकता है।

बाकी पैरामीटर सूची ही वजह है कि डिस्क create call के अंदर की बजाय इस मॉड्यूल से जोड़ी जाएँ: cache, aio, iothread, discard, ssd, backup, detect_zeroes, और पूरा throttling परिवार: iops, iops_rd, iops_wr, उनके _max और _max_length रूप, और bps_*_max_length burst नियंत्रण। बनने के बाद इनमें से कुछ भी proxmox_kvm से नहीं पहुँचा जा सकता।

दो चेतावनियाँ, दोनों मॉड्यूल के अपने डॉक्यूमेंटेशन से:

  • कुछ विकल्प बदलाव के लिए रीबूट चाहिए। “Some updates on options (like cache) are not being applied instantly and require VM restart.” हरे टास्क का मतलब है कि config लिख दिया गया, यह नहीं कि चलता हुआ VM अलग बर्ताव कर रहा है।
  • यह check mode को समर्थन नहीं देता। check_mode: none, proxmox_kvm की तरह। तो collection बीच से बँट जाता है: NIC बदलावों का --check से रिहर्सल हो सकता है, डिस्क बदलावों का नहीं।

काम का बँटवारा

यह करने के लिएइस्तेमाल करें
VM बनानाproxmox_kvm, एक बार, मौजूदगी के गेट के साथ
cores, memory, tags, agent, onboot बदलनाupdate: true के साथ proxmox_kvm
NIC जोड़ना, दोबारा tag करना, डिस्कनेक्ट करना या हटानाproxmox_nic
डिस्क जोड़ना, बढ़ाना, ले जाना, detach करना या हटानाproxmox_disk
Snapshotproxmox_snap (यह भी पूरा check mode)
जो इनमें से कोई नहीं देताSSH पर qm set
proxmox_kvm से डिस्क या NIC बदलनाकुछ नहीं; update_unsafe इसी के लिए है, और यही वजह है कि आपको इसे इस्तेमाल नहीं करना चाहिए

VM को एक न्यूनतम proxmox_kvm call से बनाइए, फिर डिस्क और इंटरफ़ेस उनके अपने मॉड्यूल से जोड़िए। इसमें ज़्यादा टास्क हैं, और यही वह रूप है जिसमें day-2 बदलावों का ऐसा रास्ता है जिसमें कोई ऐसा विकल्प शामिल नहीं जिसका documented जोखिम डिस्क खोना है।

मॉड्यूल कहाँ रुकता है

proxmox_kvm की पैरामीटर सूची बहुत बड़ी है और फिर भी यह वह सब नहीं ढकती जो qm कर सकता है। इंतज़ार करने की बजाय, प्रोडक्शन playbook नोड पर 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

इसमें कुछ गलत नहीं है। यह किसी सार्थक अर्थ में idempotent नहीं है, qm set एक write है और हर बार changed बताएगा, लेकिन यह स्पष्ट है, पढ़ने में आसान है, और दिखावा नहीं करता। अगर बाद में मॉड्यूल को यह पैरामीटर मिल जाए, तो आप टास्क मिटा दीजिए।

कुछ और चीज़ों के लिए update: true के साथ मॉड्यूल से दूसरा पास चाहिए, क्योंकि उन्हें उसी call में सेट नहीं किया जा सकता जो 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 मिल जाने के बाद उसी को इस्तेमाल कीजिए। यह अकेला identifier है जिसे API अद्वितीय मानता है।

और उन चीज़ों के लिए जो QEMU कर सकता है पर जिनके लिए PVE में कोई विकल्प नहीं, args है, जो QEMU command line को ज्यों का त्यों दिया जाता है:

    args: >-
      -global scsi-hd.physical_block_size=4k
      -global scsi-hd.logical_block_size=4096

यह वाला वर्चुअल डिस्क को 512e की बजाय 4Kn के रूप में पेश करता है, जो जितना लगता है उससे ज़्यादा मायने रखता है: block sizes, 4Kn और 512e। मॉड्यूल args पर “for experts only” का लेबल लगाता है, और वजह यह है कि PVE इसे validate नहीं करता और एक गलत flag VM को ऐसी error के साथ बूट होने से रोक देता है जो Proxmox से नहीं, QEMU से आती है।

क्लस्टर तुरंत एक जैसा नहीं होता

- name: Let registration complete on cluster
  ansible.builtin.pause:
    seconds: 5
  when: created_vm.changed

playbook में pause आमतौर पर गड़बड़ी का संकेत है, और यह वाला बोझ उठा रहा है। create call तब लौटती है जब API ने परिभाषा स्वीकार कर ली, जो इसके बराबर नहीं कि हर नोड मान ले कि VM मौजूद है, और अगला ही टास्क /vms/<vmid> पर ACL सेट करना चाहता है। पाँच सेकंड का धीरज उस error के चारों ओर retry loop से सस्ता है जो सिर्फ़ लोड में दिखती है।

teardown playbook का भी यही आकार है, इसी वजह से: रोको, रुको, फिर मिटाओ।

आपने जो बनाया उसे वापस पढ़ना

proxmox_kvm तीन return value document करता है: 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() में बनाता है और नतीजे में डाल देता है, लेकिन यह documented RETURN block में नहीं है, जिसका मतलब है कि कोई वादा नहीं करता कि यह काम करता रहेगा। यह ठीक-ठीक कैसे बर्ताव करता है यह जानने लायक है, क्योंकि इसमें दो जाल हैं:

  1. यह सिर्फ़ तब दिखता है जब मॉड्यूल ने सच में VM बनाया हो। mac सिर्फ़ create-and-deploy रास्ते पर जोड़ा जाता है। “already exists” वाली शाखा लीजिए और नतीजे में vmid और msg हैं, और कुछ नहीं।
  2. इसमें सिर्फ़ वे इंटरफ़ेस होते हैं जो आपने दिए। कोड आपके दिए पैरामीटर पर चलता है और net[0-9] से मेल खाने वाले चुनता है, फिर हर एक का stored config API से वापस पढ़ता है। कोई net पैरामीटर नहीं, तो कोई mac key नहीं।

इसीलिए प्रोडक्शन playbook को दोनों हिस्से चाहिए, और दूसरा भद्दा है:

- 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 को raw config string से खोदकर निकालना पड़ता है। net0 API से virtio=AE:AE:5C:A8:89:85,bridge=vmbr0 के रूप में आता है, तो: comma पर तोड़ो, पहला field लो, = पर तोड़ो, दूसरा हिस्सा लो। यह API response पर string की सर्जरी है, और यह उस मॉड्यूल की ईमानदार कीमत है जिसका return आकार इस पर निर्भर है कि उसने कौन सी शाखा ली।

अगर आपको दोनों हालात में MAC भरोसे से चाहिए, तो उसे हर बार proxmox_vm_info से लीजिए और दो की बजाय एक आकार parse कीजिए।

इसे source of truth से चलाना

play शुरू करने वाली लाइन को फिर से देखिए:

hosts: "{{ target_hosts | default('cluster_pve:&status_planned') }}"

यही असली architecture है, और इसे सीधे कहना ठीक है: बनाए जाने वाले VM किसी vars फ़ाइल की सूची नहीं हैं। वे आपकी inventory के वे होस्ट हैं जिनका दर्ज status कहता है कि उन्हें होना चाहिए और वे अभी नहीं हैं।

यहाँ inventory NetBox है। VM की माँग NetBox में planned status वाला record बनाकर की जाती है, जिसमें उसका CPU, memory, disk, VLAN, owner और platform होता है। Playbook planned मशीनें चुनती है, उन्हें बनाती है, IP allocate करती है, DNS लिखती है, और फिर record को staged पर सेट करती है; उस पल वह होस्ट play के host pattern से मेल नहीं खाता, और एक handler inventory को refresh करता है ताकि अगली play नई स्थिति देखे:

handlers:
  - name: Refresh inventory
    ansible.builtin.meta: refresh_inventory

status field एक state machine है, playbook उसमें एक transition है, और पूरी चीज़ दोबारा चलाई जा सकती है क्योंकि जो होस्ट आगे बढ़ चुका है वह अब चुना नहीं जाता। यह मॉड्यूल-स्तर की किसी भी idempotency से कहीं बेहतर गुण है, और यही वजह है कि create टास्क एक बार चलने वाला होकर भी बच निकलता है।

community.proxmox अपना inventory plugin भी देता है, जो क्लस्टर से inventory बनाता है; यह तब सही विकल्प है जब Proxmox ही source of truth हो। यहाँ उल्टा है: NetBox प्रामाणिक है और Proxmox वह जगह है जहाँ उसका इरादा साकार होता है। यह अपने आप में पूरी पोस्ट है और मैं इसे अलग से लिखूँगा।

इसे फिर से हटाना

teardown के बिना creation आधा जीवनचक्र है, और हटाने के रास्ते का अपना जाल है: आप चलते हुए 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 एक साफ़-सुथरा shutdown है, और timeout के साथ इसका रिश्ता documented है और याद रखने लायक है: अगर force: true के साथ timeout पूरा हो जाए तो VM ज़बरदस्ती बंद कर दिया जाता है; force: false के साथ टास्क फ़ेल हो जाता है। दस सेकंड की साफ़ खिड़की और फिर प्लग खींचना उस मशीन के लिए ठीक नीति है जिसे हटाया जा रहा है, और किसी और के लिए बहुत बुरी।

पूरा teardown (proxmox-remove-vms.yml) फिर record का बाकी हिस्सा खोलता है: DNS, allocate किया गया IP, NetBox interfaces, NetBox VM, और known_hosts की पुरानी entries। यह block को ignore_errors: true में लपेटता है, जो teardown में बचाव के लायक है। आप ऐसी चीज़ें हटा रहे हैं जो शायद पहले ही जा चुकी हों, और आधी मिटाई गई मशीन शोर वाले log से बदतर है।

नए सिरे से बनाने में मैं क्या बदलूँगा

सिर्फ़ डॉक्यूमेंटेशन नहीं, मॉड्यूल का source पढ़ने के बाद, ये पाँच बातें:

  • API token इस्तेमाल कीजिए, api_user और api_password नहीं। सीमित, वापस लिया जा सकने वाला, और कभी किसी व्यक्ति का नहीं।
  • validate_certs साफ़ तौर पर सेट कीजिए, इससे पहले कि 2.0.0 इसे आपके नीचे बदल दे।
  • VMID खुद allocate कीजिए, source of truth से। यह read-modify-write race हटा देता है, आपको serial: 1 छोड़ने देता है, और बाद के हर टास्क को एक स्थिर identifier देता है, ऐसे नाम की बजाय जो अद्वितीय नहीं है।
  • VM को खाली बनाइए, फिर उसकी डिस्क और NIC proxmox_disk और proxmox_nic से जोड़िए। ज़्यादा टास्क, लेकिन फिर हर डिस्क और इंटरफ़ेस के पास एक मॉड्यूल है जो उसे बाद में बदल सकता है, सिर्फ़-विकल्प बदलावों के लिए create: disabled और मिटाने की बजाय state: detached समेत, न कि ऐसा config जिसे सिर्फ़ update_unsafe से बदला जा सके।
  • MAC proxmox_vm_info से लीजिए, एक जगह, ताकि एक documented और एक undocumented return value के बीच शर्त की बजाय parse करने को एक ही आकार हो।

और build playbook पर --check की ओर हाथ मत बढ़ाइए। जो मॉड्यूल मायने रखता है वह इसे निभा नहीं सकता।

जो dry run हमेशा हाँ कहे वह dry run न होने से भी बुरा है, क्योंकि आप उस पर भरोसा कर लेंगे।

संदर्भ

  • community.proxmox collection docs: पूरे 47 मॉड्यूल
  • community.proxmox on GitHub: जहाँ ऊपर का source रहता है; जब डॉक्यूमेंट अस्पष्ट हों तो पढ़ने वाली फ़ाइल plugins/modules/proxmox_kvm.py है
  • proxmox_kvm module documentation: पैरामीटर सूची, और ऊपर उद्धृत update / update_unsafe चेतावनियाँ
  • proxmox_vm_info module documentation: config: current और config: pending
  • PVE qm options reference: हर scsi[n], net[n] और boot string का असली विवरण जो आप आगे देते हैं
  • proxmoxer: वह Python client जिस पर collection बना है
  • damo2929/ansible-example: वे playbooks जिनसे ये अंश लिए गए हैं, NetBox-संचालित inventory, DHCP generation और hypervisor build समेत