ilia/ansible
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity
ansible/roles/proxmox_vm/README.md
ilia c7a300b922
Some checks failed
CI / lint-and-test (pull_request) Successful in 1m21s
Details
CI / ansible-validation (pull_request) Successful in 9m3s
Details
CI / secret-scanning (pull_request) Successful in 3m19s
Details
CI / dependency-scan (pull_request) Successful in 7m13s
Details
CI / sast-scan (pull_request) Successful in 6m38s
Details
CI / license-check (pull_request) Successful in 1m16s
Details
CI / vault-check (pull_request) Failing after 6m40s
Details
CI / playbook-test (pull_request) Successful in 9m28s
Details
CI / container-scan (pull_request) Successful in 7m59s
Details
CI / sonar-analysis (pull_request) Failing after 1m11s
Details
CI / workflow-summary (pull_request) Successful in 1m11s
Details
Add POTE app project support and improve IP conflict detection 
- Add roles/pote: Python/venv deployment role with PostgreSQL, cron jobs
- Add playbooks/app/: Proxmox app stack provisioning and configuration
- Add roles/app_setup: Generic app deployment role (Node.js/systemd)
- Add roles/base_os: Base OS hardening role
- Enhance roles/proxmox_vm: Split LXC/KVM tasks, improve error handling
- Add IP uniqueness validation: Preflight check for duplicate IPs within projects
- Add Proxmox-side IP conflict detection: Check existing LXC net0 configs
- Update inventories/production/group_vars/all/main.yml: Add pote project config
- Add vault.example.yml: Template for POTE secrets (git key, DB, SMTP)
- Update .gitignore: Exclude deploy keys, backup files, and other secrets
- Update documentation: README, role docs, execution flow guides

Security:
- All secrets stored in encrypted vault.yml (never committed in plaintext)
- Deploy keys excluded via .gitignore
- IP conflict guardrails prevent accidental duplicate IP assignments
2025-12-28 20:54:50 -05:00

2.4 KiB
Raw Blame History

Role: proxmox_vm

Provision Proxmox guests via API. This role supports both:

  • LXC containers (proxmox_guest_type: lxc) via community.proxmox.proxmox
  • KVM VMs (proxmox_guest_type: kvm) via community.general.proxmox_kvm

The entry point is roles/proxmox_vm/tasks/main.yml, which dispatches to tasks/lxc.yml or tasks/kvm.yml.

Requirements

  • Ansible (project tested with modern Ansible; older 2.9-era setups may need adjustments)
  • Proxmox VE API access
  • Collections:
    • community.proxmox
    • community.general (for proxmox_kvm)
  • Python lib on the control machine:
    • proxmoxer (installed by make bootstrap / requirements.txt)

Authentication (vault-backed)

Store secrets in inventories/production/group_vars/all/vault.yml:

  • vault_proxmox_host
  • vault_proxmox_user
  • vault_proxmox_password (or token auth)
  • vault_proxmox_token_id (optional)
  • vault_proxmox_token (optional)
  • vault_ssh_public_key (used for bootstrap access where applicable)

Key variables

Common:

  • proxmox_guest_type: lxc or kvm
  • proxmox_host, proxmox_user, proxmox_node
  • proxmox_api_port (default 8006)
  • proxmox_validate_certs (default false)

LXC (tasks/lxc.yml):

  • lxc_vmid, lxc_hostname
  • lxc_ostemplate (e.g. local:vztmpl/debian-12-standard_*.tar.zst)
  • lxc_storage (default local-lvm)
  • lxc_network_bridge (default vmbr0)
  • lxc_ip (CIDR), lxc_gateway
  • lxc_cores, lxc_memory_mb, lxc_swap_mb, lxc_rootfs_size_gb

KVM (tasks/kvm.yml):

  • vm_id, vm_name
  • vm_cores, vm_memory, vm_disk_size
  • vm_storage, vm_network_bridge
  • cloud-init parameters used by the existing KVM provisioning flow

Safety guardrails

LXC provisioning includes a VMID collision guardrail:

  • If the target VMID already exists but the guest name does not match the expected name, provisioning fails.
  • Override only if you really mean it: -e allow_vmid_collision=true

Example usage

Provisioning is typically orchestrated by playbooks/app/provision_vms.yml, but you can call the role directly:

- name: Provision one LXC
  hosts: localhost
  connection: local
  gather_facts: false
  tasks:
    - name: Create/update container
      ansible.builtin.include_role:
        name: proxmox_vm
      vars:
        proxmox_guest_type: lxc
        lxc_vmid: 9301
        lxc_hostname: projectA-dev
        lxc_ip: "10.0.10.101/24"
        lxc_gateway: "10.0.10.1"