Initial commit

skills/ansible/references/proxmox/authentication.md

@@ -0,0 +1,155 @@
+# Ansible Proxmox Authentication
+
+## API Token Setup
+
+Create a dedicated Ansible user and API token on Proxmox:
+
+```bash
+# On Proxmox node
+pveum user add ansible@pve
+pveum aclmod / -user ansible@pve -role PVEAdmin
+pveum user token add ansible@pve mytoken --privsep 0
+```
+
+**Note:** `--privsep 0` gives the token the same permissions as the user.
+
+## Playbook Variables
+
+### Direct in playbook (NOT recommended)
+
+```yaml
+vars:
+  proxmox_api_host: proxmox.example.com
+  proxmox_api_user: ansible@pve
+  proxmox_api_token_id: mytoken
+  proxmox_api_token_secret: "{{ vault_proxmox_token }}"
+```
+
+### Group vars with vault
+
+```yaml
+# group_vars/all.yml
+proxmox_api_host: proxmox.example.com
+proxmox_api_user: ansible@pve
+proxmox_api_token_id: mytoken
+
+# group_vars/secrets.yml (ansible-vault encrypted)
+proxmox_api_token_secret: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
+```
+
+### Environment variables
+
+```bash
+export PROXMOX_HOST=proxmox.example.com
+export PROXMOX_USER=ansible@pve
+export PROXMOX_TOKEN_ID=mytoken
+export PROXMOX_TOKEN_SECRET=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
+```
+
+```yaml
+# In playbook
+vars:
+  proxmox_api_host: "{{ lookup('env', 'PROXMOX_HOST') }}"
+  proxmox_api_user: "{{ lookup('env', 'PROXMOX_USER') }}"
+  proxmox_api_token_id: "{{ lookup('env', 'PROXMOX_TOKEN_ID') }}"
+  proxmox_api_token_secret: "{{ lookup('env', 'PROXMOX_TOKEN_SECRET') }}"
+```
+
+## Reusable Auth Block
+
+Define once, reuse across tasks:
+
+```yaml
+vars:
+  proxmox_auth: &proxmox_auth
+    api_host: "{{ proxmox_api_host }}"
+    api_user: "{{ proxmox_api_user }}"
+    api_token_id: "{{ proxmox_api_token_id }}"
+    api_token_secret: "{{ proxmox_api_token_secret }}"
+    validate_certs: false  # For self-signed certs
+
+tasks:
+  - name: Create VM
+    community.general.proxmox_kvm:
+      <<: *proxmox_auth
+      node: joseph
+      vmid: 300
+      name: myvm
+      state: present
+
+  - name: Start VM
+    community.general.proxmox_kvm:
+      <<: *proxmox_auth
+      vmid: 300
+      state: started
+```
+
+## TLS Certificate Handling
+
+### Self-signed certificates
+
+```yaml
+community.general.proxmox_kvm:
+  # ... auth params ...
+  validate_certs: false
+```
+
+### Custom CA
+
+```bash
+export SSL_CERT_FILE=/path/to/ca-bundle.crt
+```
+
+Or in ansible.cfg:
+
+```ini
+[defaults]
+# For urllib3/requests
+ca_cert = /path/to/ca-bundle.crt
+```
+
+## Minimum Required Permissions
+
+For full VM/container management:
+
+| Permission | Path | Purpose |
+|------------|------|---------|
+| VM.Allocate | / | Create VMs |
+| VM.Clone | / | Clone templates |
+| VM.Config.* | / | Modify VM config |
+| VM.PowerMgmt | / | Start/stop VMs |
+| VM.Snapshot | / | Create snapshots |
+| Datastore.AllocateSpace | / | Allocate disk space |
+| Datastore.Audit | / | List storage |
+
+Or use the built-in `PVEAdmin` role for full access.
+
+## Troubleshooting Auth Issues
+
+```yaml
+# Debug task to test connection
+- name: Test Proxmox API connection
+  community.general.proxmox_kvm:
+    api_host: "{{ proxmox_api_host }}"
+    api_user: "{{ proxmox_api_user }}"
+    api_token_id: "{{ proxmox_api_token_id }}"
+    api_token_secret: "{{ proxmox_api_token_secret }}"
+    validate_certs: false
+    vmid: 100
+    state: current
+  register: result
+  ignore_errors: true
+
+- name: Show result
+  ansible.builtin.debug:
+    var: result
+```
+
+Common errors:
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| 401 Unauthorized | Bad token | Verify token ID format: `user@realm!tokenname` |
+| 403 Forbidden | Insufficient permissions | Check user ACLs with `pveum user permissions ansible@pve` |
+| SSL certificate problem | Self-signed cert | Set `validate_certs: false` |
+| Connection refused | Wrong host/port | Verify API URL (port 8006) |