From 44aa6ac36936685e0f76a7071da3c36c52140055 Mon Sep 17 00:00:00 2001
From: Sandwich <sandwich@archworks.co>
Date: Wed, 11 Mar 2026 04:05:36 +0100
Subject: [PATCH] feat(vmware): add hypervisor.node as unified placement field
 (replaces host)

---
 roles/global_defaults/defaults/main.yml    |  6 +++---
 roles/global_defaults/tasks/main.yml       |  2 +-
 roles/global_defaults/tasks/validation.yml | 17 +++++++++++++++++
 roles/system_check/tasks/main.yml          |  2 +-
 roles/virtualization/tasks/vmware.yml      |  3 ++-
 5 files changed, 24 insertions(+), 6 deletions(-)

diff --git a/roles/global_defaults/defaults/main.yml b/roles/global_defaults/defaults/main.yml
index 2cb2cf8..317001d 100644
--- a/roles/global_defaults/defaults/main.yml
+++ b/roles/global_defaults/defaults/main.yml
@@ -46,7 +46,7 @@ hypervisor_defaults:
   url: ""
   username: ""
   password: ""
-  host: ""
+  node: ""
   storage: ""
   datacenter: ""
   cluster: ""
@@ -136,10 +136,10 @@ system_defaults:
 # All virtual types additionally require network bridge or interfaces.
 hypervisor_required_fields:
   proxmox:
-    hypervisor: [url, username, password, host, storage]
+    hypervisor: [url, username, password, node, storage]
     system: [id]
   vmware:
-    hypervisor: [url, username, password, datacenter, cluster, storage]
+    hypervisor: [url, username, password, datacenter, storage]
     system: []
   xen:
     hypervisor: []
diff --git a/roles/global_defaults/tasks/main.yml b/roles/global_defaults/tasks/main.yml
index 1bcf33f..b296b9e 100644
--- a/roles/global_defaults/tasks/main.yml
+++ b/roles/global_defaults/tasks/main.yml
@@ -32,7 +32,7 @@
       api_host: "{{ hypervisor_cfg.url }}"
       api_user: "{{ hypervisor_cfg.username }}"
       api_password: "{{ hypervisor_cfg.password }}"
-      node: "{{ hypervisor_cfg.host }}"
+      node: "{{ hypervisor_cfg.node }}"
   no_log: true
 
 - name: Normalize system inputs
diff --git a/roles/global_defaults/tasks/validation.yml b/roles/global_defaults/tasks/validation.yml
index 5994378..def7feb 100644
--- a/roles/global_defaults/tasks/validation.yml
+++ b/roles/global_defaults/tasks/validation.yml
@@ -166,6 +166,23 @@
     label: "hypervisor.{{ item }}"
   no_log: true
 
+- name: Validate VMware placement (cluster or node required, mutually exclusive)
+  when:
+    - system_cfg.type == "virtual"
+    - hypervisor_type == "vmware"
+  ansible.builtin.assert:
+    that:
+      - >-
+        (hypervisor_cfg.cluster | default('') | string | length > 0)
+        or (hypervisor_cfg.node | default('') | string | length > 0)
+      - >-
+        (hypervisor_cfg.cluster | default('') | string | length == 0)
+        or (hypervisor_cfg.node | default('') | string | length == 0)
+    fail_msg: >-
+      VMware requires either hypervisor.cluster or hypervisor.node (mutually exclusive).
+      cluster targets a vSphere cluster; node targets a specific ESXi host.
+    quiet: true
+
 - name: Validate hypervisor-specific required system fields
   when:
     - system_cfg.type == "virtual"
diff --git a/roles/system_check/tasks/main.yml b/roles/system_check/tasks/main.yml
index 5b205e5..489ff77 100644
--- a/roles/system_check/tasks/main.yml
+++ b/roles/system_check/tasks/main.yml
@@ -45,7 +45,7 @@
       block:
         - name: Query Proxmox for existing VM
           community.proxmox.proxmox_vm_info:
-            node: "{{ hypervisor_cfg.host }}"
+            node: "{{ hypervisor_cfg.node }}"
             vmid: "{{ system_cfg.id }}"
             name: "{{ hostname }}"
             type: qemu
diff --git a/roles/virtualization/tasks/vmware.yml b/roles/virtualization/tasks/vmware.yml
index 0bc89af..88d6d8f 100644
--- a/roles/virtualization/tasks/vmware.yml
+++ b/roles/virtualization/tasks/vmware.yml
@@ -32,7 +32,8 @@
           {%- endfor -%}
           {{ ns.out }}
       community.vmware.vmware_guest:
-        cluster: "{{ hypervisor_cfg.cluster }}"
+        cluster: "{{ hypervisor_cfg.cluster if (hypervisor_cfg.node | default('') | length == 0) else omit }}"
+        esxi_hostname: "{{ hypervisor_cfg.node if (hypervisor_cfg.node | default('') | length > 0) else omit }}"
         folder: "{{ system_cfg.path if system_cfg.path | string | length > 0 else omit }}"
         name: "{{ hostname }}"
         # Generic guest ID — VMware auto-detects OS post-install