233 lines
5.0 KiB
Markdown
233 lines
5.0 KiB
Markdown
# Ansible Proxmox Modules
|
|
|
|
Proxmox VE management via `community.general` collection.
|
|
|
|
## Collection Setup
|
|
|
|
```bash
|
|
ansible-galaxy collection install community.general
|
|
```
|
|
|
|
## Core Modules
|
|
|
|
### proxmox (LXC Containers)
|
|
|
|
```yaml
|
|
- name: Create LXC container
|
|
community.general.proxmox:
|
|
api_host: proxmox.example.com
|
|
api_user: ansible@pve
|
|
api_token_id: mytoken
|
|
api_token_secret: "{{ proxmox_token_secret }}"
|
|
node: joseph
|
|
vmid: 200
|
|
hostname: mycontainer
|
|
ostemplate: local:vztmpl/ubuntu-22.04-standard_22.04-1_amd64.tar.zst
|
|
storage: local-lvm
|
|
cores: 2
|
|
memory: 2048
|
|
disk: 10
|
|
netif: '{"net0":"name=eth0,bridge=vmbr0,ip=dhcp"}'
|
|
state: present
|
|
|
|
- name: Start container
|
|
community.general.proxmox:
|
|
api_host: proxmox.example.com
|
|
api_user: ansible@pve
|
|
api_token_id: mytoken
|
|
api_token_secret: "{{ proxmox_token_secret }}"
|
|
node: joseph
|
|
vmid: 200
|
|
state: started
|
|
|
|
- name: Stop container
|
|
community.general.proxmox:
|
|
# ... auth params ...
|
|
vmid: 200
|
|
state: stopped
|
|
force: true # Force stop if graceful fails
|
|
|
|
- name: Remove container
|
|
community.general.proxmox:
|
|
# ... auth params ...
|
|
vmid: 200
|
|
state: absent
|
|
```
|
|
|
|
### proxmox_kvm (VMs)
|
|
|
|
```yaml
|
|
- name: Create VM from template
|
|
community.general.proxmox_kvm:
|
|
api_host: proxmox.example.com
|
|
api_user: ansible@pve
|
|
api_token_id: mytoken
|
|
api_token_secret: "{{ proxmox_token_secret }}"
|
|
node: joseph
|
|
vmid: 300
|
|
name: myvm
|
|
clone: tmpl-ubuntu-2404-standard
|
|
full: true # Full clone (not linked)
|
|
storage: local-lvm
|
|
format: raw
|
|
timeout: 500
|
|
|
|
- name: Start VM
|
|
community.general.proxmox_kvm:
|
|
# ... auth params ...
|
|
node: joseph
|
|
vmid: 300
|
|
state: started
|
|
|
|
- name: Stop VM (ACPI shutdown)
|
|
community.general.proxmox_kvm:
|
|
# ... auth params ...
|
|
vmid: 300
|
|
state: stopped
|
|
force: false # Graceful ACPI
|
|
|
|
- name: Force stop VM
|
|
community.general.proxmox_kvm:
|
|
# ... auth params ...
|
|
vmid: 300
|
|
state: stopped
|
|
force: true
|
|
|
|
- name: Current state (running/stopped/present/absent)
|
|
community.general.proxmox_kvm:
|
|
# ... auth params ...
|
|
vmid: 300
|
|
state: current
|
|
register: vm_state
|
|
```
|
|
|
|
### proxmox_template
|
|
|
|
```yaml
|
|
- name: Convert VM to template
|
|
community.general.proxmox_template:
|
|
api_host: proxmox.example.com
|
|
api_user: ansible@pve
|
|
api_token_id: mytoken
|
|
api_token_secret: "{{ proxmox_token_secret }}"
|
|
node: joseph
|
|
vmid: 100
|
|
state: present # Convert to template
|
|
|
|
- name: Delete template
|
|
community.general.proxmox_template:
|
|
# ... auth params ...
|
|
vmid: 100
|
|
state: absent
|
|
```
|
|
|
|
### proxmox_snap
|
|
|
|
```yaml
|
|
- name: Create snapshot
|
|
community.general.proxmox_snap:
|
|
api_host: proxmox.example.com
|
|
api_user: ansible@pve
|
|
api_token_id: mytoken
|
|
api_token_secret: "{{ proxmox_token_secret }}"
|
|
vmid: 300
|
|
snapname: before-upgrade
|
|
description: "Snapshot before major upgrade"
|
|
vmstate: false # Don't include RAM
|
|
state: present
|
|
|
|
- name: Rollback to snapshot
|
|
community.general.proxmox_snap:
|
|
# ... auth params ...
|
|
vmid: 300
|
|
snapname: before-upgrade
|
|
state: rollback
|
|
|
|
- name: Remove snapshot
|
|
community.general.proxmox_snap:
|
|
# ... auth params ...
|
|
vmid: 300
|
|
snapname: before-upgrade
|
|
state: absent
|
|
```
|
|
|
|
### proxmox_nic
|
|
|
|
```yaml
|
|
- name: Add NIC to VM
|
|
community.general.proxmox_nic:
|
|
api_host: proxmox.example.com
|
|
api_user: ansible@pve
|
|
api_token_id: mytoken
|
|
api_token_secret: "{{ proxmox_token_secret }}"
|
|
vmid: 300
|
|
interface: net1
|
|
bridge: vmbr12
|
|
model: virtio
|
|
tag: 12 # VLAN tag
|
|
state: present
|
|
|
|
- name: Remove NIC
|
|
community.general.proxmox_nic:
|
|
# ... auth params ...
|
|
vmid: 300
|
|
interface: net1
|
|
state: absent
|
|
```
|
|
|
|
### proxmox_disk
|
|
|
|
```yaml
|
|
- name: Add disk to VM
|
|
community.general.proxmox_disk:
|
|
api_host: proxmox.example.com
|
|
api_user: ansible@pve
|
|
api_token_id: mytoken
|
|
api_token_secret: "{{ proxmox_token_secret }}"
|
|
vmid: 300
|
|
disk: scsi1
|
|
storage: local-lvm
|
|
size: 50G
|
|
format: raw
|
|
state: present
|
|
|
|
- name: Resize disk
|
|
community.general.proxmox_disk:
|
|
# ... auth params ...
|
|
vmid: 300
|
|
disk: scsi0
|
|
size: +20G # Increase by 20G
|
|
state: resized
|
|
|
|
- name: Detach disk
|
|
community.general.proxmox_disk:
|
|
# ... auth params ...
|
|
vmid: 300
|
|
disk: scsi1
|
|
state: absent
|
|
```
|
|
|
|
## State Reference
|
|
|
|
| Module | States |
|
|
|--------|--------|
|
|
| proxmox (LXC) | present, started, stopped, restarted, absent |
|
|
| proxmox_kvm | present, started, stopped, restarted, absent, current |
|
|
| proxmox_template | present, absent |
|
|
| proxmox_snap | present, absent, rollback |
|
|
| proxmox_nic | present, absent |
|
|
| proxmox_disk | present, absent, resized |
|
|
|
|
## Common Parameters
|
|
|
|
All modules share these authentication parameters:
|
|
|
|
| Parameter | Description |
|
|
|-----------|-------------|
|
|
| api_host | Proxmox hostname/IP |
|
|
| api_user | User (format: user@realm) |
|
|
| api_token_id | API token name |
|
|
| api_token_secret | API token value |
|
|
| validate_certs | Verify TLS (default: true) |
|
|
| timeout | API timeout seconds |
|