Inventaire dynamique Ansible pour Proxmox VE

L'inventaire dynamique Ansible interroge l'API de Proxmox VE pour lister automatiquement vos VMs et conteneurs, au lieu de maintenir un fichier d'inventaire à la main. À chaque exécution, Ansible récupère l'état réel du cluster (machines, adresses IP, tags, statut) via le plugin community.general.proxmox. Ce guide configure ce plugin avec un token API, teste l'inventaire, puis l'enrichit pour récupérer les IP et grouper les machines par tags. Pour administrateurs qui automatisent un Proxmox avec Ansible.

Ce que vous allez apprendre

• Créer un token API Proxmox pour Ansible.
• Configurer le plugin community.general.proxmox.
• Lister VMs et conteneurs avec ansible-inventory --graph.
• Récupérer les IP via le qemu-guest-agent et grouper par tags.
• Cibler ces groupes dans un playbook.

Prérequis

• Un Proxmox VE accessible (idéalement provisionné avec Terraform).
• Ansible installé et la collection community.general.
• Des VMs avec le qemu-guest-agent actif pour remonter les adresses IP.

Pourquoi un inventaire dynamique

Un inventaire statique (un fichier listant les hôtes) se désynchronise dès qu'une VM est créée, détruite ou change d'IP. L'inventaire dynamique supprime ce problème : il reflète en temps réel l'état du cluster Proxmox. Ansible cible toujours les bonnes machines, sans maintenance manuelle, ce qui est indispensable dès que l'infrastructure bouge souvent.

Créer un token API pour Ansible

Le plugin se connecte à Proxmox avec un token API, plus sûr qu'un mot de passe (révocable, périmètre limité). Créez un utilisateur dédié et son token :

pveum user add ansible@pve
pveum user token add ansible@pve inventory --privsep 0
pveum acl modify / --users ansible@pve --roles PVEAuditor

Le rôle PVEAuditor suffit : l'inventaire n'a besoin que de lire l'état du cluster. Notez le token_id (inventory) et le secret affiché, il ne sera plus jamais réaffiché.

Configurer le plugin Proxmox

Installez la collection si nécessaire :

ansible-galaxy collection install community.general

Créez un fichier d'inventaire dont le nom se termine par .proxmox.yml (par exemple inventory.proxmox.yml) :

plugin: community.general.proxmox
url: https://proxmox.exemple.lan:8006
user: ansible@pve
token_id: inventory
token_secret: "votre-secret-de-token"
validate_certs: false

L'option validate_certs: false accepte le certificat auto-signé par défaut de Proxmox.

Tester l'inventaire

La commande --graph affiche les groupes générés automatiquement par le plugin :

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

@all:
  |--@ungrouped:
  |--@proxmox_all_lxc:
  |--@proxmox_all_qemu:
  |  |--test.exemple.lan
  |--@proxmox_all_running:
  |  |--test.exemple.lan
  |--@proxmox_all_stopped:
  |--@proxmox_nodes:
  |  |--devbox1
  |--@proxmox_devbox1_qemu:
  |  |--test.exemple.lan

Le plugin crée d'office des groupes par type (qemu, lxc), par statut (running, stopped) et par nœud. Pratique pour cibler, par exemple, toutes les VMs en marche.

Récupérer les IP et grouper par tags

Par défaut, l'inventaire ne connaît pas l'adresse IP des machines. On la dérive des interfaces remontées par le qemu-guest-agent, et on crée des groupes à partir des tags Proxmox :

want_proxmox_nodes_ansible_host: true
compose:
  ansible_host: proxmox_agent_interfaces[1]["ip-addresses"][0].split('/')[0]
keyed_groups:
  - key: proxmox_tags_parsed
    separator: ""
groups:
  ubuntu_servers: "'ubuntu' in (proxmox_tags_parsed | list)"

• compose calcule ansible_host à partir de la première IP de la seconde interface (la première étant lo).
• keyed_groups crée un groupe par tag (une VM taguée ubuntu rejoint le groupe ubuntu).
• groups définit un groupe conditionnel ubuntu_servers.

L'agent invité est indispensable

Le compose qui calcule l'IP ne fonctionne que si le qemu-guest-agent est installé et actif dans la VM. Sans lui, proxmox_agent_interfaces est vide et ansible_host reste null.

Relancez avec --list pour voir les facts récupérés (extrait) :

"test.exemple.lan": {
    "ansible_host": "192.168.3.167",
    "proxmox_status": "running",
    "proxmox_tags_parsed": ["ubuntu"],
    "proxmox_vmid": 100,
    "proxmox_vmtype": "qemu"
}

Chaque machine remonte des dizaines de facts (proxmox_cores, proxmox_memory, proxmox_node...), exploitables dans vos playbooks.

Simplifier avec ansible.cfg

Pour éviter de répéter -i inventory.proxmox.yml, créez un ansible.cfg :

[defaults]
inventory = ./inventory.proxmox.yml
host_key_checking = False
forks = 10

[ssh_connection]
pipelining = True

Cibler les groupes dans un playbook

L'inventaire dynamique prend tout son sens dans un playbook qui vise un groupe plutôt que des hôtes nommés. Ici, le groupe ubuntu (créé depuis le tag) :

---
- name: Configuration des serveurs Ubuntu
  hosts: ubuntu
  gather_facts: true
  become: true

  tasks:
    - name: Mettre à jour le cache APT
      ansible.builtin.apt:
        update_cache: true
        cache_valid_time: 3600

ansible-playbook playbook.yml

PLAY RECAP *********************************************************************
test.exemple.lan : ok=2  changed=0  unreachable=0  failed=0

Le playbook s'applique automatiquement à toute machine taguée ubuntu dans Proxmox, sans jamais éditer d'inventaire.

À retenir

• L'inventaire dynamique reflète l'état réel du cluster Proxmox, sans fichier d'hôtes à maintenir.
• Le plugin community.general.proxmox se connecte via un token API (rôle PVEAuditor suffisant).
• Le fichier d'inventaire doit se terminer par .proxmox.yml.
• Le compose récupère l'IP via le qemu-guest-agent ; sans agent, pas d'ansible_host.
• keyed_groups transforme les tags Proxmox en groupes Ansible directement ciblables.

FAQ : questions fréquentes sur l'inventaire dynamique Proxmox

Qu'est-ce qu'un inventaire dynamique Ansible pour Proxmox ?

C'est un inventaire généré automatiquement en interrogeant l'API de Proxmox VE, au lieu d'un fichier d'hôtes maintenu à la main. Le plugin community.general.proxmox liste les VMs et conteneurs avec leur statut, leurs tags et leurs IP, en reflétant l'état réel du cluster à chaque exécution d'Ansible.

Pourquoi l'adresse IP de mes VMs ne remonte pas dans l'inventaire ?

Parce que l'IP est lue depuis les interfaces remontées par le qemu-guest-agent. Si l'agent n'est pas installé ou actif dans la VM, proxmox_agent_interfaces est vide et le compose qui calcule ansible_host renvoie null. Installez et activez qemu-guest-agent dans chaque VM pour obtenir les IP.

Quel rôle donner au token API utilisé par l'inventaire Proxmox ?

Le rôle PVEAuditor suffit : l'inventaire a seulement besoin de lire l'état du cluster. On crée un utilisateur ansible@pve, un token avec privsep 0, et on lui donne PVEAuditor. Un token est plus sûr qu'un mot de passe : révocable et à périmètre limité.

Comment grouper les VMs Proxmox par tags dans Ansible ?

Avec l'option keyed_groups pointant sur proxmox_tags_parsed : chaque tag Proxmox devient un groupe Ansible. Une VM taguée ubuntu rejoint le groupe ubuntu. L'option groups permet en plus des groupes conditionnels comme ubuntu_servers.

Prochaines étapes

Provisionner avec Terraform Créer les VMs Proxmox en amont de la configuration Ansible.

Modules Ansible pour Proxmox Piloter VMs, conteneurs et stockage avec les modules dédiés.

Proxmox VE, qu'est-ce que c'est ? Les fondamentaux de la plateforme.

Ansible La formation Ansible complète.

×

📖 Voir la documentation →