156 lines
3.6 KiB
Markdown
156 lines
3.6 KiB
Markdown
# 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) |
|