Add Proxmox auth fallback updates and session snapshot (2026-04-21)

ansible/requirements.yml

@@ -12,7 +12,7 @@ collections:
   # Used for: proxmox lifecycle, kvm, and nic management modules
   # Docs: https://docs.ansible.com/ansible/latest/collections/community/proxmox/
   - name: community.proxmox
-    version: ">=1.3.0"
+    version: ">=1.6.0"
 
   # Community General Collection
   # Used for: docker modules and general utilities

ansible/roles/proxmox_vm_deploy/defaults/main.yml

@@ -4,6 +4,7 @@ proxmox_api_host: "10.0.0.201"
 proxmox_api_user: "ansible@pve"
 proxmox_api_token_id: "ansible"
 proxmox_api_token_secret: "SET_IN_VAULT"
+proxmox_api_password: ""
 proxmox_validate_certs: false
 
 # VM placement

ansible/roles/proxmox_vm_deploy/tasks/main.yml

@@ -4,21 +4,27 @@
     that:
       - proxmox_api_host | length > 0
       - proxmox_api_user | length > 0
-      - proxmox_api_token_id | length > 0
+      - >-
-      - proxmox_api_token_secret | length > 0
+        (proxmox_api_password | default('') | length > 0)
+        or
+        (
+          proxmox_api_token_id | length > 0
+          and proxmox_api_token_secret | length > 0
+        )
       - proxmox_node | length > 0
       - proxmox_template | length > 0
       - proxmox_vmid | int > 99
       - vm_ci_user | length > 0
       - vm_ipconfig0 is match('^ip=.+')
-    fail_msg: "Missing required VM provisioning variables."
+    fail_msg: "Missing required VM provisioning variables or Proxmox credentials."
 
 - name: Gather current VMs on Proxmox node
   community.proxmox.proxmox_vm_info:
     api_host: "{{ proxmox_api_host }}"
     api_user: "{{ proxmox_api_user }}"
-    api_token_id: "{{ proxmox_api_token_id }}"
+    api_password: "{{ proxmox_api_password if (proxmox_api_password | default('') | length > 0) else omit }}"
-    api_token_secret: "{{ proxmox_api_token_secret }}"
+    api_token_id: "{{ proxmox_api_token_id if (proxmox_api_password | default('') | length == 0) else omit }}"
+    api_token_secret: "{{ proxmox_api_token_secret if (proxmox_api_password | default('') | length == 0) else omit }}"
     validate_certs: "{{ proxmox_validate_certs }}"
     node: "{{ proxmox_node }}"
   register: proxmox_vms
@@ -37,8 +43,9 @@
   community.proxmox.proxmox_kvm:
     api_host: "{{ proxmox_api_host }}"
     api_user: "{{ proxmox_api_user }}"
-    api_token_id: "{{ proxmox_api_token_id }}"
+    api_password: "{{ proxmox_api_password if (proxmox_api_password | default('') | length > 0) else omit }}"
-    api_token_secret: "{{ proxmox_api_token_secret }}"
+    api_token_id: "{{ proxmox_api_token_id if (proxmox_api_password | default('') | length == 0) else omit }}"
+    api_token_secret: "{{ proxmox_api_token_secret if (proxmox_api_password | default('') | length == 0) else omit }}"
     validate_certs: "{{ proxmox_validate_certs }}"
     node: "{{ proxmox_node }}"
     clone: "{{ proxmox_template }}"
@@ -54,8 +61,9 @@
   community.proxmox.proxmox_kvm:
     api_host: "{{ proxmox_api_host }}"
     api_user: "{{ proxmox_api_user }}"
-    api_token_id: "{{ proxmox_api_token_id }}"
+    api_password: "{{ proxmox_api_password if (proxmox_api_password | default('') | length > 0) else omit }}"
-    api_token_secret: "{{ proxmox_api_token_secret }}"
+    api_token_id: "{{ proxmox_api_token_id if (proxmox_api_password | default('') | length == 0) else omit }}"
+    api_token_secret: "{{ proxmox_api_token_secret if (proxmox_api_password | default('') | length == 0) else omit }}"
     validate_certs: "{{ proxmox_validate_certs }}"
     node: "{{ proxmox_node }}"
     vmid: "{{ proxmox_vmid }}"
@@ -85,8 +93,9 @@
   community.proxmox.proxmox_kvm:
     api_host: "{{ proxmox_api_host }}"
     api_user: "{{ proxmox_api_user }}"
-    api_token_id: "{{ proxmox_api_token_id }}"
+    api_password: "{{ proxmox_api_password if (proxmox_api_password | default('') | length > 0) else omit }}"
-    api_token_secret: "{{ proxmox_api_token_secret }}"
+    api_token_id: "{{ proxmox_api_token_id if (proxmox_api_password | default('') | length == 0) else omit }}"
+    api_token_secret: "{{ proxmox_api_token_secret if (proxmox_api_password | default('') | length == 0) else omit }}"
     validate_certs: "{{ proxmox_validate_certs }}"
     node: "{{ proxmox_node }}"
     vmid: "{{ proxmox_vmid }}"

documentation/project-history/SESSION_SNAPSHOT_2026-04-21.md

@@ -0,0 +1,44 @@
+# Session Snapshot - 2026-04-21
+
+## Summary
+- Built a role-based deployment path for Proxmox VM provisioning and AI Tutor installation.
+- Added troubleshooting-driven improvements for Proxmox API auth handling.
+- Last test still failed due `401 Unauthorized` from `community.proxmox` modules, despite successful direct authenticated `curl` API check.
+- Session closed for the night with deployment still blocked in Ansible module auth path.
+
+## Work Completed
+- Added/updated automation for:
+  - Proxmox VM deployment role logic
+  - Proxmox role defaults
+  - Collection version baseline
+- Added optional Proxmox password-auth fallback in role tasks/defaults to unblock deployment path.
+
+## Files Changed
+- ansible/requirements.yml
+- ansible/roles/proxmox_vm_deploy/defaults/main.yml
+- ansible/roles/proxmox_vm_deploy/tasks/main.yml
+
+## Validation and Test Results
+- `ansible-inventory -i inventory/hosts.ini --list --ask-vault-pass`:
+  - Passed after vault YAML fix.
+- Direct API auth check with token:
+  - `GET /api2/json/cluster/resources?type=vm` returned HTTP 200.
+- Playbook execution:
+  - `ansible-playbook -i inventory/hosts.ini playbooks/deploy-aitutor-vm.yml --ask-vault-pass`
+  - Failed at `proxmox_vm_deploy : Gather current VMs on Proxmox node` with `401 Unauthorized`.
+
+## New Technical Debt
+- None added in code comments (`@TODO` / `FIXME` not introduced this session).
+
+## Open Issues
+- Ansible `community.proxmox` module auth path still fails with 401 while equivalent direct API call succeeds.
+- Environment contains multiple installed versions of `community.proxmox`; module resolution should be verified/standardized on target runner.
+
+## Next Steps
+1. Force/verify collection resolution to `community.proxmox 1.6.0` on watchtower runtime.
+2. Re-test token auth via playbook.
+3. If still blocked, use `proxmox_api_password` fallback for immediate deployment completion.
+4. After unblock, revert to token-only auth and remove password fallback if desired.
+
+## Session Notes
+- User requested to pack up for the night and commit all current changes.