refactor ♻️: Integrate centralized helper functions for improved code consistency and idempotency across VM management tasks

tasks/configure-vm.yml

@@ -113,6 +113,12 @@
 
 - name: "[CONFIG] Create and apply Cloud-Init snippets"
   block:
+    - name: "[CONFIG] Clean up old Cloud-Init snippets (if any)"
+      ansible.builtin.include_tasks: helpers.yml
+      vars:
+        helper_task: cleanup_snippets
+        target_vm_id: "{{ vm_id }}"
+
     - name: "[CONFIG] Create Cloud-Init vendor-data snippet"
       ansible.builtin.template:
         src: cloudinit_vendor.yaml.j2
@@ -153,9 +159,9 @@
       changed_when: cloudinit_apply.rc == 0
 
     - name: "[CONFIG] Display Cloud-Init configuration"
-      debug:
-        ansible.builtin.msg: |
-          ✓ Cloud-Init configured
+      ansible.builtin.debug:
+        msg: |
+          ✓ Cloud-Init configured for VM {{ vm_id }}
           - User: {{ ci_user }}
           - Hostname: {{ hostname }}
           - IP Config: {{ ipconfig0 }}

tasks/create-clones.yml

@@ -11,14 +11,14 @@
 - name: "[CLONES] Process each clone"
   block:
     - name: "[CLONES] Check if clone already exists"
-      ansible.builtin.stat:
-        path: "/etc/pve/qemu-server/{{ clone.id }}.conf"
-      register: clone_conf
-      changed_when: false
+      ansible.builtin.include_tasks: helpers.yml
+      vars:
+        helper_task: check_vm_exists
+        target_vm_id: "{{ clone.id }}"
 
     - name: "[CLONES] Display clone status"
       ansible.builtin.debug:
-        msg: "Clone {{ clone.id }} ({{ clone.hostname }}) - Status: {{ 'EXISTS' if clone_conf.stat.exists else 'WILL BE CREATED' }}"
+        msg: "Clone {{ clone.id }} ({{ clone.hostname }}) - Status: {{ 'EXISTS' if vm_exists else 'WILL BE CREATED' }}"
 
     - name: "[CLONES] Clone VM from template"
       block:
@@ -28,19 +28,26 @@
             --name {{ clone.hostname }}
             --full {{ clone.full | default(0) }}
           register: clone_cmd
-          when: not clone_conf.stat.exists
+          when: not vm_exists
 
         - name: "[CLONES] Verify clone was created"
-          ansible.builtin.stat:
-            path: "/etc/pve/qemu-server/{{ clone.id }}.conf"
-          register: clone_verify
-          changed_when: false
-          failed_when: not clone_verify.stat.exists
+          ansible.builtin.include_tasks: helpers.yml
+          vars:
+            helper_task: check_vm_exists
+            target_vm_id: "{{ clone.id }}"
+          when: not vm_exists
+
+        - name: "[CLONES] Ensure clone creation succeeded"
+          ansible.builtin.assert:
+            that:
+              - vm_exists | bool
+            fail_msg: "Failed to create clone {{ clone.id }}"
+          when: not vm_exists
 
         - name: "[CLONES] Wait for clone to be ready"
           ansible.builtin.pause:
             seconds: 2
-          when: not clone_conf.stat.exists
+          when: not vm_exists
 
       rescue:
         - name: "[CLONES] Handle clone creation error"
@@ -57,13 +64,13 @@
             --hostname {{ clone.hostname }}
             --ipconfig0 "ip={{ clone.ip }},gw={{ clone.gateway }}"
           register: clone_config
-          when: not clone_conf.stat.exists
+          when: not vm_exists
 
         - name: "[CLONES] Apply SSH keys to clone"
           ansible.builtin.command: >
             qm set {{ clone.id }}
             --sshkeys local:snippets/{{ vm_id }}-sshkey.pub
-          when: not clone_conf.stat.exists
+          when: not vm_exists
 
       rescue:
         - name: "[CLONES] Handle clone configuration error"
@@ -76,7 +83,7 @@
       retries: "{{ max_retries }}"
       delay: "{{ retry_delay }}"
       until: clone_start is succeeded
-      when: not clone_conf.stat.exists
+      when: not vm_exists
 
     - name: "[CLONES] Wait for clone to boot"
       ansible.builtin.pause:
@@ -85,11 +92,15 @@
     - name: "[CLONES] Display clone creation result"
       ansible.builtin.debug:
         msg: |
+          {% if vm_exists %}
+          ℹ Clone {{ clone.id }} ({{ clone.hostname }}) already exists - skipped
+          {% else %}
           ✓ Clone created and started
           - ID: {{ clone.id }}
           - Hostname: {{ clone.hostname }}
           - IP: {{ clone.ip }}
           - Full clone: {{ clone.full | default(0) }}
+          {% endif %}
 
   loop: "{{ clones }}"
   loop_control:

tasks/create-template.yml

@@ -2,51 +2,58 @@
 # create-template.yml - Convert VM to template with proper idempotency
 
 - name: "[TEMPLATE] Check if VM is already a template"
-  ansible.builtin.shell: "qm config {{ vm_id }} | grep -q 'template: 1'"
-  register: is_template
-  changed_when: false
-  failed_when: false
+  ansible.builtin.include_tasks: helpers.yml
+  vars:
+    helper_task: check_template
+    target_vm_id: "{{ vm_id }}"
 
 - name: "[TEMPLATE] Display template status"
   ansible.builtin.debug:
-    msg: "Template status for VM {{ vm_id }}: {{ 'ALREADY A TEMPLATE' if is_template.rc == 0 else 'NOT YET A TEMPLATE' }}"
+    msg: "Template status for VM {{ vm_id }}: {{ 'ALREADY A TEMPLATE' if is_template else 'NOT YET A TEMPLATE' }}"
 
 - name: "[TEMPLATE] Verify VM is stopped before converting"
   block:
     - name: "[TEMPLATE] Check VM status"
-      ansible.builtin.shell: "qm status {{ vm_id }} | grep -q 'stopped'"
-      register: vm_stopped
-      changed_when: false
-      failed_when: false
+      ansible.builtin.include_tasks: helpers.yml
+      vars:
+        helper_task: check_vm_status
+        target_vm_id: "{{ vm_id }}"
 
     - name: "[TEMPLATE] Stop VM if running"
       ansible.builtin.command: "qm stop {{ vm_id }}"
-      when: vm_stopped.rc != 0
       register: vm_stop
+      when: vm_status != 'stopped'
+      changed_when: vm_stop.rc == 0
 
     - name: "[TEMPLATE] Wait for VM to stop"
       ansible.builtin.pause:
         seconds: 2
-      when: vm_stopped.rc != 0
+      when: vm_status != 'stopped'
 
   rescue:
     - name: "[TEMPLATE] Handle VM stop error"
       ansible.builtin.debug:
         msg: "WARNING: Could not verify/stop VM {{ vm_id }}. Continuing..."
 
-- name: "[TEMPLATE] Convert VM to template"
+- name: "[TEMPLATE] Convert VM to template (idempotent - skipped if already template)"
   block:
     - name: "[TEMPLATE] Convert to template"
       ansible.builtin.command: "qm template {{ vm_id }}"
       register: template_convert
-      when: is_template.rc != 0
+      when: not is_template
       changed_when: template_convert.rc == 0
 
     - name: "[TEMPLATE] Verify conversion"
-      ansible.builtin.shell: "qm config {{ vm_id }} | grep 'template: 1'"
-      register: template_verify
-      changed_when: false
-      failed_when: template_verify.rc != 0
+      ansible.builtin.include_tasks: helpers.yml
+      vars:
+        helper_task: check_template
+        target_vm_id: "{{ vm_id }}"
+
+    - name: "[TEMPLATE] Ensure template conversion succeeded"
+      ansible.builtin.assert:
+        that:
+          - is_template | bool
+        fail_msg: "Failed to convert VM {{ vm_id }} to template"
 
     - name: "[TEMPLATE] Display template conversion result"
       ansible.builtin.debug:
@@ -64,4 +71,4 @@
 - name: "[TEMPLATE] Skip template conversion (already done)"
   ansible.builtin.debug:
     msg: "ℹ VM {{ vm_id }} is already a template, skipping conversion"
-  when: is_template.rc == 0
+  when: is_template

tasks/create-vm.yml

@@ -2,45 +2,49 @@
 # create-vm.yml - Create base VM on Proxmox
 
 - name: "[VM] Check if VM already exists"
-  ansible.builtin.stat:
-    path: "/etc/pve/qemu-server/{{ vm_id }}.conf"
-  register: vm_conf
-  changed_when: false
+  ansible.builtin.include_tasks: helpers.yml
+  vars:
+    helper_task: check_vm_exists
+    target_vm_id: "{{ vm_id }}"
 
 - name: "[VM] Display VM status"
   ansible.builtin.debug:
-    msg: "VM {{ vm_id }} ({{ hostname }}) - Status: {{ 'ALREADY EXISTS' if vm_conf.stat.exists else 'WILL BE CREATED' }}"
+    msg: "VM {{ vm_id }} ({{ hostname }}) - Status: {{ 'ALREADY EXISTS' if vm_exists else 'WILL BE CREATED' }}"
 
-- name: "[VM] Create base VM"
-  ansible.builtin.command: >
-    qm create {{ vm_id }}
-    --name {{ hostname }}
-    --memory {{ memory }}
-    --cores {{ cores }}
-    --cpu {{ cpu_type }}
-    --net0 virtio,bridge={{ bridge }},macaddr={{ mac_address }}
-    --agent 1
-  register: vm_create
-  when: not vm_conf.stat.exists
-  changed_when: vm_create.rc == 0
+- name: "[VM] Create base VM (idempotent - skipped if already exists)"
+  block:
+    - name: "[VM] Create base VM"
+      ansible.builtin.command: >
+        qm create {{ vm_id }}
+        --name {{ hostname }}
+        --memory {{ memory }}
+        --cores {{ cores }}
+        --cpu {{ cpu_type }}
+        --net0 virtio,bridge={{ bridge }},macaddr={{ mac_address }}
+        --agent 1
+      register: vm_create
+      changed_when: vm_create.rc == 0
 
-- name: "[VM] Handle VM creation error"
-  ansible.builtin.fail:
-    msg: |
-      Failed to create VM {{ vm_id }}:
-      {{ vm_create.stderr | default('No error message') }}
-  when:
-    - not vm_conf.stat.exists
-    - vm_create is failed
+    - name: "[VM] Verify VM was created"
+      ansible.builtin.include_tasks: helpers.yml
+      vars:
+        helper_task: check_vm_exists
+        target_vm_id: "{{ vm_id }}"
 
-- name: "[VM] Verify VM was created"
-  ansible.builtin.stat:
-    path: "/etc/pve/qemu-server/{{ vm_id }}.conf"
-  register: vm_conf_verify
-  changed_when: false
-  failed_when: not vm_conf_verify.stat.exists
+    - name: "[VM] Ensure VM creation succeeded"
+      ansible.builtin.assert:
+        that:
+          - vm_exists | bool
+        fail_msg: "Failed to create VM {{ vm_id }}"
 
-- name: "[VM] Display VM creation result"
-  ansible.builtin.debug:
-    msg: "✓ VM {{ vm_id }} created successfully"
-  when: not vm_conf.stat.exists
+    - name: "[VM] Display VM creation result"
+      ansible.builtin.debug:
+        msg: "✓ VM {{ vm_id }} created successfully"
+
+  when: not vm_exists
+  rescue:
+    - name: "[VM] Handle VM creation error"
+      ansible.builtin.fail:
+        msg: |
+          Failed to create VM {{ vm_id }}:
+          {{ ansible_failed_result | default('Unknown error') }}