Initial commit

2025-11-30 08:47:38 +08:00
commit 18faa0569e
47 changed files with 7969 additions and 0 deletions
--- a/skills/proxmox/references/automation-tools.md
+++ b/skills/proxmox/references/automation-tools.md
@@ -0,0 +1,179 @@
+# Proxmox Automation Tools
+
+Integration patterns for managing Proxmox with Terraform and Ansible.
+
+## Tool Selection Guide
+
+| Task | Recommended Tool | Rationale |
+|------|-----------------|-----------|
+| VM/LXC provisioning | Terraform | Declarative state, idempotent, handles dependencies |
+| Template creation | Packer | Repeatable builds, version-controlled |
+| Post-boot configuration | Ansible | Agent-based, procedural, good for drift |
+| One-off VM operations | Ansible | Quick tasks, no state file needed |
+| Dynamic inventory | Ansible | Query running VMs for configuration |
+| Bulk VM creation | Terraform | count/for_each, parallel creation |
+| Snapshot management | Either | Terraform for lifecycle, Ansible for ad-hoc |
+| Cluster administration | CLI/API | Direct access for maintenance tasks |
+
+## Terraform Integration
+
+### Provider
+
+```hcl
+terraform {
+  required_providers {
+    proxmox = {
+      source  = "telmate/proxmox"
+      version = "~> 3.0"
+    }
+  }
+}
+
+provider "proxmox" {
+  pm_api_url          = "https://proxmox.example.com:8006/api2/json"
+  pm_api_token_id     = "terraform@pve!mytoken"
+  pm_api_token_secret = var.pm_api_token_secret
+}
+```
+
+### Common Patterns
+
+```hcl
+# Clone from template
+resource "proxmox_vm_qemu" "vm" {
+  name        = "myvm"
+  target_node = "joseph"
+  clone       = "tmpl-ubuntu-2404-standard"
+  full_clone  = true
+
+  cores   = 2
+  memory  = 4096
+
+  disks {
+    scsi {
+      scsi0 {
+        disk {
+          storage = "local-lvm"
+          size    = "50G"
+        }
+      }
+    }
+  }
+}
+```
+
+### Skill Reference
+
+Load terraform skill for detailed patterns:
+- `terraform/references/proxmox/gotchas.md` - Critical issues
+- `terraform/references/proxmox/vm-qemu.md` - VM resource patterns
+- `terraform/references/proxmox/authentication.md` - API setup
+
+## Ansible Integration
+
+### Collection
+
+```bash
+ansible-galaxy collection install community.general
+```
+
+### Common Patterns
+
+```yaml
+# Clone VM
+- name: Clone 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
+    timeout: 500
+
+# Start VM
+- name: Start VM
+  community.general.proxmox_kvm:
+    # ... auth ...
+    vmid: 300
+    state: started
+```
+
+### Skill Reference
+
+Load ansible skill for detailed patterns:
+- `ansible/references/proxmox/modules.md` - All Proxmox modules
+- `ansible/references/proxmox/gotchas.md` - Common issues
+- `ansible/references/proxmox/dynamic-inventory.md` - Auto-discovery
+
+## Terraform vs Ansible Decision
+
+### Use Terraform When
+
+- Creating infrastructure from scratch
+- Managing VM lifecycle (create, update, destroy)
+- Need state tracking and drift detection
+- Deploying multiple similar VMs (for_each)
+- Complex dependencies between resources
+- Team collaboration with state locking
+
+### Use Ansible When
+
+- Configuring VMs after creation
+- Ad-hoc operations (start/stop specific VMs)
+- Dynamic inventory needed for other playbooks
+- Quick one-off tasks
+- No state file management desired
+- Integration with existing Ansible workflows
+
+### Use Both When
+
+- Terraform provisions VMs
+- Ansible configures them post-boot
+- Ansible uses Proxmox dynamic inventory to find Terraform-created VMs
+
+## Hybrid Workflow Example
+
+```
+1. Packer builds VM template
+   └── packer build ubuntu-2404.pkr.hcl
+
+2. Terraform provisions VMs from template
+   └── terraform apply
+   └── Outputs: VM IPs, hostnames
+
+3. Ansible configures VMs
+   └── Uses Proxmox dynamic inventory OR
+   └── Uses Terraform output as inventory
+
+4. Ongoing management
+   └── Terraform for infrastructure changes
+   └── Ansible for configuration drift
+```
+
+## API Token Sharing
+
+Both tools can share the same API token:
+
+```bash
+# Create shared token
+pveum user add automation@pve
+pveum aclmod / -user automation@pve -role PVEAdmin
+pveum user token add automation@pve shared --privsep 0
+```
+
+Store in shared secrets management (1Password, Vault, etc.).
+
+## Common Gotchas
+
+| Issue | Terraform | Ansible |
+|-------|-----------|---------|
+| VMID | Auto-assigns if not specified | Must specify manually |
+| Cloud-init changes | Use replace_triggered_by | Limited support, use API |
+| State tracking | Yes (tfstate) | No state file |
+| Parallel operations | Yes (configurable) | Yes (forks) |
+| Template name vs ID | Supports both | Supports both |
+| Timeout handling | Provider config | Module parameter |