Inventaire dynamique Proxmox VE avec community.general.proxmox

Pour un homelab ou une PME sous Proxmox VE, le plugin community.general.proxmox est la solution la plus complète. Contrairement à libvirt qui ne retourne que les noms de VMs, le plugin Proxmox récupère les VMs, les conteneurs LXC, leurs IPs (via l’agent QEMU), leurs tags Proxmox — tout en une seule API call.

Cette page est didactique — elle suppose un cluster Proxmox déjà déployé.

Ce que vous allez apprendre

Configurer le plugin avec un token API Proxmox (sans password).
Lister VMs et conteneurs LXC dans un même inventaire.
Récupérer les IPs automatiquement via l’agent QEMU.
Grouper par tag Proxmox, par node Proxmox, par état.
Anticiper les pièges (agent QEMU absent, tokens permissions).

Prérequis

Un cluster ou serveur Proxmox VE 7+ opérationnel.
Token API Proxmox créé (procédure ci-dessous).
community.general collection installée.
requests Python côté control node : pip install requests.

Création d’un token API Proxmox

Plutôt qu’un mot de passe (renouvellement, MFA, audit), utiliser un token API dédié à Ansible.

Sur l’interface Proxmox web : Datacenter → Permissions → API Tokens → Add.

Champ	Valeur
User	`ansible@pve` (créer ce user au préalable)
Token ID	`inventory`
Privilege Separation	Décocher (sinon il faut donner les rôles séparément)
Expire	Date d’expiration (recommandé : 1 an)

À la création, Proxmox affiche le token secret une seule fois — copier immédiatement, vous ne pourrez plus le voir.

Permissions minimales requises : PVEAuditor (lecture seule sur tous les paths) — suffit pour l’inventaire dynamique.

Configuration minimale

Créer inventory/proxmox.yml :

---
plugin: community.general.proxmox
url: https://proxmox.example.com:8006
user: ansible@pve
token_id: inventory
token_secret: !vault |
  $ANSIBLE_VAULT;1.1;AES256
  3736...
validate_certs: true

Le token_secret doit être chiffré avec Ansible Vault :

ansible-vault encrypt_string '<le-secret-token>' --name token_secret

Coller le résultat dans le YAML. Le déchiffrement se fait au runtime avec --ask-vault-pass.

Inclure VMs et LXC

Par défaut, le plugin ne liste que les VMs (KVM). Pour inclure aussi les conteneurs LXC :

plugin: community.general.proxmox
url: https://proxmox.example.com:8006
user: ansible@pve
token_id: inventory
token_secret: !vault | ...

want_facts: true                    # détails complets de chaque VM/LXC
want_proxmox_nodes_ansible_host: false   # ne pas définir ansible_host depuis Proxmox

Tester :

ansible-inventory -i inventory/proxmox.yml --graph

Sortie :

@all:
  |--@proxmox_lab:                   # le cluster Proxmox
  |--@proxmox_node_pve01:            # un node du cluster
  |  |--vm-100
  |  |--vm-101
  |--@proxmox_running:               # VMs en cours d'exécution
  |  |--vm-100
  |--@proxmox_lxc:                   # conteneurs LXC
  |  |--ct-200

Récupérer les IPs via l’agent QEMU

L’avantage majeur de Proxmox sur libvirt : si l’agent QEMU est installé sur les VMs, le plugin récupère leurs IPs automatiquement.

Sur chaque VM Proxmox :

# RHEL/Alma/Rocky
sudo dnf install -y qemu-guest-agent
sudo systemctl enable --now qemu-guest-agent

# Debian/Ubuntu
sudo apt install -y qemu-guest-agent
sudo systemctl enable --now qemu-guest-agent

Côté Proxmox, activer l’agent dans la config de la VM (interface web : Hardware → QEMU Guest Agent → Enabled, ou en CLI qm set <VMID> --agent enabled=1).

Une fois ça en place :

ansible-inventory -i inventory/proxmox.yml --host vm-100 | grep -i ip

Vous voyez les IPs réelles de la VM (privée et publique si configurées).

Grouper par tags Proxmox

Proxmox 7+ supporte les tags sur chaque VM/LXC. Le plugin les utilise comme keyed_groups :

plugin: community.general.proxmox
url: https://proxmox.example.com:8006
user: ansible@pve
token_id: inventory
token_secret: !vault | ...

want_facts: true

keyed_groups:
  # Un groupe par tag Proxmox
  - prefix: tag
    key: proxmox_tags_parsed
    parent_group: lab_vms

Si une VM a les tags Proxmox prod;web, elle rejoint les groupes tag_prod et tag_web. Pratique pour grouper sans toucher à l’inventaire YAML.

Cache pour éviter les API calls répétés

plugin: community.general.proxmox
url: https://proxmox.example.com:8006
user: ansible@pve
token_id: inventory
token_secret: !vault | ...

cache: true
cache_plugin: jsonfile
cache_timeout: 300
cache_connection: /tmp/ansible_proxmox_cache

Sur un cluster avec 50+ VMs, le cache divise par 5 le temps de chaque commande Ansible.

Configuration SSH des VMs

Comme libvirt, le plugin Proxmox ne fournit pas directement les paramètres SSH (utilisateur, clé). Utiliser host_vars/ :

inventory/
├── proxmox.yml
└── host_vars/
    ├── vm-100.yml
    └── vm-101.yml

host_vars/vm-100.yml :

ansible_user: ansible
ansible_ssh_private_key_file: ~/.ssh/lab_ed25519

Ou plus malin : utiliser compose: pour calculer ansible_user selon le tag Proxmox :

compose:
  ansible_user: "'ec2-user' if 'aws' in proxmox_tags_parsed else 'ansible'"

Variables exposées

Le plugin expose toute la config Proxmox de la VM :

- debug:
    msg: |
      VM {{ inventory_hostname }} :
      - Type   : {{ proxmox_vmtype }}      # qemu ou lxc
      - State  : {{ proxmox_status }}       # running, stopped
      - Memory : {{ proxmox_memory }} MB
      - Cores  : {{ proxmox_cores }}
      - Node   : {{ proxmox_node }}         # pve01, pve02...
      - Tags   : {{ proxmox_tags_parsed }}
      - IPs    : {{ proxmox_agent_interfaces | default('agent absent') }}

Toutes les variables Proxmox sont préfixées proxmox_ pour éviter les collisions.

Filtrer les VMs

Pour ne garder que certaines VMs (ex: avec un tag spécifique), utiliser groups: Jinja :

plugin: community.general.proxmox
url: https://proxmox.example.com:8006
user: ansible@pve
token_id: inventory
token_secret: !vault | ...

groups:
  managed_vms: "'ansible' in (proxmox_tags_parsed | default([]))"
  prod_vms: "'prod' in (proxmox_tags_parsed | default([]))"

Maintenant ansible managed_vms -m ping cible uniquement les VMs taggées ansible côté Proxmox. Les autres sont ignorées.

Pièges courants

Symptôme	Cause	Fix
`requests module not found`	Module Python manquant	`pip install requests`
`Authentication failed`	Token mal configuré ou expiré	Re-créer le token avec `Privilege Separation` décoché
Pas d’IPs retournées	Agent QEMU absent ou désactivé	Installer `qemu-guest-agent` + activer côté Proxmox (`qm set`)
Permissions insuffisantes	Token sans rôle approprié	Donner `PVEAuditor` au user `ansible@pve`
`validate_certs: true` plante	Certificat self-signed Proxmox	`validate_certs: false` (lab) ou trust le cert (prod)
Lent au démarrage	Cluster avec beaucoup de nodes	Activer le cache + filtrer avec `groups:`

Comparaison libvirt vs Proxmox

Critère	libvirt	Proxmox
Setup	Local (qemu:///system)	Token API + URL
VMs	Oui	Oui
LXC	Non	Oui
IPs	Non sans agent QEMU	Oui (avec agent QEMU)
Tags	Manuel via `groups:`	Tags Proxmox natifs
Multi-host	Non (one host = one libvirt)	Oui (cluster Proxmox)
Cas d’usage	Bare-metal homelab	Cluster Proxmox

À retenir

community.general.proxmox = solution la plus complète pour homelab Proxmox.
Token API > password — créer un user dédié ansible@pve + token inventory.
Token secret chiffré avec Ansible Vault — jamais en clair.
Agent QEMU indispensable pour récupérer les IPs automatiquement.
VMs + LXC dans un même inventaire (avantage majeur sur libvirt).
Tags Proxmox = grouping natif via keyed_groups: proxmox_tags_parsed.
PVEAuditor = permissions minimales suffisantes (lecture seule).

Prochaines étapes

Plugin libvirt pour KVM Alternative pour bare-metal KVM (sans Proxmox)

Plugin AWS EC2 Pour basculer en cloud public — patterns proches

Plugin NetBox Source de vérité IPAM/DCIM si vous l'utilisez en parallèle de Proxmox

Modules runtime (add_host) Provisionner avec community.general.proxmox_kvm + add_host pour configurer immédiatement