Initial commit

2025-11-30 08:47:38 +08:00
commit 18faa0569e
47 changed files with 7969 additions and 0 deletions
--- a/skills/ansible/references/proxmox/modules.md
+++ b/skills/ansible/references/proxmox/modules.md
@@ -0,0 +1,232 @@
+# 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 |